qt_add_translations | Qt Linguist Manual
Description: Add targets to update and transform Qt Linguist .ts files into .qm files.

- Qt 6.11
- Qt Linguist Manual
- CMake Commands in Qt6 LinguistTools
- qt_add_translations
- Qt 6.11.2 Reference Documentation

# 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_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])

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_OUTPUT_DIRECTORY` 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_OUTPUT_DIRECTORY` and `TS_FILE_BASE` have no effect for explicitly specified `.ts` files.

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

Before Qt 6.9, the argument `TS_OUTPUT_DIRECTORY` was called `TS_FILE_DIR`. That name is still an alias for `TS_OUTPUT_DIRECTORY` to keep older project files working.

## 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.

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_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`.

## 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.

## Location of generated .qm files

By default, the `.qm` files will be placed in the current build directory (`CMAKE_CURRENT_BINARY_DIR`). Since Qt 6.9 you can use the `QM_OUTPUT_DIRECTORY` argument to generate the `.qm` files in a different directory. Relative paths are considered to be below `CMAKE_CURRENT_BINARY_DIR`.

For example, with the following code, the `.qm` files are generated in a `translations` directory below the current build directory.

     qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

For more fine-grained control, you can specify the output directory of individual `.qm` files by setting the source file property `OUTPUT_LOCATION` on the corresponding `.ts` file. This must happen before calling `qt_add_translations`.

The `OUTPUT_LOCATION` source file property overrides the directory passed via `QM_OUTPUT_DIRECTORY`.

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")
     qt_add_translations(app)

## 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_LANGUAGES 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_OUTPUT_DIRECTORY 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
     )