Escritura del código fuente para la traducción

Escriba el código fuente de QML y Qt C++ de forma que le permita localizar las aplicaciones:

• Marcar cadenas para la traducción
• Usar parámetros en lugar de concatenar cadenas
• Manejo de formularios plurales
• Utilizar configuraciones numéricas regionales
• Internacionalizar fecha, hora y moneda
• Marcar cadenas de texto de datos traducibles
• Añadir comentarios para los traductores
• Desambiguar texto idéntico
• Hacer traducibles los métodos abreviados de teclado
• Uso de la configuración regional para ampliar las funciones de localización
• Activar la traducción
• Prepararse para los cambios dinámicos de idioma

Cuando desarrolle aplicaciones C++, consulte también Consideraciones adicionales para el código C++.

Marcar cadenas para la traducción

La mayor parte del texto que debe traducirse en una aplicación consiste en palabras sueltas o frases cortas. 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 del uso de traducciones traduciendo las frases para cada ventana a medida que se crean. En la mayoría de las aplicaciones, la ventana principal se crea una sola vez. Los diálogos suelen crearse una vez y luego se muestran y ocultan según sea necesario. Una vez que se ha realizado la traducción inicial, no hay más sobrecarga de tiempo de ejecución para las ventanas traducidas. Sólo las ventanas creadas, destruidas y creadas posteriormente tendrán un coste de rendimiento de traducción.

Se pueden crear aplicaciones que cambien de idioma en tiempo de ejecución, pero ello requiere un esfuerzo y conlleva un coste de rendimiento en tiempo de ejecución.

Utilice funciones de traducción para marcar el texto de la interfaz de usuario visible para su traducción en QML y código 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 por el contexto de traducción y, opcionalmente, un comentario de desambiguación al que está asociada. La misma frase puede aparecer en más de un contexto sin conflicto. Si una frase aparece más de una vez en un contexto determinado, sólo se traduce una vez y la traducción se aplica a cada aparición dentro del contexto.

En el enfoque de traducción basada en ID, cada traducción se identifica de forma única mediante un ID explícito. Los ID son únicos para todo el proyecto. Si un ID aparece más de una vez en un proyecto, sólo se traduce una vez y la traducción se aplica a cada ocurrencia dentro del proyecto.

QML

En QML, puede utilizar las siguientes funciones para marcar cadenas visibles para el usuario para su traducción en 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 fuente 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 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 puede establecerse para un archivo dado con:

pragma Translator: ChosenContext

o

pragma Translator: "Chosen::Context"

El contexto establecido mediante qsTranslate() tiene prioridad sobre el contexto 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 la 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 obtiene el valor de traducción correspondiente (o, si no está traducido, el texto fuente) 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++, puede utilizar las siguientes funciones para marcar 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, consulte linguist-id-based-i18n.html

Traducción basada en texto tr()

Utilice la función tr() para marcar un texto como traducible y mostrar el texto traducido. El contexto de traducción es el nombre de la subclase QObject en la que se utiliza la cadena. Para definir el contexto de traducción de las nuevas clases basadas en QObject, utilice la macro Q_OBJECT en la definición de cada nueva clase.

Cuando se llama a tr(), busca la cadena traducible utilizando un objeto QTranslator, que debe instalar en el objeto de aplicación, como se describe en Activar traducción.

Por ejemplo, suponiendo que LoginWidget sea una subclase de QWidget:

LoginWidget::LoginWidget()
{
    QLabel *label = new QLabel(tr("Password:"));
    ...
}

Esto representa el 99% de las cadenas visibles para el usuario que probablemente escriba. Para obtener información sobre cómo marcar literales de cadena traducibles, consulte Marcar cadenas de texto de datos traducibles.

Si el texto entrecomillado no se encuentra en una función miembro de una subclase de QObject, utilice la función tr() de una clase apropiada o directamente la función QCoreApplication::translate():

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() basado en ID

qtTrId() devuelve una cadena traducible identificada por 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 metastring //%. Si el texto no se traduce, se devuelve el texto fuente anotado por //%. Si no se encuentra un ID que coincida, se devuelve el propio ID. Esto no debería ocurrir en condiciones normales.

//% "Password:"
QLabel *label = new QLabel(qtTrId("PasswordID"));

Este código convierte "PasswordID" en una entrada clave única en los archivos de origen de la traducción (TS) y escribe "Password:" como texto de origen. En tiempo de ejecución, el sistema de traducción busca el ID "PasswordID" y obtiene el valor de traducción correspondiente (o si no está traducido, el texto fuente) para la configuración regional actual del sistema.

Utilice parámetros en lugar de concatenar cadenas

Los distintos idiomas organizan las palabras de forma diferente en frases, cláusulas y oraciones, así que no cree cadenas concatenando palabras y datos. En su lugar, utilice % 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 segundo nombre de archivo, respectivamente. En la traducción deben aparecer los mismos parámetros numerados, pero no necesariamente en el mismo orden. Una traducción al alemán de la cadena podría invertir las frases. Por ejemplo, Datei %2 wird bearbeitet, wenn Datei %1 fertig ist. Ambos parámetros numerados aparecen en la traducción, pero en el orden inverso.

QML: Uso de .arg()

El siguiente fragmento de QML tiene una cadena con dos parámetros numéricos %1 y %2. Estos parámetros se insertan con las funciones .arg().

Text {
    text: qsTr("File %1 of %2").arg(counter).arg(total)
}

%1 se refiere al primer parámetro y %2 se refiere al segundo parámetro, por lo que este código produce una salida como: Archivo 2 de 3.

Evite utilizar cadenas de plantilla con argumentos porque la cadena resultante se define en tiempo de ejecución, en lugar de en tiempo de compilación. Como resultado, las herramientas de traducción no pueden encontrar la traducción correcta para las cadenas de plantilla.

C++: Utilice QString::arg()

En C++, utilice las funciones QString::arg() para sustituir parámetros:

void FileCopier::showProgress(int done, int total,
                              const QString &currentFile)
{
    label.setText(tr("%1 of %2 files copied.\nCopying: %3")
                  .arg(done)
                  .arg(total)
                  .arg(currentFile));
}

Este código produce una salida como 5 de 10 archivos copiados. Copiando: algúnarchivo.txt.

Manejo de formas plurales

Puede pasar un parámetro entero adicional(n) a las funciones de traducción y utilizar una notación especial para 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 plurales diferentes.

Este modismo también funciona con idiomas de destino que tienen varias formas plurales, como una forma dual. Además, el modismo maneja correctamente el caso n == 0 para idiomas como el francés que requieren el singular.

Para obtener un resumen de las reglas que Qt Linguist y lrelease utilizan para traducir cadenas que contienen formas plurales, consulte Reglas de traducción para formas plurales.

Para manejar formas plurales en el idioma nativo, 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 sólo entradas con formas plurales.

También 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 de QML

El siguiente fragmento de código QML traduce el texto fuente a la forma plural correcta y sustituye %n por el valor de total:

Text {
    text: qsTr("%n message(s) saved", "", total)
}

Ejemplo de C

El siguiente fragmento de código C++ sustituye %n por el valor que devuelve la función count():

int n = messages.count();
showMessage(tr("%n message(s) saved", "", n));

Utilizar configuración regional de números

Si 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 por defecto si la ha establecido o la configuración regional de todo el sistema, en caso contrario.

QML: Uso de %L

Por ejemplo, en el siguiente fragmento de QML, %L1 formatea el primer parámetro según las convenciones de formateo de números de la configuración regional (región geográfica) seleccionada en ese momento:

Text {
    text: qsTr("%L1").arg(total)
}

Si total es el número 4321 , 56, con la configuración regional inglesa (locale) la salida es 4. 321,56, mientras que con la configuración regional alemana es 4.321,56.

C++: Utilizar %Ln

En C++, puede utilizar %Ln para producir una representación localizada de n. Utilice QLocale::setDefault() para establecer la configuración regional predeterminada.

Internacionalizar la fecha, la hora y la moneda

Presente la fecha, la hora y la moneda utilizando los formatos locales preferidos.

QML: Utilice las funciones QtQml

QML no dispone de modificadores de cadena especiales 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 particular, la propiedad Locale.name contiene el idioma y el país de la configuración regional actual. Puede utilizar el valor tal cual o analizarlo para determinar el contenido apropiado para la configuración regional actual.

El siguiente fragmento obtiene la fecha y la hora actuales con Date(), y las convierte en una cadena para 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 números de moneda, utilice el tipo Number. Tiene funciones similares a las del tipo Date para convertir números en cadenas de divisas localizadas.

C++: Utilice 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 de texto traducibles para su extracción por la herramienta lupdate.

QML: Uso de funciones _NOOP

En QML, utilice las siguientes funciones para marcar literales de cadena traducibles:

• QT_TR_NOOP()
• QT_TRANSLATE_NOOP()
• QT_TRID_NOOP()

Si el usuario cambia el idioma del sistema sin reiniciarlo, dependiendo del sistema, es posible que las cadenas de las matrices y los modelos de listas 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, es necesario declarar las cadenas con la función QT_TR_NOOP(). A continuación, cuando rellene los objetos para su visualización, deberá 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++: Utilizar macros _NOOP

Para el texto traducible completamente fuera de una función, utilice las macros QT_TR_NOOP(), QT_TRID_NOOP(), y QT_TRANSLATE_NOOP() que se expanden a sólo 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

Puede añadir comentarios en el código fuente antes de una cadena que marque como traducible para aclarar su propósito. Los comentarios se incluyen en los archivos TS que entrega al traductor.

QML: Uso de //: 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 extra opcional. La primera palabra del texto se utiliza como identificador adicional en el elemento XML del archivo TS, así que asegúrese de que la primera palabra no forma 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++: Utilice caracteres de comentario

Para añadir comentarios en C++, anote las llamadas a tr() en su código con comentarios de la forma //: o marcando el principio 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, utilice:

//~ <field name> <field contents>

El nombre del campo debe constar de un prefijo de dominio (posiblemente la extensión de archivo 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 el almacenamiento en archivos TS, el nombre del campo junto con el prefijo extra- formará un nombre de elemento XML. El contenido del campo se esconderá en XML, pero por lo demás aparecerá literalmente como el contenido del elemento. Puede 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.");

Puede utilizar la palabra clave TRANSLATOR para los comentarios de traductor. Los metadatos que aparecen justo delante de la palabra clave TRANSLATOR se aplican a todo el archivo TS.

Agrupación de traducciones basadas en ID

Puede asignar a cada traducción basada en ID una etiqueta para organizar las entradas basadas en ID de proyectos grandes en grupos más pequeños.

Para asignar una etiqueta a una entrada basada en ID, añada un comentario en //@ 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 Linguistlas 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 en <unnamed label>.

Desambiguar texto idéntico

El sistema de traducción consolida 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 hacia atrás como la parte de un objeto opuesta a la delantera. Es necesario indicar al sistema de traducción estos dos significados distintos para que el traductor pueda crear dos traducciones distintas.

QML: Añadir un desambiguador a qsTr()

En QML, añada una cadena desambiguadora como segundo parámetro de la función qsTr().

En el siguiente fragmento de código, el ID not front diferencia este texto Back del texto Back backstepping:

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 desambiguador a tr()

En C++, pase una cadena desambiguadora en la llamada a tr().

En el siguiente fragmento de código, el ID recipient diferencia el nombre del destinatario del del remitente:

MyWindow::MyWindow()
{
    QLabel *senderLabel = new QLabel(tr("Name:"));
    QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
    ...

Hacer traducibles los atajos de teclado

En su forma más común, un atajo de teclado describe una combinación de teclas que se pulsan para realizar alguna acción. Para standard shortcuts, utilice una tecla estándar para solicitar la secuencia de teclas específica de la plataforma asociada a cada método abreviado.

Para los atajos personalizados, utiliza cadenas legibles por humanos, como Ctrl+Q o Alt+F. Puedes traducirlas a los atajos adecuados para los hablantes de distintos idiomas.

Si codificas los atajos de teclado en tu aplicación, los traductores no podrán anularlos.

Cuando se utilizan métodos abreviados de teclado en el texto de los elementos de menú y botones, un carácter mnemotécnico (marcado con subrayado) indica que pulsar Alt o Ctrl con el carácter subrayado realiza la misma acción que hacer clic en el elemento de menú o pulsar el botón.

Por ejemplo, las aplicaciones suelen utilizar F como carácter mnemotécnico en el menú File, de modo que puede hacer clic en el elemento de menú o pulsar Alt+F para abrir el menú. Para definir el carácter mnemotécnico en la cadena traducible ("Archivo"), antepóngale un ampersand: "&File". La traducción de la cadena también debe tener un ampersand, preferiblemente delante del mismo carácter.

Ejemplo QML

En QML:

Menu {
    id: fileMenu
    title: qsTr("&File")

    MenuItem {
        objectName: "quitMenuItem"
        text: qsTr("E&xit")
        onTriggered: Qt.quit()
    }
}

C++: Utilice la clase QKeySequence

En C++, utilice los objetos QAction y QKeySequence para especificar los métodos abreviados de teclado que desencadenan acciones:

exitAct = new QAction(tr("E&xit"), this);
exitAct->setShortcuts(QKeySequence::Quit);

Las traducciones de los métodos abreviados de teclado están asociadas al contexto QShortcut.

Utilice Locale para ampliar las funciones de localización

Es posible que distintos gráficos o sonidos resulten más adecuados para distintas regiones geográficas.

En general, trate de evitar la localización de imágenes. Cree iconos que sean apropiados a nivel global, en lugar de basarse en juegos de palabras locales o metáforas estiradas. Sin embargo, es posible que tenga que invertir las imágenes de las flechas que apuntan a la izquierda y a la derecha para las localizaciones árabe y hebrea.

La configuración regional es uno de los selectores de archivos por defecto, por lo que puedes utilizar la selección de archivos para mostrar diferentes imágenes que entregues como recursos en función de la configuración regional del sistema.

Los ejemplos de código QML y C++ de las siguientes secciones suponen que usted entrega los siguientes archivos en los recursos de la aplicación y utiliza los códigos de idioma y país como nombres de las subcarpetas:

images
├── language-icon.png
├── +en_GB
│   └── language-icon.png
└── +fi_FI
    └── language-icon.png

QML: Establecer origen de imagen

El siguiente fragmento de código QML muestra cómo seleccionar una imagen de origen de icono según la configuración regional actual:

icon.source: "qrc:/images/language-icon.png"

C++: Utilizar QFileSelector

El siguiente fragmento de código 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"));

Activar traducción

Los nombres de archivo 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: Utilizar QQmlApplicationEngine

En QML, utilice QQmlApplicationEngine para cargar automáticamente los archivos de traducción de un subdirectorio denominado i18n 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. Consulte 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 dinámicamente 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 archivo TS deben contener el nombre de la aplicación. Por ejemplo, app_de_DE.ts.

Normalmente, la función main() de su 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 compatible con la traducción, se crea un objeto QTranslator, load una traducción de acuerdo con la configuración regional de la interfaz de usuario en tiempo de ejecución, y se instala el objeto traductor en la aplicación.

Prepararse para los 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 de traducción.

LanguageChange Los eventos se publican 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 a sí mismos enviándoles eventos LanguageChange.

Por defecto, los eventos LanguageChange se propagan a todas las ventanas de nivel superior, y desde ahí se propagan a través de todo el árbol de widgets o tipos QML derivados de Item.

Qt Widgets: Anular changeEvent

El manejador de eventos por defecto para las subclases de QWidget responde al evento QEvent::LanguageChange y llama a la función changeEvent() cuando es necesario.

Para que los widgets Qt sean conscientes de los cambios en los objetos QTranslator instalados, reimplemente la función changeEvent() del widget para comprobar si el evento es un evento LanguageChange y actualice el texto mostrado por los widgets utilizando 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);
}

Cuando utilice Qt Widgets Archivos de interfaz de usuario de diseñador (.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 pasar otros eventos de cambio, llame a la implementación por defecto de la función.

La lista de traductores instalados puede cambiar en respuesta a un evento LocaleChange, o la aplicación puede proporcionar una interfaz de usuario que permita al usuario cambiar el idioma actual de la aplicación.

QML: Evento Override para tipos derivados de Item

Para aplicaciones QML simples sin ningún tipo personalizado registrado en C++, basta con utilizar QQmlApplicationEngine para activar una actualización de todos los enlaces de traducción.

Sin embargo, si ha registrado un tipo derivado de QQuickItem, y una de sus propiedades expone texto traducido (o depende del idioma de alguna otra forma), anule su evento event method y emita la señal de cambio de la propiedad en él (o llame a notify en 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 vinculación en QML en la que se utilice la propiedad se reevalúe y tenga en cuenta el cambio de idioma.

Clases genéricas derivadas de QObject: Utilizar filtros de eventos

Algunas clases no derivan ni de QWidget ni de QQuickItem, pero pueden necesitar manejar 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 luego 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 Rápidos, y por lo tanto es responsable de reenviarles el evento.

Consideraciones adicionales para el código C

Las siguientes secciones contienen más información sobre el uso de las clases y funciones C++ de Qt en aplicaciones traducibles:

• Utilizar QString para todo el texto visible para el usuario
• Definir un contexto de traducción
• Traducir clases que no sean Qt
• Traducir texto que está fuera de una subclase QObject

Usar QString para todo el texto visible para el usuario

QString utiliza internamente la codificación Unicode, y por lo tanto puede utilizar operaciones familiares de procesamiento de texto para procesar de forma transparente todos los idiomas del mundo. Además, como todas las funciones Qt que presentan texto al usuario toman un objeto QString como parámetro, no hay 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 subclase QObject, utilice la macro Q_OBJECT en la definición de la clase para anular 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 la definición de una 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 QWidget definida sin una macro Q_OBJECT utiliza el contexto QWidget si invoca su función tr().

Traducir clases no basadas en Qt

Debe proporcionar información extra para lupdate sobre cadenas en clases que no hereden QObject o utilicen la macro Q_OBJECT. Para añadir soporte de traducción a una clase que no sea Qt, puede utilizar la macro Q_DECLARE_TR_FUNCTIONS(). Por ejemplo:

class MyClass
{
    Q_DECLARE_TR_FUNCTIONS(MyClass)

public:
    MyClass();
    ...
};

Esto proporciona a la clase tr() funciones que puede utilizar para traducir cadenas asociadas con la clase, y permite a lupdate encontrar cadenas traducibles en el código fuente.

Alternativamente, puede llamar a la función QCoreApplication::translate() con un contexto específico que lupdate y Qt Linguist reconocen.

Traducir texto que está fuera de una subclase QObject

Si el texto citado no se encuentra en una función miembro de una subclase de QObject, utilice la función tr() de una clase apropiada 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);
}