- Qt 6.7
- Qt Linguist Manual
- CMake Commands in Qt6 LinguistTools
- qt_add_translations
- Qt 6.7.0 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

     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 c{.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")