Traducciones basadas en ID de texto

El mecanismo de traducción basado en ID de texto es un sistema industrial para la internacionalización y la localización. Cada texto de la aplicación tiene un identificador único (ID de texto) que se utiliza en el código fuente en lugar del texto. Esto facilita enormemente la gestión de un gran número de textos traducidos.

Internacionalizar con ID de texto

Cuando se utilizan identificadores de texto en lugar de texto sin formato, el método general para internacionalizar una aplicación es el mismo, pero los detalles son un poco diferentes:

1. Las funciones y macros del sistema de traducción basado en identificadores de texto son distintas de las del sistema de texto sin formato. Se utiliza la función qsTrId() en lugar de qsTr(), la macro QT_TRID_NOOP() en lugar de QT_TR_NOOP(), y la macro QT_TRID_N_NOOP() en lugar de QT_TR_N_NOOP()).
2. Utilice los ID de texto como cadenas de interfaz de usuario en lugar de cadenas de texto sin formato. Por ejemplo, qsTrId("id-back-not-front")
3. No se puede especificar un parámetro de contexto con un ID de texto, por lo que las palabras con ortografía idéntica pero significado diferente necesitan ID de texto independientes. Por ejemplo, qsTrId("id-back-backstep") diferencia el Back-step Back del id-back-not-front Back.
4. Dado que los nombres de contexto no están permitidos para las traducciones basadas en ID de texto, Qt Linguist enumera los ID en un archivo sin nombres de contexto.
5. El texto en inglés de ingeniería que se ve en la interfaz de usuario para las compilaciones de desarrollo se indica con un comentario //%. Si no lo incluye, el texto ID se muestra en la interfaz de usuario. Esto es especialmente importante cuando hay textos con parámetros. El comentario //% debe incluir los indicadores de parámetros en la cadena. Por ejemplo, //% "Number of files: %1"
6. Los comentarios de //: que proporcionan información adicional al traductor son opcionales en el sistema de texto sin formato. Sin embargo, con el sistema basado en ID de texto, esta información adicional resulta esencial, ya que sin ella sólo se dispone del ID del texto y el traductor podría no ser capaz de hacer una traducción sensata a partir de él sin más contexto. Se pueden utilizar identificadores de texto largos y descriptivos, pero los comentarios suelen ser más fáciles de entender.

Los siguientes fragmentos de código muestran una comparación entre las traducciones basadas en ID de texto y las basadas en texto plano:

Text {
    id: backTxt;
    //: The back of the object, not the front
    //% "Back"
    //~ Context Not related to back-stepping
    text: qsTrId("id-back-not-front");
}

Text {
    id: backTxt;
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back","Not front")
}

Localización con identificadores de texto

La localización con identificadores de texto sigue un proceso muy similar al del texto sin formato.

Se utiliza la herramienta lupdate para generar los ficheros TS en los que se añaden las traducciones. Los valores de origen en los archivos de traducción serán identificadores de texto en lugar de texto sin formato y, por lo tanto, necesitará identificadores de texto descriptivos o buenos comentarios adicionales, o ambos, para garantizar que las traducciones sean precisas.

El ejemplo de texto de interfaz de usuario basado en ID de texto anterior da como resultado el siguiente contenido en el archivo .ts:

<message id="id-back-not-front">
    <source>Back</source>
    <extracomment>The back of the object, not the front</extracomment>
    <translation type="unfinished"></translation>
    <extra-Context>Not related to back-stepping</extra-Context>
</message>

Si no hay traducción disponible para un texto determinado (lo que suele ocurrir hasta avanzado el desarrollo), en la interfaz de usuario se mostrará el ID del texto en lugar de un texto propiamente dicho. Para que la aplicación sea más utilizable en las pruebas, puede hacer que lrelease utilice el texto fuente en inglés (de los comentarios de //% ) como texto traducido y lo marque con algún indicador, como un signo de exclamación (!), para que pueda ver los textos que aún no están traducidos.

Agrupación de traducciones basadas en ID

Puede asignar una etiqueta a cada traducción basada en ID 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>.

Generación automática de etiquetas

En lugar de especificar manualmente los nombres de las etiquetas, puede utilizar marcadores de posición para generar automáticamente etiquetas basadas en la estructura del código:

• //@ <context> - Utiliza automáticamente el contexto completo (namespace::class)
• //@ <class> - Utiliza automáticamente sólo el nombre de la clase (sin espacios de nombres)
• //@ <file> - Utiliza automáticamente el nombre del archivo fuente

Combinación de marcadores de posición

Los marcadores de posición pueden combinarse con texto personalizado para crear etiquetas más descriptivas:

• //@ <file>:<class> - Combina nombre de archivo y clase: filehandler.cpp:FileHandler
• //@ <context>_customSuffix - Añade sufijo: MyApp::FileHandler_customSuffix
• //@ module_<file>_<class>-label - Prefijo y sufijo personalizados: module_filehandler.cpp_FileHandler-label
• //@ <context>:<file> - Contexto con archivo: MyApp::FileHandler:filehandler.cpp

Por ejemplo, en C++:

namespace MyApp {
class FileHandler : QObject {
    Q_OBJECT
    void open() {
        //% "Open file"
        //@ <context>
        qtTrId("msg.open"); // Label: MyApp::FileHandler

        //% "Save file"
        //@ <class>
        qtTrId("msg.save"); // Label: FileHandler

        //% "Export"
        //@ <file>
        qtTrId("msg.export"); // Label: filehandler.cpp
    }
};
}

O en QML:

Item {
    id: myComponent
    Component.onCompleted: {
        //% "Loading"
        //@ <context>
        qsTrId("msg.loading") // Label: <component-name>

        //% "Ready"
        //@ <file>
        qsTrId("msg.ready") // Label: main.qml

        //% "Initialized"
        //@ <file>:<context>-state
        qsTrId("msg.init") // Label: main.qml:<component-name>-state
    }
}

Las etiquetas automáticas son especialmente útiles en proyectos grandes en los que la gestión manual de los nombres de las etiquetas en muchos archivos puede resultar tediosa. Garantizan una agrupación coherente basada en la estructura del código y dan pistas a los traductores sobre dónde se utilizará la traducción.

Configuración de CMake

Al compilar con CMake, utilice el prefijo qml_ para los archivos .ts. Por ejemplo, qml_en.ts. En el archivo CMakeLists.txt, añada la función qt_add_translations, donde se enumeran los archivos *.ts como valores de TS_FILES, y establezca el valor de RESOURCE_PREFIX en el URI del archivo main.qml del proyecto seguido de /i18n:

qt_add_translations(${CMAKE_PROJECT_NAME}
    TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
    RESOURCE_PREFIX Main/i18n
)

Uso avanzado con qmake

Para proyectos con un gran número de configuraciones regionales, puede eliminar la información TRANSLATIONS del archivo .pro y, en su lugar, gestionar las traducciones con un script independiente. El script puede llamar a lrelease y lupdate para cada uno de los objetivos deseados.

Las actualizaciones podrían programarse de la siguiente manera:

lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
...

La generación de los archivos .qm finales podría programarse de la siguiente manera:

lrelease <project-dir>/i18n/myapp-text_en_GB.ts
lrelease <project-dir>/i18n/myapp-text_en_US.ts
...