En esta página

qt_add_translations

Añade objetivos para actualizar y transformar 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 sin versión están desactivados, utiliza qt6_add_translations() en su lugar. Admite el mismo conjunto de argumentos que este comando.

Advertencia: Para llamar a qt_add_translations en un ámbito de directorio distinto al del directorio de destino se requiere, como mínimo, la versión 3.18 de CMake.

Descripción

Crea objetivos para actualizar los archivos ` Qt Linguist ` y ` .ts `, así como para transformarlos en archivos ` .qm `. Esta función es una envoltura de conveniencia en torno a `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 tienen previsto cargar los archivos .qm generados en tiempo de ejecución. Si solo hay un objetivo de este tipo, se puede pasar directamente el nombre del objetivo como primer argumento.

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

Si no se proporciona 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 analiza 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 compila de forma predeterminada.

Los archivos .ts pueden especificarse con el argumento TS_FILES, pero resulta más cómodo dejar que qt_add_translations determine las rutas de los archivos automáticamente. Consulte «Determinación automática de rutas de archivos .ts» para obtener más detalles.

Fuentes y directorios de inclusión

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

Puede utilizar INCLUDE_DIRECTORIES para especificar explícitamente los directorios de inclusión de dichos 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 definido QT_I18N_TRANSLATED_LANGUAGES. Esta variable puede configurarse fácilmente con qt_standard_project_setup().

Por lo general, basta con la siguiente configuración del proyecto:

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 de fuentes del proyecto.

Por defecto, los archivos ` .ts ` se crean en ` CMAKE_CURRENT_SOURCE_DIR`. Puedes cambiar la ubicación indicando un directorio diferente mediante el argumento ` TS_OUTPUT_DIRECTORY `.

Por defecto, los nombres de los archivos « .ts » se generan a partir de « PROJECT_NAME ». Se puede especificar un nombre base diferente mediante el argumento « TS_FILE_BASE ».

Nota: « TS_OUTPUT_DIRECTORY » y « TS_FILE_BASE » no tienen ningún efecto en los archivos « .ts » especificados explícitamente.

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

Antes de Qt 6.9, el argumento TS_OUTPUT_DIRECTORY se denominaba TS_FILE_DIR. Ese nombre sigue siendo un alias de TS_OUTPUT_DIRECTORY para garantizar que los archivos de proyecto más antiguos sigan funcionando.

Formas plurales

QT_I18N_SOURCE_LANGUAGE especifica el idioma en el que están escritas las cadenas del código fuente. Para gestionar correctamente las formas plurales, crea un archivo « .ts » adicional para ese idioma que contenga únicamente cadenas traducibles para formas plurales. Consulta «Gestión de formas plurales» para obtener más detalles.

Con PLURALS_TS_FILE se puede especificar el archivo .ts para el idioma de origen. Este archivo solo contendrá formas plurales.

Se genera automáticamente un archivo « .ts » que solo contiene formas plurales, a menos que se especifique la opción « NO_GENERATE_PLURALS_TS_FILE ».

Si necesitas una traducción completa del idioma de origen, añádela 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)

se crea el archivo de traducción completo myapp_de.ts y el archivo de solo plurales myapp_en.ts.

Opciones

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

Se pueden establecer opciones adicionales para lupdate y lrelease con LUPDATE_OPTIONS y LRELEASE_OPTIONS. Las opciones disponibles se pueden consultar en las opciones de lupdate y las opciones de 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). A partir de Qt 6.9, puedes utilizar el argumento « QM_OUTPUT_DIRECTORY » para generar los archivos « .qm » en un directorio diferente. Las rutas relativas se consideran situadas por debajo de « CMAKE_CURRENT_BINARY_DIR ».

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

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

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

La propiedad del 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)

Incorporación de archivos .qm generados en los recursos

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

Puedes establecer el prefijo de recursos con ` RESOURCE_PREFIX`.

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

Si se utiliza OUTPUT_TARGETS, debe especificarse IMMEDIATE_CALL o SOURCE_TARGETS.

La incrustación automática de recursos se puede desactivar indicando 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 solo aceptaba un destino como primer argumento. Este destino se utilizaba tanto para extraer fuentes traducibles como para incrustar archivos .qm.

A partir de Qt 6.7, el destino del primer argumento ya no se utiliza para la extracción de fuentes.

Fusionar las traducciones proporcionadas por Qt

Desde Qt 6.9, puedes fusionar las traducciones proporcionadas por Qt en archivos ` .qm ` específicos de la aplicación. Para ello, pasa 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 tu proyecto y los fusionará en los archivos ` .qm ` generados por ` lrelease`.

Los catálogos de traducción de Qt se determinan mediante las llamadas a find_package en el ámbito de su CMakeLists.txt donde se invoca 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 los catálogos de forma explícita, utiliza el argumento « QT_TRANSLATION_CATALOGS »:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

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

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

Ejemplos

Añade una traducción al alemán y otra al francés al archivo de 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 detecta los archivos de origen de todos los destinos aptos 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 destino frogger_game bajo el prefijo de recursos "i18n".

La llamada a ` qt_add_translations ` del ejemplo anterior equivale, a grandes rasgos, 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}"
)

Exclusión de directorios, destinos y fuentes

Puedes excluir destinos y directorios de la recopilación automática de destinos de código fuente. Lo siguiente excluye el destino helper_lib y todo lo que se encuentre en el directorio tests. Consulta 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 objetivo frogger_game utilizando la propiedad de objetivo 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 objetivos de código fuente

Si no deseas utilizar la recopilación automática de objetivos de código fuente, puedes especificarlos explícitamente:

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Prefijo de recursos personalizado

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

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

Instalación de archivos .qm

En lugar de integrar 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")

Modificación de los nombres de los archivos .ts

Coloca los archivos .ts en un directorio translations y cambia 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 de forma explícita:

qt_add_translations(frogger
    TS_FILES translations/froggo_de.ts translations/froggo_fr.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.