Cómo escribir código fuente para su traducción
Escribe el código fuente QML y Qt C++ de forma que permita localizar las aplicaciones:
- Marcar cadenas para su traducción
- Utiliza parámetros en lugar de concatenar cadenas
- Gestionar las formas plurales
- Utiliza la configuración numérica regional
- Internacionalizar la fecha, la hora y la moneda
- Marcar las cadenas de texto con datos traducibles
- Añade comentarios para los traductores
- Resolver ambigüedades en textos idénticos
- Hacer que los atajos de teclado sean traducibles
- Utilizar la configuración regional para ampliar las funciones de localización
- Habilitar la traducción
- Prepararse para cambios dinámicos de idioma
Al desarrollar aplicaciones en C++, consulta también «Consideraciones adicionales para el código C++».
Marcar cadenas para su traducción
La mayor parte del texto que debe traducirse en una aplicación consiste en palabras sueltas o frases cortas. Estas suelen aparecer como títulos de ventanas, elementos de menú, información sobre herramientas y etiquetas de botones, casillas de verificación y botones de opción.
Qt minimiza el coste de rendimiento que supone el uso de traducciones traduciendo las frases de cada ventana a medida que se crean. En la mayoría de las aplicaciones, la ventana principal se crea una sola vez. Los cuadros de diálogo suelen crearse una vez y, a continuación, mostrarse y ocultarse según sea necesario. Una vez realizada la traducción inicial, no hay más sobrecarga en tiempo de ejecución para las ventanas traducidas. Solo aquellas ventanas que se crean, se destruyen y posteriormente se vuelven a crear tendrán un coste de rendimiento en la traducción.
Se pueden crear aplicaciones que cambien de idioma en tiempo de ejecución, pero ello requiere un esfuerzo adicional y conlleva un coste de rendimiento en tiempo de ejecución.
Utiliza funciones de traducción para marcar el texto de la interfaz de usuario visible para el usuario con el fin de traducirlo en código QML y C++. Qt admite dos enfoques para identificar el texto traducible: basado en texto y basado en ID.
En el enfoque de traducción basado en texto, Qt indexa cada cadena traducible según el contexto de traducción y, opcionalmente, un comentario de desambiguación asociado a ella. La misma frase puede aparecer en más de un contexto sin que se produzca ningún conflicto. Si una frase aparece más de una vez en un contexto concreto, se traduce únicamente una vez y la traducción se aplica a todas las apariciones dentro de ese contexto.
En el enfoque de traducción basado en identificadores, cada traducción se identifica de forma única mediante un identificador explícito. Los identificadores son únicos en todo el proyecto. Si un identificador aparece más de una vez en un proyecto, se traduce solo una vez y la traducción se aplica a todas las apariciones dentro del proyecto.
QML
En QML, puedes utilizar las siguientes funciones para marcar las cadenas visibles para el usuario que deben traducirse en los archivos .qml:
- qsTr(): Traducción basada en texto
- qsTranslate(): Traducción basada en texto
- qsTrId(): Traducción basada en ID
qsTr(): basada en texto
Text {
id: txt1
text: qsTr("Back")
}Este código convierte «Back» en una entrada clave en los archivos de origen de traducción (TS). En tiempo de ejecución, el sistema de traducción busca la palabra clave «Back» en el contexto actual (véase más abajo) y, a continuación, obtiene el valor de traducción correspondiente para la configuración regional actual del sistema. El resultado se devuelve a la propiedad « text » y la interfaz de usuario muestra la traducción adecuada de «Back» para la configuración regional actual. Si no se encuentra ninguna traducción, « qsTr() » devuelve la cadena original.
El contexto de traducción se puede establecer para un archivo determinado con:
pragma Translator: ChosenContexto
pragma Translator: "Chosen::Context"El contexto establecido mediante ` qsTranslate() ` tiene prioridad sobre el establecido mediante ` pragma ` Translator. En QML, por defecto, el contexto de traducción es el nombre del archivo.
qsTrId() basado en ID:
Text {
id: txt1
//% "Back"
text: qsTrId("BackID")
}Este código convierte «BackID» en una entrada clave única en los archivos de origen de traducción (TS) y escribe «Back» como texto de origen. En tiempo de ejecución, el sistema de traducción busca el ID «BackID» y, a continuación, obtiene el valor de traducción correspondiente (o, si no está traducido, el texto de origen) para la configuración regional actual del sistema. El resultado se devuelve a la propiedad ` text ` y la interfaz de usuario muestra la traducción adecuada de «BackID» para la configuración regional actual. Si no se encuentra ninguna entrada con el ID «BackID» en los archivos TS, ` qsTrId() ` devuelve el propio ID. Esto no debería ocurrir en condiciones normales.
C++
En C++, puedes utilizar las siguientes funciones para marcar las cadenas visibles para el usuario para su traducción:
- tr(): Traducción basada en texto
- QCoreApplication::translate(): Traducción basada en texto
- QTranslator::translate(): Traducción basada en texto
- qtTrId(): Traducción basada en ID
- Para más opciones, consulta linguist-id-based-i18n.html
tr() basada en texto
Utiliza la función ` tr()` para marcar el texto como traducible y para mostrar el texto traducido. El contexto de traducción es el nombre de la subclase de ` QObject ` en la que se utiliza la cadena. Para definir el contexto de traducción para nuevas clases basadas en ` QObject`, utiliza la macro ` Q_OBJECT ` en cada nueva definición de clase.
Cuando se llama a ` tr() `, esta busca la cadena traducible utilizando un objeto ` QTranslator `, que debe instalarse en el objeto de la aplicación, tal y como se describe en «Habilitar la traducción».
Por ejemplo, suponiendo que ` LoginWidget ` sea una subclase de ` QWidget`:
Esto abarca el 99 % de las cadenas visibles para el usuario que probablemente escribas. Para obtener información sobre cómo marcar literales de cadena como traducibles, consulta «Marcar cadenas de texto de datos como traducibles».
Si el texto entre comillas no se encuentra en una función miembro de una subclase de ` QObject `, utiliza la función ` tr() ` de la clase adecuada o la función ` QCoreApplication::translate()` directamente:
void some_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
LoginWidget::tr("Password:"), logwid);
}
void same_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
QCoreApplication::translate("LoginWidget", "Password:"), logwid);
}qtTrId() basada en ID
qtTrId() devuelve una cadena traducida identificada por un ID. Así, en lugar de escribir la propia cadena traducible en la función, se escribe el ID de la traducción. El texto de origen (cadena por defecto) se escribe utilizando la notación de metacadena //%. Si el texto no está traducido, se devuelve el texto de origen anotado por //%. Si no se encuentra ningún ID coincidente, se devuelve el propio ID. Esto no debería ocurrir en condiciones normales.
Este código convierte «PasswordID» en una entrada clave única en los archivos de origen de traducción (TS) y escribe «Password:» como texto original. En tiempo de ejecución, el sistema de traducción busca el ID «PasswordID» y, a continuación, obtiene el valor de traducción correspondiente (o, si no está traducido, el texto original) para la configuración regional actual del sistema.
Nota: Si desactivas la conversión automática de const char * a QString al compilar tu aplicación con la macro QT_NO_CAST_FROM_ASCII definida, lo más probable es que detectes cualquier cadena que te falte. Consulta QString::fromUtf8() y QString::fromLatin1() para obtener más información.
Utiliza parámetros en lugar de concatenar cadenas
Los distintos idiomas organizan las palabras de forma diferente en frases, cláusulas y oraciones, por lo que no debes crear cadenas concatenando palabras y datos. En su lugar, utiliza % para insertar parámetros en las cadenas.
Por ejemplo, en la cadena After processing file %1, file %2 is next in line, %1 y %2 son parámetros numerados. En tiempo de ejecución, %1 y %2 se sustituyen por el primer y el segundo nombre de archivo, respectivamente. Los mismos parámetros numerados deben aparecer en la traducción, pero no necesariamente en el mismo orden. Una traducción al alemán de la cadena podría invertir el orden de las frases. Por ejemplo: Datei %2 wird bearbeitet, wenn Datei %1 fertig ist. Ambos parámetros numerados aparecen en la traducción, pero en orden inverso.
QML: Utiliza .arg()
El siguiente fragmento de código QML contiene una cadena con dos parámetros numerados: %1 y %2. Estos parámetros se insertan mediante las funciones .arg().
Text {
text: qsTr("File %1 of %2").arg(counter).arg(total)
}%1 se refiere al primer parámetro y %2 al segundo, por lo que este código genera un resultado del tipo: Archivo 2 de 3.
Evita utilizar cadenas de plantilla con argumentos, ya que la cadena resultante se define en tiempo de ejecución, en lugar de en tiempo de compilación. Como consecuencia, las herramientas de traducción no pueden encontrar la traducción correcta para las cadenas de plantilla.
C++: Utiliza QString::arg()
En C++, utiliza las funciones QString::arg() para sustituir parámetros:
void FileCopier::showProgress(int done, int total,
const QString ¤tFile)
{
label.setText(tr("%1 of %2 files copied.\nCopying: %3")
.arg(done)
.arg(total)
.arg(currentFile));
}Este código genera un resultado del tipo: 5 de 10 archivos copiados. Copiando: somefile.txt.
Gestión de formas plurales
Puedes pasar un parámetro entero adicional (n) a las funciones de traducción y utilizar una notación especial para las formas plurales (%n) en cada cadena traducible.
Dependiendo del valor de n, la función de traducción devuelve una traducción diferente, con el número gramatical correcto para el idioma de destino. Además, cualquier aparición de « %n » se sustituye por el valor de n.
Por ejemplo, las traducciones al inglés y al francés de la cadena « %n message(s) saved » requieren formas de plural diferentes.
| n | Sin traducción | Francés | Inglés |
|---|---|---|---|
| 0 | «0 mensajes guardados» | «0 mensaje guardado» | «0mensajes guardados» |
| 1 | «1 mensaje(s) guardado(s)» | «1 mensaje guardado» | «1 mensaje guardado» |
| 2 | «2 mensajes guardados» | «2mensajesguardados» | «2mensajes guardados» |
| 37 | «37 mensajes guardados» | «37mensajesguardados» | «37mensajes guardados» |
Esta expresión también funciona con idiomas de destino que tienen varias formas de plural, como la forma dual. Además, la expresión gestiona correctamente el caso «n == 0 » para idiomas como el francés, que requieren el singular.
Para obtener un resumen de las reglas que utilizan Qt Linguist y lrelease para traducir cadenas que contienen formas plurales, consulta Reglas de traducción para formas plurales.
Para gestionar las formas plurales en el idioma de origen, cargue también un archivo TS para este idioma. Utilice la opción de línea de comandos -pluralonly de la herramienta lupdate para crear archivos TS que contengan únicamente entradas con formas plurales.
Como alternativa, puede utilizar la opción de línea de comandos « -pluralonly » de la herramienta « lconvert » para eliminar todas las formas no plurales de un archivo TS existente.
Ejemplo en QML
El siguiente fragmento de código QML traduce el texto de origen a la forma plural correcta y sustituye %n por el valor de total:
Text {
text: qsTr("%n message(s) saved", "", total)
}Ejemplo en C++
El siguiente fragmento de código en C++ sustituye « %n » por el valor que devuelve la función « count() »:
int n = messages.count();
showMessage(tr("%n message(s) saved", "", n));Utilizar la configuración numérica regional
Si se incluye el modificador %L al especificar un parámetro, el número se localiza según la configuración regional actual. La conversión utiliza la configuración regional predeterminada si se ha establecido, o la configuración regional del sistema en caso contrario.
QML: Utilizar %L
Por ejemplo, en el siguiente fragmento de código QML, %L1 formatea el primer parámetro según las convenciones de formato numérico de la configuración regional (región geográfica) seleccionada actualmente:
Text {
text: qsTr("%L1").arg(total)
}Si total es el número 4321,56, con la configuración regional (locale) en inglés el resultado es 4.321,56, mientras que con la configuración regional en alemán es 4.321,56.
C++: Utiliza %Ln
En C++, puedes utilizar ` %Ln ` para generar una representación localizada de ` n`. Utiliza ` QLocale::setDefault()` para establecer la configuración regional por defecto.
Internacionalizar la fecha, la hora y la moneda
Presenta la fecha, la hora y la moneda utilizando los formatos preferidos localmente.
QML: Utiliza las funciones de QtQml
QML no dispone de modificadores especiales dentro de las cadenas para dar formato a fechas y horas. En su lugar, es necesario consultar la configuración regional actual (región geográfica) y utilizar los métodos de Date para dar formato a la cadena.
Qt.locale() devuelve un objeto ` Locale ` que contiene información sobre la configuración regional. En concreto, la propiedad ` Locale.name ` contiene el idioma y el país de la configuración regional actual. Puedes utilizar el valor tal cual o analizarlo para determinar el contenido adecuado para la configuración regional actual.
El siguiente fragmento de código obtiene la fecha y la hora actuales con ` Date()`, y luego las convierte en una cadena adaptada a la configuración regional actual. A continuación, inserta la cadena de fecha en el parámetro ` %1 ` para obtener la traducción adecuada.
Text {
text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale()))
}Para localizar valores monetarios, utiliza el tipo `Number `. Tiene funciones similares a las del tipo ` Date ` para convertir números en cadenas monetarias localizadas.
C++: Utiliza la clase QLocale
En C++, utilice QLocale::timeFormat() o QLocale::toString(QTime) o toString(QDate):
QLabel *label = new QLabel(this);
label->setText(tr("Date %1").arg(QLocale().toString(QDate::currentDate()));Marcar cadenas de texto de datos traducibles
Utilice las funciones _NOOP (en QML) y las macros _NOOP (en C++) para marcar las cadenas literales traducibles y que la herramienta lupdate pueda extraerlas.
QML: Utiliza las funciones _NOOP
En QML, utiliza las siguientes funciones para marcar las cadenas literales traducibles:
Si el usuario cambia el idioma del sistema sin reiniciar el equipo, dependiendo del sistema, es posible que las cadenas de los arrays, los modelos de lista y otras estructuras de datos no se actualicen automáticamente. Para forzar la actualización de los textos cuando se muestran en la interfaz de usuario, debes declarar las cadenas con la función ` QT_TR_NOOP() `. A continuación, al rellenar los objetos para su visualización, hay que recuperar explícitamente la traducción de cada texto.
Por ejemplo:
ListModel {
id: myListModel
ListElement {
//: Capital city of Finland
name: QT_TR_NOOP("Helsinki")
}
}
...
Text {
text: qsTr(myListModel.get(0).name)
// Get the translation of the name property in element 0
}C++: Uso de macros _NOOP
Para texto traducible que se encuentre completamente fuera de una función, utiliza las macros ` QT_TR_NOOP()`, ` QT_TRID_NOOP()` y ` QT_TRANSLATE_NOOP()`, que se expanden mostrando únicamente el texto sin el contexto.
Un ejemplo de QT_TR_NOOP():
QString FriendlyConversation::greeting(int type)
{
static const char *greeting_strings[] = {
QT_TR_NOOP("Hello"),
QT_TR_NOOP("Goodbye")
};
return tr(greeting_strings[type]);
}Un ejemplo de QT_TRANSLATE_NOOP():
static const char *greeting_strings[] = {
QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
};
QString FriendlyConversation::greeting(int type)
{
return tr(greeting_strings[type]);
}
QString global_greeting(int type)
{
return QCoreApplication::translate("FriendlyConversation",
greeting_strings[type]);
}Añadir comentarios para los traductores
Puedes añadir comentarios en el código fuente antes de una cadena que marques como traducible para aclarar su finalidad. Los comentarios se incluyen en los archivos TS que se entregan al traductor.
Nota: Los archivos TS son archivos XML que contienen los textos originales y un espacio reservado para el texto traducido. Los archivos TS actualizados se convierten en archivos de traducción binarios y se incluyen como parte de la aplicación final.
QML: Utiliza //: y //~
En el siguiente fragmento de código, el texto de la línea « //: » es el comentario principal para el traductor.
El texto de la línea « //~ » es información adicional opcional. La primera palabra del texto se utiliza como identificador adicional en el elemento XML del archivo TS, así que asegúrate de que la primera palabra no forme parte de la frase. Por ejemplo, el comentario «Context Not related to back-stepping» se convierte en « <extra-Context>Not related to back-stepping » en el archivo TS.
Text {
id: txt1;
// This UI string is only used here
//: The back of the object, not the front
//~ Context Not related to back-stepping
text: qsTr("Back");
}C++: Utilizar caracteres de comentario
Para añadir comentarios en C++, anota las llamadas a tr() en tu código con comentarios del tipo « //: » o marcando el inicio y el final del comentario.
En los siguientes ejemplos, los comentarios están asociados a las cadenas pasadas a tr() en el contexto de cada llamada:
//: This name refers to a host name.
hostNameLabel->setText(tr("Name:"));
/*: This text refers to a C++ code example. */
QString example = tr("Example");Para añadir comentarios opcionales, utiliza:
//~ <field name> <field contents>El nombre del campo debe constar de un prefijo de dominio (posiblemente la extensión convencional del formato de archivo en el que se inspira el campo), un guión y el nombre real del campo en notación delimitada por guiones bajos. Para su almacenamiento en archivos TS, el nombre del campo, junto con el prefijo extra-, formará el nombre de un elemento XML. El contenido del campo se escapará según las normas XML, pero por lo demás aparecerá tal cual como contenido del elemento. Puedes añadir cualquier número de campos únicos a cada mensaje.
Ejemplo:
//: This is a comment for the translator.
//~ loc-layout_id foo_dialog
//~ loc-blank False
//~ magic-stuff This might mean something magic.
QString text = MyMagicClass::tr("Sim sala bim.");Nota: El uso de comentarios de metacadena « //= » para establecer identificadores en traducciones basadas en texto ha quedado obsoleto en Qt 6.10 y se eliminará en las próximas versiones.
Puedes utilizar la palabra clave TRANSLATOR para los comentarios del traductor. Los metadatos que aparecen justo delante de la palabra clave TRANSLATOR se aplican a todo el archivo TS.
Nota: Cuando se abre el archivo TS en Qt Linguist, los comentarios anotados con //: se muestran en el editor de mensajes de Qt Linguist. Por el contrario, los textos proporcionados mediante las notaciones //~ son información adicional y solo se generan en el archivo TS. Están destinados principalmente a conversiones a otros formatos y permanecen ocultos en Qt Linguist.
Agrupación de traducciones basadas en ID
Puedes asignar una etiqueta a cada traducción basada en ID para organizar las entradas de este tipo de proyectos grandes en grupos más pequeños.
Para asignar una etiqueta a una entrada basada en ID, añada un comentario « //@ » con el nombre de la etiqueta; por ejemplo, en C++:
//% "Open file"
//@ FileOperations
qtTrId("msg.open");O en QML:
//% "Open file"
//@ FileOperations
qsTrId("msg.open");Al abrir el archivo TS en Qt Linguist, las entradas basadas en ID con la misma etiqueta se agrupan, de forma similar a las entradas basadas en texto que se agrupan por contexto. Cualquier elemento sin etiqueta aparece bajo « <unnamed label> ».
Nota: Los nombresde las etiquetas no afectan a la búsqueda ni a la unicidad: los ID siguen siendo únicos a nivel global y se pueden seguir cargando mediante qtTrId("msgid") sin hacer referencia a una etiqueta. La etiqueta se utiliza únicamente para facilitar la navegación del traductor y no modifica el comportamiento en tiempo de ejecución.
Desambiguación de textos idénticos
El sistema de traducción agrupa las cadenas de texto de la interfaz de usuario en elementos únicos para evitar tener que traducir el mismo texto varias veces. Sin embargo, un texto puede parecer idéntico a otro, pero tener un significado diferente. Por ejemplo, en inglés, «back» significa tanto «un paso atrás» como la parte de un objeto opuesta a la parte delantera. Debes indicar al sistema de traducción estos dos significados distintos, para que el traductor pueda crear dos traducciones separadas.
QML: Añadir un desambiguador a qsTr()
En QML, añade una cadena de desambiguación como segundo parámetro de la función qsTr().
En el siguiente fragmento de código, el identificador « not front » diferencia este texto «Back» del texto «Back» que se refiere a dar un paso atrás:
Text {
id: txt1
// This UI string is used only here
//: The back of the object, not the front
//~ Context Not related to back-stepping
text: qsTr("Back", "not front")
}C++: Añadir un disambiguador a tr()
En C++, pasa una cadena de desambiguación en la llamada a tr().
En el siguiente fragmento de código, el identificador « recipient » distingue el nombre del destinatario del del remitente:
MyWindow::MyWindow()
{
QLabel *senderLabel = new QLabel(tr("Name:"));
QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
...Hacer que los atajos de teclado sean traducibles
En su forma más habitual, un atajo de teclado describe una combinación de teclas que se pulsan para realizar alguna acción. Para standard shortcuts, utiliza una tecla estándar para solicitar la secuencia de teclas específica de la plataforma asociada a cada atajo.
Para los atajos personalizados, utiliza cadenas legibles para el usuario, como Ctrl+Q o Alt+F. Puedes traducirlas a los atajos adecuados para los hablantes de diferentes idiomas.
Si codificas los atajos de teclado de forma fija en tu aplicación, los traductores no podrán modificarlos.
Cuando se utilizan atajos de teclado en el texto de los elementos de menú y de los botones, un carácter mnemotécnico (marcado con un subrayado) indica que al pulsar Alt o Ctrl junto con el carácter subrayado se realiza la misma acción que al hacer clic en el elemento de menú o pulsar el botón.
Por ejemplo, las aplicaciones suelen utilizar la tecla F como carácter mnemotécnico en el menú « File », por lo que puedes hacer clic en el elemento del menú o pulsar Alt+F para abrirlo. Para definir el carácter mnemónico en la cadena traducible («Archivo»), antepónle un símbolo «&»: "&File". La traducción de la cadena también debe incluir un símbolo «&», preferiblemente delante del mismo carácter.
Ejemplo en QML
En QML:
Menu {
id: fileMenu
title: qsTr("&File")
MenuItem {
objectName: "quitMenuItem"
text: qsTr("E&xit")
onTriggered: Qt.quit()
}
}C++: Utiliza la clase QKeySequence
En C++, utiliza los objetos ` QAction ` y ` QKeySequence ` para especificar los atajos de teclado que activan acciones:
exitAct = new QAction(tr("E&xit"), this);
exitAct->setShortcuts(QKeySequence::Quit);Las traducciones de los atajos de teclado están asociadas al contexto de ` QShortcut `.
Utiliza Locale para ampliar las funciones de localización
Es posible que algunos gráficos o elementos de audio resulten más adecuados para determinadas regiones geográficas.
En general, intenta evitar la localización de imágenes. Crea iconos que sean apropiados a nivel global, en lugar de basarte en juegos de palabras locales o metáforas forzadas. Sin embargo, es posible que tengas que invertir las imágenes de las flechas que apuntan a la izquierda y a la derecha para las configuraciones regionales en árabe y hebreo.
La configuración regional es uno de los selectores de archivos predeterminados, por lo que puedes utilizar la selección de archivos para mostrar diferentes imágenes que proporciones como recursos en función de la configuración regional del sistema.
Los ejemplos de código QML y C++ de las secciones siguientes dan por hecho que se incluyen los siguientes archivos en los recursos de la aplicación y que se utilizan los códigos de idioma y de país como nombres de las subcarpetas:
images
├── language-icon.png
├── +en_GB
│ └── language-icon.png
└── +fi_FI
└── language-icon.pngQML: Establecer la fuente de la imagen
El siguiente fragmento de código QML muestra cómo seleccionar una imagen de origen para un icono según la configuración regional actual:
icon.source: "qrc:/images/language-icon.png"C++: Uso de QFileSelector
El siguiente fragmento de código en C++ utiliza ` QFileSelector ` para seleccionar un icono de idioma de la carpeta ` images ` según la configuración regional del sistema:
const QFileSelector selector;
const QIcon languageIcon(selector.select(":/images/language-icon.png"));Habilitar la traducción
Los nombres de los archivos TS deben contener códigos ISO de idioma y país:
- «language» es un código de idioma ISO-639 en minúsculas.
- country es un código de país ISO-3166 de dos letras en mayúsculas.
Por ejemplo, « qml_de.ts » establece el idioma de destino en alemán, y « qml_de_CH.ts » establece el idioma de destino en alemán y el país de destino en Suiza. La herramienta « lrelease » genera archivos QM denominados « qml_de.qm » y « qml_de_CH.qm », que la aplicación carga en función de la configuración regional del sistema.
QML: Utiliza QQmlApplicationEngine
En QML, utiliza QQmlApplicationEngine para cargar automáticamente los archivos de traducción desde un subdirectorio llamado i18n, situado en el directorio que contiene el archivo QML principal. Los nombres de los archivos de traducción deben tener el prefijo qml_. Por ejemplo, qml_en_US.qm. Consulta los siguientes fragmentos de código CMake para saber cómo configurar una aplicación multilingüe:
...
find_package(Qt6 6.5 REQUIRED COMPONENTS Quick LinguistTools)
qt_standard_project_setup(REQUIRES 6.5 I18N_TRANSLATED_LANGUAGES ja_JP)
qt_add_qml_module(appmultilingual_demo
URI multilingual_demo
QML_FILES
Main.qml
)
qt_add_translations(appmultilingual_demo
TS_FILE_BASE qml
TS_FILE_DIR i18n
RESOURCE_PREFIX /qt/qml/multilingual_demo/i18n
)
...Las aplicaciones recargan las traducciones cuando cambia el valor de la propiedad « QJSEngine::uiLanguage » o « Qt.uiLanguage ». El siguiente fragmento de código cambia el idioma de forma dinámica cuando el usuario hace clic en el botón:
Button {
anchors.centerIn: parent
text: qsTr("Translate")
onClicked: {
Qt.uiLanguage = Qt.uiLanguage === "en" ? "ja" : "en"
}
}C++: Utilizar QTranslator
En C++, los nombres de los archivos TS deben contener el nombre de la aplicación. Por ejemplo, app_de_DE.ts.
Normalmente, la función ` main() ` de tu aplicación Qt C++ tendrá este aspecto:
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QTranslator myappTranslator;
if (myappTranslator.load(QLocale::system(), u"myapp"_s, u"_"_s, u":/i18n"_s))
app.installTranslator(&myappTranslator);
return app.exec();
}Para una aplicación con capacidad de traducción, se crea un objeto ` QTranslator `, se obtiene una traducción mediante ` load ` según la configuración regional de la interfaz de usuario del usuario en tiempo de ejecución, y se instala el objeto traductor en la aplicación.
Preparación para cambios dinámicos de idioma
Tanto ` Qt Widgets ` como ` Qt Quick ` utilizan el sistema de eventos de Qt para informar a las clases sobre los cambios en la traducción.
LanguageChange Se envían eventos cuando se utiliza la función ` QCoreApplication::installTranslator()` para instalar una nueva traducción. Otros componentes de la aplicación también pueden forzar a los widgets o tipos QML derivados del tipo ` Item ` a actualizarse enviándoles eventos ` LanguageChange `.
Por defecto, los eventos ` LanguageChange ` se propagan a todas las ventanas de nivel superior y, desde allí, se propagan a través de todo el árbol de widgets o tipos QML derivados de `Item`.
Qt Widgets: Sobrescribir changeEvent
El controlador de eventos predeterminado para las subclases de ` QWidget ` responde al evento ` QEvent::LanguageChange ` y llama a la función ` changeEvent() ` cuando es necesario.
Para que los widgets de Qt detecten los cambios en los objetos ` QTranslator ` instalados, reimplementa la función ` changeEvent()` del widget para comprobar si el evento es un evento ` LanguageChange ` y actualiza el texto mostrado por los widgets mediante la función ` tr()`. Por ejemplo:
void MyWidget::changeEvent(QEvent *event)
{
if (event->type() == QEvent::LanguageChange) {
titleLabel->setText(tr("Document Title"));
...
okPushButton->setText(tr("&OK"));
} else
QWidget::changeEvent(event);
}Al utilizar archivos de interfaz de usuario de Qt Widgets Designer (.ui) y uic, puede leer los nuevos archivos de traducción y llamar directamente a ui.retranslateUi(this):
void MyWidget::changeEvent(QEvent *event)
{
if (event->type() == QEvent::LanguageChange) {
ui.retranslateUi(this);
} else
QWidget::changeEvent(event);
}Para transmitir otros eventos de cambio, llama a la implementación predeterminada de la función.
La lista de traductores instalados podría cambiar en respuesta a un evento LocaleChange, o la aplicación podría proporcionar una interfaz de usuario que permita al usuario cambiar el idioma actual de la aplicación.
QML: Sobrescribir el evento para tipos derivados de Item
Para aplicaciones QML sencillas sin ningún tipo registrado en C++ personalizado, basta con utilizar QQmlApplicationEngine para activar una actualización de todos los enlaces de traducción.
Sin embargo, si has registrado un tipo derivado de ` QQuickItem` y una de sus propiedades expone texto traducido (o depende del idioma de cualquier otra forma), sobrescribe su ` event method ` y emite en él la señal de cambio de la propiedad (o llama a ` notify ` en el caso de propiedades enlazables). Por ejemplo:
class MyItem : public QQuickItem
{
Q_OJBECT
QML_ELEMENT
Q_PROPERTY(QString greeting READ greeting NOTIFY greetingChanged)
public signals:
void greetingChanged();
public:
QString greeting() const
{
return tr("Hello World!");
}
bool event(QEvent *ev) override
{
if (ev->type() == QEvent::LanguageChange)
emit greetingChanged();
return QQuickItem::event(ev);
}
};Esto garantiza que cualquier enlace en QML en el que se utilice la propiedad se reevalúe y tenga en cuenta el cambio de idioma.
Clases genéricas derivadas de QObject: uso de filtros de eventos
Algunas clases no derivan ni de ` QWidget ` ni de ` QQuickItem`, pero es posible que aún así necesiten gestionar eventos de cambio de idioma. En ese caso, instale un filtro de eventos en ` QCoreApplication`.
class CustomObject : public QObject
{
Q_OBJECT
public:
QList<QQuickItem *> managedItems;
CustomObject(QOject *parent = nullptr) : QObject(parent)
{
QCoreApplication::instance()->installEventFilter(this);
}
bool eventFilter(QObject *obj, QEvent *ev) override
{
if (obj == QCoreApplication::instance() && ev->type() == QEvent::LanguageChange) {
for (auto item : std::as_const(managedItems))
QCoreApplication::sendEvent(item, ev);
// do any further work on reaction, e.g. emit changed signals
}
return false;
}
};Esto puede ser necesario cuando la clase proporciona cadenas traducidas que posteriormente se muestran en una interfaz de usuario (por ejemplo, un ` item model` personalizado), o cuando la clase actúa como contenedor de widgets o elementos Quick y, por lo tanto, es responsable de reenviarles el evento.
Consideraciones adicionales para el código C++
Las secciones siguientes contienen más información sobre el uso de las clases y funciones de Qt C++ en aplicaciones traducibles:
- Utiliza QString para todo el texto visible para el usuario
- Definir un contexto de traducción
- Traducir clases que no sean de Qt
- Traducir texto que se encuentre fuera de una subclase de QObject
Utiliza QString para todo el texto visible para el usuario
QString utiliza la codificación Unicode internamente, por lo que puedes emplear operaciones habituales de procesamiento de texto para tratar de forma transparente todos los idiomas del mundo. Además, dado que todas las funciones de Qt que muestran texto al usuario toman como parámetro un objeto ` QString `, no hay ninguna sobrecarga de conversión de ` char * ` a ` QString `.
Definir un contexto de traducción
El contexto de traducción para ` QObject ` y cada subclase de ` QObject ` es el propio nombre de la clase. Si se crea una subclase de ` QObject`, utilice la macro ` Q_OBJECT ` en la definición de la clase para sobrescribir el contexto de traducción. La macro establece el contexto en el nombre de la subclase.
Por ejemplo, la siguiente definición de clase incluye la macro Q_OBJECT, que implementa una nueva función tr() que utiliza el contexto MainWindow:
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow();
...Si no se utiliza ` Q_OBJECT ` en una definición de clase, el contexto se hereda de la clase base. Por ejemplo, dado que todas las clases basadas en ` QObject` en Qt proporcionan un contexto, una nueva subclase de ` QWidget ` definida sin la macro ` Q_OBJECT ` utiliza el contexto ` QWidget ` si se invoca su función ` tr() `.
Traducir clases que no son de Qt
Debes proporcionar información adicional a lupdate sobre las cadenas de las clases que no heredan de QObject ni utilizan la macro Q_OBJECT. Para añadir soporte de traducción a una clase que no sea de Qt, puedes utilizar la macro Q_DECLARE_TR_FUNCTIONS(). Por ejemplo:
class MyClass
{
Q_DECLARE_TR_FUNCTIONS(MyClass)
public:
MyClass();
...
};Esto dota a la clase de las funciones ` tr()`, que puedes utilizar para traducir las cadenas asociadas a la clase, y permite que ` lupdate ` encuentre las cadenas traducibles en el código fuente.
Como alternativa, puede llamar a la función ` QCoreApplication::translate()` con un contexto específico que reconozcan ` lupdate ` y ` Qt Linguist `.
Traducir texto que se encuentra fuera de una subclase de QObject
Si el texto entre comillas no se encuentra en una función miembro de una subclase de ` QObject `, utiliza la función ` tr() ` de la clase adecuada o la función ` QCoreApplication::translate()` directamente:
void some_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
LoginWidget::tr("Password:"), logwid);
}
void same_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
QCoreApplication::translate("LoginWidget", "Password:"),
logwid);
}© 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.