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

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 ...]]
                    [NATIVE_TS_FILE file.ts]
                    [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])

If versionless commands are disabled, use qt6_add_translations() instead. It supports the same set of arguments as this command.

Note: This command is in technology preview and may change in future releases.

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_i18n_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_LANGUAGES has been set.

The following project setup is usually enough:

project(myproject)
cmake_minimum_required(VERSION 3.19)
qt_standard_project_setup(I18N_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.

Native Language

The native language of a project is 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 NATIVE_TS_FILE you can specify the .ts file for the native language. This file will only contain plural forms.

If QT_I18N_NATIVE_LANGUAGE is set then the path to the native .ts file will also be automatically determined.

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.

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 translation to a target super_calc using qt_add_translations:

qt_add_translations(super_calc TS_FILES super_calc_de.ts)

This is roughly equivalent to the following:

qt_collect_i18n_targets(i18n_targets)
qt_add_lupdate(
    TARGETS ${i18n_targets}
    TS_FILES super_calc_de.ts)
qt_add_lrelease(
    TS_FILES super_calc_de.ts
    QM_FILES_OUTPUT_VARIABLE qm_files)
qt_add_resources(super_calc "translations"
    PREFIX "/i18n"
    BASE "${CMAKE_CURRENT_BINARY_DIR}"
    FILES "${qm_files}")

Add a Norwegian translation to frogger_game and frogger_level_editor with a custom resource prefix:

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    TS_FILES frogger_game_no.ts
    RESOURCE_PREFIX "/translations")

Add a Finnish translation to business_logic, and install the generated .qm files:

qt_add_translations(business_logic
    TS_FILES myapp_fi.ts
    QM_FILES_OUTPUT_VARIABLE qm_files)
install(FILES ${qm_files} DESTINATION "translations")

© 2023 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.