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]
                    [TS_FILES_OUTPUT_VARIABLE variable-name]    # since 6.8
                    [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 ...]
                    [MERGE_QT_TRANSLATIONS]
                    [QT_TRANSLATION_CATALOGS catalog1 [catalog2 ...]]
                    [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.

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.

Since Qt 6.8, you can specify the TS_FILES_OUTPUT_VARIABLE argument to store the automatically determined .ts file paths in a variable.

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.

Merging Qt-provided translations

Since Qt 6.9, you can merge the translations that are provided by Qt into application-specific .qm files. To do that, pass the MERGE_QT_TRANSLATIONS option to qt_add_translations. This will determine the Qt translation catalogs that belong to the modules used by your project and merge them into the .qm files that are produced by lrelease.

The Qt translation catalogs are determined by the find_package calls in the scope of your CMakeLists.txt where qt_add_translations is called. For example, the following sequence will merge the catalogs qtbase and qtmultimedia into your .qm files:

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

To explicitly specify the catalogs, use the QT_TRANSLATION_CATALOGS argument:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

If your project supports a language for which Qt doesn't offer its own translation, a warning will be issued at configure time. You can suppress this warning by setting the CMake variable QT_NO_MISSING_CATALOG_LANGUAGE_WARNING to ON.

If the automatic determination of .ts file names is not used then you must ensure that the QT_I18N_TRANSLATED_LANGUAGE source file property is set on each of the .ts files.

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
)