QTranslator Class
La clase QTranslator ofrece soporte para la internacionalización de la salida de texto. Más información...
| Encabezado: | #include <QTranslator> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredan: | QObject |
Funciones públicas
| QTranslator(QObject *parent = nullptr) | |
| virtual | ~QTranslator() |
| QString | filePath() const |
| virtual bool | isEmpty() const |
| QString | language() const |
| bool | load(const QString &filename, const QString &directory = QString(), const QString &search_delimiters = QString(), const QString &suffix = QString()) |
| bool | load(const QLocale &locale, const QString &filename, const QString &prefix = QString(), const QString &directory = QString(), const QString &suffix = QString()) |
| bool | load(const uchar *data, int len, const QString &directory = QString()) |
| virtual QString | translate(const char *context, const char *sourceText, const char *disambiguation = nullptr, int n = -1) const |
Descripción detallada
Un objeto de esta clase contiene un conjunto de traducciones de un idioma de origen a un idioma de destino. QTranslator proporciona funciones para buscar traducciones en un archivo de traducción. Los archivos de traducción se crean utilizando Qt Linguist.
El uso más habitual de QTranslator es cargar un archivo de traducción e instalarlo mediante QCoreApplication::installTranslator().
A continuación se muestra un ejemplo de la función ` main() ` que utiliza `QTranslator`:
// Required for using the '_L1' string literal.
using namespace Qt::StringLiterals;
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QTranslator translator;
// look up e.g. :/i18n/myapp_de.qm
if (translator.load(QLocale(), "myapp"_L1, "_"_L1, ":/i18n"_L1))
QCoreApplication::installTranslator(&translator);
QPushButton hello(QCoreApplication::translate("main", "Hello world!"));
hello.resize(100, 30);
hello.show();
return app.exec();
}Ten en cuenta que el traductor debe crearse antes que los widgets de la aplicación.
La mayoría de las aplicaciones nunca necesitarán hacer nada más con esta clase. Las demás funciones que ofrece esta clase son útiles para aplicaciones que trabajan con archivos de traducción.
Búsqueda de traducciones
Es posible buscar una traducción utilizando translate() (tal y como lo hacen tr() y QCoreApplication::translate()). La función translate() admite hasta tres parámetros:
- El contexto: normalmente el nombre de la clase que invoca tr().
- El texto de origen: suele ser el argumento de tr().
- La desambiguación: una cadena opcional que ayuda a desambiguar los diferentes usos del mismo texto en el mismo contexto.
Por ejemplo, el «Cancel» de un cuadro de diálogo podría aparecer como «Anuluj» cuando el programa se ejecuta en polaco (en este caso, el texto de origen sería «Cancel»). El contexto sería (normalmente) el nombre de la clase del cuadro de diálogo; normalmente no habría ningún comentario, y el texto traducido sería «Anuluj».
Pero no siempre es tan sencillo. La versión en español de un cuadro de diálogo de la impresora con opciones para la impresión a doble cara y la encuadernación probablemente requeriría tanto «Activado» como «Activada» como traducciones de «Enabled». En este caso, el texto de origen sería «Enabled» en ambos casos, y el contexto sería el nombre de la clase del cuadro de diálogo, pero los dos elementos tendrían distinciones como «impresión a doble cara» para uno y «encuadernación» para el otro. La aclaración permite al traductor elegir el género adecuado para la versión en español y permite a Qt distinguir entre las traducciones.
Uso de traducciones múltiples
Se pueden instalar varios archivos de traducción en una aplicación. Las traducciones se buscan en el orden inverso al de su instalación, de modo que primero se busca en el archivo de traducción instalado más recientemente y, por último, en el más antiguo. La búsqueda se detiene en cuanto se encuentra una traducción que contenga una cadena coincidente.
Este mecanismo permite «seleccionar» una traducción específica o darle prioridad sobre las demás; basta con desinstalar el traductor de la aplicación pasándolo a la función ` QCoreApplication::removeTranslator()` y reinstalarlo con ` QCoreApplication::installTranslator()`. De este modo, será la primera traducción en la que se buscarán las cadenas coincidentes.
Consideraciones de seguridad
Instala únicamente archivos de traducción procedentes de fuentes fiables.
Los archivos de traducción son archivos binarios generados a partir de archivos fuente de traducción basados en texto. El formato de estos archivos binarios está estrictamente definido por Qt y cualquier manipulación de los datos del archivo binario puede provocar un fallo de la aplicación al cargar el archivo. Además, incluso los archivos de traducción correctamente formados pueden contener traducciones engañosas o maliciosas.
Véase también QCoreApplication::installTranslator(), QCoreApplication::removeTranslator(), QObject::tr(), QCoreApplication::translate(), Ejemplo de reloj localizado, Ejemplo de teclado de flechas y Ejemplo de impresión de troll.
Documentación de las funciones de miembro
[explicit] QTranslator::QTranslator(QObject *parent = nullptr)
Crea un objeto de archivo de mensajes vacío cuyo padre es parent y que no está vinculado a ningún archivo.
[virtual noexcept] QTranslator::~QTranslator()
Destruye el objeto y libera los recursos asignados.
QString QTranslator::filePath() const
Devuelve la ruta del archivo de traducción cargado.
La ruta del archivo estará vacía si aún no se ha cargado ninguna traducción, si la carga ha fallado o si la traducción no se ha cargado desde un archivo.
[virtual] bool QTranslator::isEmpty() const
Devuelve « true » si este traductor está vacío; en caso contrario, devuelve « false ».
QString QTranslator::language() const
Devuelve el idioma de destino tal y como figura en el archivo de traducción.
bool QTranslator::load(const QString &filename, const QString &directory = QString(), const QString &search_delimiters = QString(), const QString &suffix = QString())
Carga filename + suffix («.qm» si no se especifica suffix ), que puede ser un nombre de archivo absoluto o relativo a directory. Devuelve true si la traducción se ha cargado correctamente; en caso contrario, devuelve false.
Si no se especifica directory, se utiliza el directorio actual (es decir, como currentPath()).
Se descarta el contenido anterior de este objeto traductor.
Si el nombre del archivo no existe, se prueban otros nombres de archivo en el siguiente orden:
- Nombre de archivo sin « suffix » añadido al final.
- Nombre de archivo con el texto situado después de un carácter en search_delimiters eliminado («_.» es el valor por defecto para search_delimiters si se trata de una cadena vacía) y suffix.
- Nombre de archivo sin el sufijo « suffix ».
- Nombre de archivo con el texto eliminado aún más, etc.
Por ejemplo, una aplicación que se ejecute en la configuración regional fr_CA (Canadá francófono) podría llamar a load("foo.fr_ca", "/opt/foolib"). load() intentaría entonces abrir el primer archivo legible existente de esta lista:
/opt/foolib/foo.fr_ca.qm/opt/foolib/foo.fr_ca/opt/foolib/foo.fr.qm/opt/foolib/foo.fr/opt/foolib/foo.qm/opt/foolib/foo
Por lo general, es mejor utilizar la función `QTranslator::load(const QLocale &, const QString &, const QString &, const QString &, const QString &)`, ya que utiliza ` QLocale::uiLanguages()` y no simplemente el nombre de la configuración regional, que hace referencia al formato de fechas y números y no necesariamente al idioma de la interfaz de usuario.
bool QTranslator::load(const QLocale &locale, const QString &filename, const QString &prefix = QString(), const QString &directory = QString(), const QString &suffix = QString())
Carga filename + prefix + ui language name + suffix (».qm» si no se especifica suffix ), que puede ser un nombre de archivo absoluto o relativo a directory. Devuelve true si la traducción se ha cargado correctamente; en caso contrario, devuelve false.
Se descarta el contenido anterior de este objeto traductor.
Si el nombre de archivo no existe, se prueban otros nombres de archivo en el siguiente orden:
- Nombre de archivo sin « suffix » añadido.
- Nombre de archivo sin la parte correspondiente al idioma de la interfaz de usuario tras el carácter «_» y « suffix ».
- Nombre de archivo sin la parte correspondiente al idioma de la interfaz de usuario y sin « suffix » añadido.
- Nombre de archivo al que se le ha eliminado además la parte del idioma de la interfaz de usuario, etc.
Por ejemplo, una aplicación que se ejecute en el locale con los siguientes ui languages —«es», «fr-CA», «de»— podría llamar a load(QLocale(), «foo», «.», «/opt/foolib», «.qm»). La función load() sustituiría el «-» (guión) por «_» (guión bajo) en el idioma de la interfaz de usuario y, a continuación, intentaría abrir el primer archivo legible existente de esta lista:
/opt/foolib/foo.es.qm/opt/foolib/foo.es/opt/foolib/foo.fr_CA.qm/opt/foolib/foo.fr_CA/opt/foolib/foo.fr.qm/opt/foolib/foo.fr/opt/foolib/foo.de.qm/opt/foolib/foo.de/opt/foolib/foo.qm/opt/foolib/foo./opt/foolib/foo
En los sistemas operativos en los que el sistema de archivos distingue entre mayúsculas y minúsculas, QTranslator también intenta cargar una versión en minúsculas del nombre de la configuración regional.
bool QTranslator::load(const uchar *data, int len, const QString &directory = QString())
Carga los datos del archivo QM data, de longitud len, en el traductor.
Los datos no se copian. El usuario que realiza la llamada debe poder garantizar que data no se eliminará ni se modificará.
directory Solo se utiliza para especificar el directorio base al cargar las dependencias de un archivo QM. Si el archivo no tiene dependencias, se ignora este argumento.
Esta función sobrecarga QTranslator::load().
[virtual] QString QTranslator::translate(const char *context, const char *sourceText, const char *disambiguation = nullptr, int n = -1) const
Devuelve la traducción correspondiente a la clave (context, sourceText, disambiguation). Si no se encuentra ninguna, también prueba con (context, sourceText, ""). Si sigue sin funcionar, devuelve una cadena nula.
Nota: Las traduccionesincompletas pueden dar lugar a un comportamiento inesperado: si no se proporciona ninguna traducción para (context, sourceText, ""), el método podría, en este caso, devolver en realidad una traducción para un disambiguation diferente.
Si n no es -1, se utiliza para elegir una forma adecuada para la traducción (por ejemplo, «%n archivo encontrado» frente a «%n archivos encontrados»).
Si necesitas insertar traducciones mediante programación en un ` QTranslator`, esta función se puede reimplementar.
Nota: Esta función es segura para subprocesos.
Véase también load().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.