qt_add_translations

Añade objetivos para actualizar y transformar los archivos .ts de Qt Linguist en archivos .qm.

El comando está definido en el componente LinguistTools del paquete Qt6. Carga el paquete con:

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

Este comando se introdujo en Qt 6.2.

Sinopsis

Desde Qt 6.7:

qt_add_translations([target]
                    [TARGETS target1 [target2...]]
                    [SOURCE_TARGETS target1 [target2...]]
                    [TS_FILE_BASE name]
                    [TS_FILES file1.ts [file2.ts ...]]
                    [PLURALS_TS_FILE file.ts]
                    [NO_GENERATE_PLURALS_TS_FILE]
                    [RESOURCE_PREFIX prefix]
                    [OUTPUT_TARGETS variable-name]
                    [TS_FILES_OUTPUT_VARIABLE variable-name]    # since 6.8
                    [TS_OUTPUT_DIRECTORY directory]             # since 6.9
                    [QM_FILES_OUTPUT_VARIABLE variable-name]
                    [QM_OUTPUT_DIRECTORY directory]             # since 6.9
                    [SOURCES source1.cpp [sources2.cpp ...]]
                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
                    [LUPDATE_TARGET target-name]
                    [LUPDATE_OPTIONS ...]
                    [LRELEASE_TARGET target-name]
                    [LRELEASE_OPTIONS ...]
                    [MERGE_QT_TRANSLATIONS]
                    [QT_TRANSLATION_CATALOGS catalog1 [catalog2 ...]]
                    [IMMEDIATE_CALL])

Desde Qt 6.2 (obsoleto):

qt_add_translations(target TS_FILES file1.ts [file2.ts ...]
                    [RESOURCE_PREFIX prefix]
                    [OUTPUT_TARGETS variable-name]
                    [QM_FILES_OUTPUT_VARIABLE variable-name]
                    [SOURCES source1.cpp [sources2.cpp ...]]
                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
                    [LUPDATE_OPTIONS ...]
                    [LRELEASE_OPTIONS ...])

Si los comandos versionless están deshabilitados, utilice qt6_add_translations() en su lugar. Soporta el mismo conjunto de argumentos que este comando.

Descripción

Crea destinos para actualizar los archivos Qt Linguist .ts y para transformarlos en archivos .qm. Esta función es una envoltura de conveniencia alrededor de qt_add_lupdate y qt_add_lrelease y tiene como objetivo ofrecer el uso más común de ambas funciones con una sola llamada.

El parámetro TARGETS especifica una lista de objetivos que pretenden cargar los archivos .qm generados en tiempo de ejecución. Si sólo hay un objetivo de este tipo, puede pasar directamente el nombre del objetivo como primer argumento.

El parámetro SOURCE_TARGETS especifica una lista de objetivos ejecutables o de biblioteca que contienen fuentes con cadenas traducibles. A partir de los fuentes de estos objetivos, se crearán archivos .ts.

Si no se indica SOURCE_TARGETS, los objetivos se recopilan automáticamente llamando a qt_collect_translation_source_targets al final del ámbito del directorio de PROJECT_SOURCE_DIR. Esta funcionalidad requiere CMake 3.19 o posterior. Esta funcionalidad se puede desactivar con el argumento IMMEDIATE_CALL.

Esta función creará el objetivo update_translations que escanea todos los archivos fuente con lupdate y crea y actualiza los archivos .ts.

Esta función creará el objetivo release_translations que genera los archivos .qm a partir de los archivos .ts. Este objetivo se crea por defecto.

Los archivos .ts pueden ser especificados con el argumento TS_FILES, pero es más conveniente dejar que qt_add_translations determine las rutas de los archivos automáticamente. Vea Determinación automática de rutas de archivos .ts para más detalles.

Fuentes y directorios de inclusión

Con SOURCES puede especificar explícitamente archivos fuente adicionales que contengan cadenas traducibles.

Puede utilizar INCLUDE_DIRECTORIES para especificar explícitamente directorios de inclusión para esos archivos fuente.

Determinación automática de las rutas de los archivos .ts

Las rutas de los archivos .ts que se utilizan como entrada para qt_add_translations pueden determinarse automáticamente si se ha establecido QT_I18N_TRANSLATED_LANGUAGES. Esta variable se puede configurar convenientemente con qt_standard_project_setup.

La siguiente configuración del proyecto suele ser suficiente:

project(myproject)
cmake_minimum_required(VERSION 3.19)
find_package(Qt6 COMPONENTS Core LinguistTools)
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

add_subdirectory(libs)
add_subdirectory(apps)

qt_add_translations(TARGETS myapp)

Esto creará los archivos myproject_de.ts y myproject_fr.ts en el directorio fuente del proyecto.

Por defecto, los archivos .ts se crean en CMAKE_CURRENT_SOURCE_DIR. Puede cambiar la ubicación pasando un directorio diferente con el argumento TS_OUTPUT_DIRECTORY.

Por defecto, los nombres de los archivos .ts se construyen a partir de PROJECT_NAME. Puede especificar un nombre base diferente con el argumento TS_FILE_BASE.

Desde Qt 6.8, puede especificar el argumento TS_FILES_OUTPUT_VARIABLE para almacenar las rutas de los archivos .ts determinadas automáticamente en una variable.

Antes de Qt 6.9, el argumento TS_OUTPUT_DIRECTORY se llamaba TS_FILE_DIR. Ese nombre sigue siendo un alias de TS_OUTPUT_DIRECTORY para mantener funcionando archivos de proyecto antiguos.

Formas plurales

QT_I18N_SOURCE_LANGUAGE especifica el lenguaje en el que están escritas las cadenas del código fuente. Para manejar correctamente las formas plurales, cree un archivo .ts adicional para ese idioma que sólo contenga cadenas traducibles para formas plurales. Consulte Manejo de formas plurales para más detalles.

Con PLURALS_TS_FILE puede especificar el archivo .ts para el idioma de origen. Este archivo sólo contendrá formas plurales.

Se genera automáticamente un .ts sólo para plurales a menos que se especifique la opción NO_GENERATE_PLURALS_TS_FILE.

Si necesita una traducción completa del idioma de origen, añádala a QT_I18N_TRANSLATED_LANGUAGES

Por ejemplo

project(myapp)
qt_standard_project_setup(
    I18N_SOURCE_LANGUAGE en         # optional - this is the default
    I18N_TRANSLATED_LANGUAGES de
)
qt_add_executable(myapp ...)
...
qt_add_translations(myapp)

crea el archivo de traducción completa myapp_de.ts y el archivo de sólo plurales myapp_en.ts.

Opciones

Puede especificar el nombre del destino personalizado que llama a lupdate con la opción LUPDATE_TARGET. Del mismo modo, LRELEASE_TARGET controla el nombre del objetivo personalizado que dirige la llamada a lrelease.

Puede establecer opciones adicionales para lupdate y lrelease con LUPDATE_OPTIONS y LRELEASE_OPTIONS. Encontrará las opciones posibles en las opciones de lupdate y lrelease.

Ubicación de los archivos .qm generados

Por defecto, los archivos .qm se colocarán en el directorio de compilación actual (CMAKE_CURRENT_BINARY_DIR). Desde Qt 6.9 se puede utilizar el argumento QM_OUTPUT_DIRECTORY para generar los archivos .qm en un directorio diferente. Las rutas relativas se consideran por debajo de CMAKE_CURRENT_BINARY_DIR.

Por ejemplo, con el siguiente código, los archivos .qm se generan en un directorio translations por debajo del directorio de construcción actual.

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

Para un control más preciso, puede especificar el directorio de salida de archivos .qm individuales estableciendo la propiedad de archivo fuente OUTPUT_LOCATION en el archivo .ts correspondiente. Esto debe hacerse antes de llamar a qt_add_translations.

La propiedad de archivo fuente OUTPUT_LOCATION anula el directorio pasado a través de QM_OUTPUT_DIRECTORY.

Por ejemplo, con el siguiente código, los archivos .qm se generan en un directorio translations situado debajo del directorio de compilación actual.

set_source_files_properties(app_en.ts app_de.ts
    PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/translations")
qt_add_translations(app)

Incrustación de archivos .qm generados en recursos

Por defecto, los archivos .qm generados se incrustan en un recurso Qt que se enlazará con los objetivos pasados con TARGETS. Se puede acceder a los archivos del recurso con el prefijo "/i18n".

Puede establecer el prefijo del recurso con RESOURCE_PREFIX.

En una compilación estática de Qt, cuando se crea un objetivo de recurso, se pueden crear objetivos adicionales. Puede indicar a qt_add_translations que almacene estos destinos en una variable, pasando OUTPUT_TARGETS <variable-name>.

Si se utiliza OUTPUT_TARGETS, se debe especificar IMMEDIATE_CALL o SOURCE_TARGETS.

La incrustación automática de recursos puede desactivarse dando la opción QM_FILES_OUTPUT_VARIABLE, seguida del nombre de una variable en la que el comando debe almacenar la lista de archivos .qm generados.

qt_add_translations antes de Qt 6.7

Antes de Qt 6.7, este comando sólo aceptaba un objetivo como primer argumento. Este objetivo se usaba tanto para extraer fuentes traducibles como para incrustar archivos .qm.

Desde Qt 6.7, el objetivo en el primer argumento ya no se utiliza para la extracción de fuentes.

Fusionando traducciones proporcionadas por Qt

Desde Qt 6.9, puedes combinar las traducciones proporcionadas por Qt en archivos .qm específicos de la aplicación. Para ello, pase la opción MERGE_QT_TRANSLATIONS a qt_add_translations. Esto determinará los catálogos de traducción de Qt que pertenecen a los módulos utilizados por su proyecto y los fusionará en los archivos .qm que son producidos por lrelease.

Los catálogos de traducción Qt están determinados por las llamadas a find_package en el ámbito de su CMakeLists.txt donde se llama a qt_add_translations. Por ejemplo, la siguiente secuencia fusionará los catálogos qtbase y qtmultimedia en sus archivos .qm:

find_package(Qt6 COMPONENTS MultimediaWidgets)
...
qt_add_translations(my_app MERGE_QT_TRANSLATIONS)

Para especificar explícitamente los catálogos, utilice el argumento QT_TRANSLATION_CATALOGS:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

Si su proyecto soporta un idioma para el que Qt no ofrece su propia traducción, se emitirá una advertencia en el momento de la configuración. Puede suprimir esta advertencia estableciendo la variable CMake QT_NO_MISSING_CATALOG_LANGUAGE_WARNING a ON.

Si no se utiliza la determinación automática de los nombres de archivo .ts, debe asegurarse de que la propiedad de archivo fuente QT_I18N_TRANSLATED_LANGUAGES está establecida en cada uno de los archivos .ts.

Ejemplos

Añada una traducción al alemán y otra al francés al destino frogger utilizando qt_add_translations:

cmake_minimum_required(VERSION 3.28)
project(frogger)
find_package(Qt6 COMPONENTS OpenGLWidgets)
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

# The CMake files in the 'src' subdirectory create
# the targets 'frogger_game' and 'frogger_level_editor'.
add_subdirectory(src)

# Add translations to the 'frogger_game' target.
qt_add_translations(frogger_game)

Esto creará los archivos .ts frogger_de.ts y frogger_fr.ts en el directorio de origen. lupdate ve los archivos de origen de todos los objetivos que son elegibles para la traducción, de acuerdo con las reglas de qt_collect_translation_source_targets.

Los archivos .qm que se crean a partir de los archivos .ts se incrustan en el objetivo frogger_game bajo el prefijo de recurso "i18n".

La llamada a qt_add_translations del ejemplo anterior equivale aproximadamente a lo siguiente:

qt_collect_translation_source_targets(i18n_targets)
qt_add_lupdate(
    SOURCE_TARGETS ${i18n_targets}
    TS_FILES frogger_de.ts frogger_fr.ts)
qt_add_lrelease(
    TS_FILES frogger_de.ts frogger_fr.ts
    QM_FILES_OUTPUT_VARIABLE qm_files)
qt_add_resources(frogger_game "translations"
    PREFIX "/i18n"
    BASE "${CMAKE_CURRENT_BINARY_DIR}"
    FILES "${qm_files}"
)

Excluir directorios, destinos y fuentes

Puede excluir destinos y directorios de la recopilación automática de destinos fuente. Lo siguiente excluye el objetivo helper_lib y todo lo que se encuentre bajo el directorio tests. Consulte la propiedad de directorio QT_EXCLUDE_FROM_TRANSLATION y la propiedad de destino QT_EXCLUDE_FROM_TRANSLATION.

# <project_root>/CMakeLists.txt
qt_add_translations(frogger_game)

# <project_root>/src/helper_lib/CMakeLists.txt
qt_add_library(helper_lib STATIC helpers.cpp)
set_property(TARGET helper_lib PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)

# <project_root>/tests/CMakeLists.txt
add_subdirectory(behavior_tests)
add_subdirectory(physics_tests)
set_directory_properties(PROPERTIES QT_EXCLUDE_FROM_TRANSLATION ON)

En el siguiente ejemplo, excluimos los archivos fuente que forman parte del destino frogger_game utilizando la propiedad de destino QT_EXCLUDE_SOURCES_FROM_TRANSLATION:

qt_add_executable(frogger_game
    main.cpp
    3rdparty/jumpsim.cpp
    3rdparty/frogmath.cpp
)
set_property(TARGET frogger_game
    PROPERTY QT_EXCLUDE_SOURCES_FROM_TRANSLATION "3rdparty/*"
)

Especificación explícita de destinos fuente

Si no desea utilizar la recopilación automática de destinos de origen, puede especificar los destinos de origen de forma explícita:

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Prefijo de recurso personalizado

Ahora, vamos a incrustar los archivos .qm en frogger_game y frogger_level_editor y a establecer un prefijo de recurso personalizado.

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

Instalación de archivos .qm

En lugar de incrustar los archivos .qm podemos instalarlos como archivos normales:

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    QM_FILES_OUTPUT_VARIABLE qm_files
)
install(FILES ${qm_files} DESTINATION "translations")

Influyendo en los nombres de los archivos .ts

Coloque los archivos .ts en un directorio translations y cambie el nombre base a frogger_i18n:

qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
...
qt_add_translations(frogger
    TS_FILE_BASE froggo
    TS_OUTPUT_DIRECTORY translations
)

Esto crea los siguientes archivos

• translations/froggo_de.ts
• translations/froggo_fr.ts

También puedes especificar las rutas explícitamente:

qt_add_translations(frogger
    TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
)