Traducciones basadas en ID de texto
El mecanismo de traducción basado en ID de texto es un sistema de gran solidez 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 grandes cantidades de textos traducidos.
Internacionalización con identificadores de texto
Al utilizar identificadores de texto en lugar de texto sin formato, el método general para internacionalizar una aplicación es el mismo, pero los detalles difieren ligeramente:
- Las funciones y macros del sistema de traducción basado en identificadores de texto son diferentes 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()`.
- Utilice los identificadores de texto como cadenas de la interfaz de usuario en lugar de cadenas de texto sin formato. Por ejemplo,
qsTrId("id-back-not-front") - no se puede especificar un parámetro de contexto con un identificador de texto y, por lo tanto, las palabras que se escriben igual pero tienen significados diferentes necesitan identificadores de texto distintos. Por ejemplo, «
qsTrId("id-back-backstep")» distingue entre el «Back» de dar un paso atrás y el «Back» de «id-back-not-front». - Dado que no se permiten nombres de contexto para las traducciones basadas en identificadores de texto, Qt Linguist enumera los identificadores en un archivo sin nombres de contexto.
- El texto en inglés técnico que se ve en la interfaz de usuario de las versiones de desarrollo se indica con un comentario de
//%. Si no se incluye este comentario, el identificador de texto se muestra en la interfaz de usuario. Esto es especialmente importante cuando hay textos con parámetros. El comentario de//%debe incluir los indicadores de parámetros en la cadena. Por ejemplo,//% "Number of files: %1" - Los comentarios «
//:» que proporcionan información adicional al traductor son opcionales en el sistema de texto sin formato. Sin embargo, con el sistema basado en identificadores de texto, esta información adicional se vuelve esencial, ya que sin ella solo se dispone del identificador de texto y es posible que el traductor no pueda realizar una traducción coherente a partir de él sin un contexto adicional. Se pueden utilizar identificadores de texto largos y descriptivos sin comentarios, pero los comentarios suelen facilitar la comprensión.
Los fragmentos de código que se muestran a continuación, uno al lado del otro, presentan una comparación entre las traducciones basadas en el identificador de texto y las basadas en texto sin formato:
| basadas en el identificador de texto | Basadas en texto sin formato |
|---|---|
| |
Localización con identificadores de texto
La localización con identificadores de texto sigue prácticamente el mismo proceso que con el texto sin formato.
Se utiliza la herramienta lupdate para generar los archivos 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, por lo que se necesitan identificadores de texto descriptivos o buenos comentarios adicionales, o ambos, para garantizar que las traducciones sean precisas.
El texto de ejemplo de la interfaz de usuario basado en identificadores de texto que aparece más arriba 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 ninguna traducción disponible para un texto determinado (lo cual suele ser el caso hasta una fase avanzada del desarrollo), en la interfaz de usuario se mostrará el identificador de texto en lugar del texto propiamente dicho. Para que la aplicación resulte más manejable a la hora de realizar pruebas, puedes hacer que lrelease utilice el texto original en inglés técnico (procedente de los comentarios « //% ») como texto traducido y marcarlo con algún indicador, como un signo de exclamación (!), para que puedas ver los textos que aún no se han traducido.
Agrupación de traducciones basadas en ID
Puedes 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ñade 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.
Generación automática de etiquetas
En lugar de especificar manualmente los nombres de las etiquetas, puedes utilizar marcadores de posición para generar etiquetas automáticamente en función de la estructura del código:
//@ <context>- Utiliza automáticamente el contexto completo (espacio de nombres::clase)//@ <class>- Utiliza automáticamente solo 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 se pueden combinar con texto personalizado para crear etiquetas más descriptivas:
//@ <file>:<class>- Combina el nombre del archivo y la clase:filehandler.cpp:FileHandler//@ <context>_customSuffix- Añade un sufijo:MyApp::FileHandler_customSuffix//@ module_<file>_<class>-label- Prefijo y sufijo personalizados:module_filehandler.cpp_FileHandler-label//@ <context>:<file>- Contexto con el 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 resultan especialmente útiles en proyectos de gran envergadura, en los que gestionar manualmente los nombres de las etiquetas en numerosos archivos puede resultar tedioso. Garantizan una agrupación coherente basada en la estructura del código y ofrecen indicaciones a los traductores sobre dónde se utilizará la traducción.
Nota: Al utilizar « <class> » en código C++ fuera de cualquier clase, se generará una advertencia y se utilizará « <unnamed> » en la etiqueta generada.
Nota: El uso de ` <class> ` en QML generará una advertencia y se utilizará ` <unnamed> `, ya que los componentes QML no son clases. Utiliza ` <context> ` en su lugar para obtener el nombre del componente, o ` <file> ` para obtener el nombre del archivo QML.
Nota: Las etiquetasautomáticas solo funcionan con traducciones basadas en ID (qtTrId, qsTrId). El uso de etiquetas automáticas con traducciones basadas en texto (tr, qsTr) generará una advertencia y la etiqueta se ignorará.
Configuración de CMake
Al compilar con CMake, utiliza el prefijo qml_ para los archivos .ts. Por ejemplo, qml_en.ts. En el archivo CMakeLists.txt, añade la función qt_add_translations, en la que enumeras los archivos *.ts como valores de TS_FILES, y establece el valor de RESOURCE_PREFIX en la URI del archivo main.qml del proyecto seguida 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 destinados a un gran número de configuraciones regionales, puedes eliminar la información de 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 destinos deseados.
Las actualizaciones podrían programarse mediante un script más o menos así:
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
...© 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.