qt_add_lrelease | Qt Linguist Manual
Description: Add targets to transform Qt Linguist .ts files into .qm files.

- Qt 6.11
- Qt Linguist Manual
- CMake Commands in Qt6 LinguistTools
- qt_add_lrelease
- Qt 6.11.1 Reference Documentation

# qt_add_lrelease

Add targets to 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 6.7:

     qt_add_lrelease(TS_FILES file1.ts [file2.ts ...]
                     [LRELEASE_TARGET target-name]
                     [EXCLUDE_FROM_ALL]
                     [NO_GLOBAL_TARGET]
                     [QM_OUTPUT_DIRECTORY directory]             # since 6.9
                     [QM_FILES_OUTPUT_VARIABLE variable-name]
                     [MERGE_QT_TRANSLATIONS]
                     [QT_TRANSLATION_CATALOGS catalog1 [catalog2 ...]]
                     [OPTIONS ...])

Since 6.2 (deprecated):

     qt_add_lrelease(target TS_FILES file1.ts [file2.ts ...]
                     [NO_TARGET_DEPENDENCY]
                     [NO_GLOBAL_TARGET]
                     [QM_FILES_OUTPUT_VARIABLE variable-name]
                     [OPTIONS ...])

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

Warning: Calling `qt_add_lrelease` in a directory scope different than the target directory scope requires at least CMake version 3.18.

## Description

Creates a custom command to transform `.ts` files into `.qm` files with lrelease.

The execution of the custom command is driven by a custom target that is built by default. The name of that custom target defaults to `${PROJECT_NAME}_lrelease`. Further calls of `qt_add_lrelease` will create target names with an increasing number appended. The custom target name can be specified with the `LRELEASE_TARGET` option.

The `.ts` files must be specified with the argument `TS_FILES`.

This function is designed to be used in conjunction with qt_add_lupdate. See also the convenience wrapper qt_add_translations.

## Options

You can set additional `OPTIONS` that should be passed when `lrelease` is invoked. You can find possible options in the lrelease documentation.

## 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_lrelease(
         TS_FILES myapp_en.ts myapp_de.ts
         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_lrelease`.

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_lrelease(TS_FILES myapp_en.ts myapp_de.ts)

## Processing Generated .qm Files

To further process the generated `.qm` files, for example to create install rules, `qt_add_lrelease` can store the paths of the `.qm` files in a variable. Pass `QM_FILES_OUTPUT_VARIABLE <variable-name>` to the function for that.

## Build by Default

By default, the command creates a custom target that is added to the default build target. This ensures that the `.qm` files are always up-to-date when the project is built. This behavior can be turned off with the `EXCLUDE_FROM_ALL` argument. In this case, the user must build the `${PROJECT_NAME}_lrelease` target manually.

## Umbrella Target

In addition to the target `${target}_lrelease`, an umbrella target `release_translations` is created. This target will build all `${target}_lrelease` targets that were created with `qt_add_lrelease`.

Pass `NO_GLOBAL_TARGET` to `qt_add_lrelease` to prevent this behavior.

The name of this target can be overridden by setting the variable `QT_GLOBAL_LRELEASE_TARGET` before calling `qt_add_lrelease`.

## 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_lrelease(
         TS_FILES myapp_de.ts myapp_fi.ts
         MERGE_QT_TRANSLATIONS
     )

To explicitly specify the catalogs, use the `QT_TRANSLATION_CATALOGS` argument:

     qt_add_lrelease(
         TS_FILES myapp_de.ts myapp_fi.ts
         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`.

## Deprecated Command Signature

Older versions of `qt_add_lrelease` took a target as the first argument. This is still possible but deprecated.

## Examples

Add the targets `myapp_lrelease` and `release_translations` for transforming the given `.ts` files into `.qm` files. Also, install the generated `.qm` files. The target `myapp_lrelease` is built by default.

     project(myapp)
     ...
     qt_add_lrelease(
         TS_FILES myapp_de.ts myapp_fr.ts
         QM_FILES_OUTPUT_VARIABLE qm_files
     )
     install(FILES ${qm_files} DESTINATION "translations")

You can specify the name of the created target by passing the `LRELEASE_TARGET` argument:

     qt_add_lrelease(
         LRELEASE_TARGET create_myapp_qm_files
         TS_FILES myapp_de.ts myapp_fr.ts
         QM_FILES_OUTPUT_VARIABLE qm_files
     )