qt_add_translations
Add targets to update and transform Qt Linguist .ts files into .qm files.
The command is defined in the LinguistTools
component of the Qt6
package. Load the package with:
find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
This command was introduced in Qt 6.2.
Synopsis
Since Qt 6.7:
qt_add_translations([target] [TARGETS target1 [target2...]] [SOURCE_TARGETS target1 [target2...]] [TS_FILE_BASE name] [TS_FILE_DIR directory] [TS_FILES file1.ts [file2.ts ...]] [PLURALS_TS_FILE file.ts] [NO_GENERATE_PLURALS_TS_FILE] [RESOURCE_PREFIX prefix] [OUTPUT_TARGETS variable-name] [QM_FILES_OUTPUT_VARIABLE variable-name] [SOURCES source1.cpp [sources2.cpp ...]] [INCLUDE_DIRECTORIES directory1 [directory2 ...]] [LUPDATE_TARGET target-name] [LUPDATE_OPTIONS ...] [LRELEASE_TARGET target-name] [LRELEASE_OPTIONS ...] [IMMEDIATE_CALL])
Since Qt 6.2 (deprecated):
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 ...])
If versionless commands are disabled, use qt6_add_translations()
instead. It supports the same set of arguments as this command.
Warning: Calling qt_add_translations
in a directory scope different than the target directory scope requires at least CMake version 3.18.
Description
Creates targets for updating Qt Linguist .ts
files and for transforming them into .qm
files. This function is a convenience wrapper around qt_add_lupdate and qt_add_lrelease and aims to offer the most common usage of both functions with one call.
The parameter TARGETS
specifies a list of targets that intend to load the generated .qm
files at run time. If there's only one such target, you may directly pass the target's name as the first argument.
The parameter SOURCE_TARGETS
specifies a list of executable or library targets that contain sources with translatable strings. From the sources of these targets, .ts
files will be created.
If SOURCE_TARGETS
is not given, targets are automatically gathered by calling qt_collect_translation_source_targets at the end of the directory scope of PROJECT_SOURCE_DIR
. This functionality requires CMake 3.19 or newer. This functionality can be turned off with the argument IMMEDIATE_CALL
.
This function will create the target update_translations
that scans all source files with lupdate
and creates and updates the .ts
files.
This function will create the target release_translations
that generates the .qm
files from the .ts
files. This target is built by default.
The .ts
files may be specified with the argument TS_FILES
, but it's more convenient to let qt_add_translations
figure out the file paths automatically. See Automatic Determination of .ts File Paths for details.
Sources and Include Directories
With SOURCES
you can explicitly specify additional source files that contain translatable strings.
You can use INCLUDE_DIRECTORIES
to explicitly specify include directories for those source files.
Automatic Determination of .ts File Paths
The paths of the .ts
files that are used as input for qt_add_translations
can be automatically determined if QT_I18N_TRANSLATED_LANGUAGES has been set. This variable can be conveniently set with qt_standard_project_setup.
The following project setup is usually enough:
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)
This will create the files myproject_de.ts
and myproject_fr.ts
in the project's source directory.
By default, the .ts
files are created in CMAKE_CURRENT_SOURCE_DIR
. You can change the location by passing a different directory with the TS_FILE_DIR
argument.
By default, the .ts
file names are constructed from PROJECT_NAME
. You can specify a different base name with the TS_FILE_BASE
argument.
Note: TS_FILE_DIR
and TS_FILE_BASE
have no effect for explicitly specified .ts
files.
Plural Forms
QT_I18N_SOURCE_LANGUAGE specifies the language in which the source code strings are written. For handling plural forms correctly, create an additional .ts
file for that language that only contains translatable strings for plural forms. See Handle Plural Forms for details.
With PLURALS_TS_FILE
you can specify the .ts
file for the source language. This file will only contain plural forms.
A plurals-only .ts
is automatically generated unless the option NO_GENERATE_PLURALS_TS_FILE
is specified.
For example,
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)
creates the full translation file myapp_de.ts
and the plurals-only file myapp_en.ts
.
If you need a full translation of the source language, add it to QT_I18N_TRANSLATED_LANGUAGES
For example,
project(myapp) qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES en de) qt_add_executable(myapp ...) ... qt_add_translations(myapp)
creates the full translation files
myapp_en.ts
myapp_de.ts
Options
You can specify the name of the custom target that calls lupdate with the LUPDATE_TARGET
option. Likewise, LRELEASE_TARGET
controls the name of the custom target that drives the call to lrelease
.
You can set additional options for lupdate and lrelease with LUPDATE_OPTIONS
and LRELEASE_OPTIONS
. You can find possible options in the lupdate options and lrelease options.
For example, to use ID based translations, you need to pass LRELEASE_OPTIONS -idbased
to qt_add_translations
.
By default, the .qm
files will be placed in the current build directory (CMAKE_CURRENT_BINARY_DIR
). To change this, you can set OUTPUT_LOCATION
as a property of the source .ts
file.
For example, with the following code, the .qm
files are generated in a translations
directory below the current build directory.
set_source_files_properties(app_en.ts app_de.ts PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/translations")
Embedding Generated .qm Files in Resources
By default, the generated .qm
files are embedded in a Qt resource that will be linked into the targets passed with TARGETS
. The files in the resource are accessible under the resource prefix "/i18n"
.
You can set the resource prefix with RESOURCE_PREFIX
.
In a static Qt build, when a resource target is created, additional targets can be created. You can instruct qt_add_translations
to store these targets in a variable, by passing OUTPUT_TARGETS <variable-name>
.
If OUTPUT_TARGETS
is used, either IMMEDIATE_CALL
or SOURCE_TARGETS
must be specified.
The automatic resource embedding can be turned off by giving the QM_FILES_OUTPUT_VARIABLE
option, followed by the name of a variable in which the command should store the list of generated .qm
files.
qt_add_translations
before Qt 6.7
Before Qt 6.7, this command accepted only one target as the first argument. This target was used for both, extracting translatable sources and embedding .qm
files.
Since Qt 6.7, the target in the first argument is not used for source extraction anymore.
Examples
Add a German and a French translation to the target frogger
using 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)
This will create the .ts
files frogger_de.ts
and frogger_fr.ts
in the source directory. lupdate sees the source files of all targets that are eligible for translation, according to the rules of qt_collect_translation_source_targets.
The .qm
files that are created from the .ts
files are embedded in the frogger_game
target under the resource prefix "i18n"
.
The qt_add_translations
call in the above example is roughly equivalent to the following:
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}" )
Excluding directories, targets, and sources
You can exclude targets and directories from the automatic collection of source targets. The following excludes the target helper_lib
and everything under the tests
directory. See the directory property QT_EXCLUDE_FROM_TRANSLATION and the target property 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)
In the following example, we exclude source files that are part of the frogger_game
target using the QT_EXCLUDE_SOURCES_FROM_TRANSLATION target property:
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/*" )
Explicit specification of source targets
If you don't want to use the automatic collection of source targets you can specify the source targets explicitly:
qt_add_translations(frogger_game SOURCE_TARGETS frogger_game )
Custom resource prefix
Now, let's embed the .qm
files in frogger_game
and frogger_level_editor
and set a custom resource prefix.
qt_add_translations( TARGETS frogger_game frogger_level_editor RESOURCE_PREFIX "/translations" )
Installing .qm files
Instead of embedding the .qm
files we can install them as regular files:
qt_add_translations( TARGETS frogger_game frogger_level_editor QM_FILES_OUTPUT_VARIABLE qm_files ) install(FILES ${qm_files} DESTINATION "translations")
Influencing the names of the .ts files
Place the .ts
files in a translations
directory and change the base name to frogger_i18n
:
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr) ... qt_add_translations(frogger TS_FILE_BASE froggo TS_FILE_DIR translations )
This creates the following files
translations/froggo_de.ts
translations/froggo_fr.ts
You can also specify the paths explicitly:
qt_add_translations(frogger TS_FILES translations/froggo_de.ts translations/froggo_fr.ts )
© 2024 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.