qt_add_translations

添加目标以更新Qt Linguist.ts 文件并将其转换为 .qm 文件。

该命令在Qt6 软件包的LinguistTools 组件中定义。使用该命令加载软件包：

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

此命令在 Qt 6.2 中引入。

简介

自 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])

自 Qt 6.2 起（已弃用）：

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 ...])

如果禁用了无版本命令，请使用qt6_add_translations() 代替。它支持与此命令相同的参数集。

警告： 在与目标目录作用域不同的目录作用域中调用qt_add_translations 至少需要 CMake 3.18 版本。

说明

创建用于更新Qt Linguist .ts 文件并将其转换为.qm 文件的目标。该函数是qt_add_lupdate和qt_add_lrelease的方便封装，旨在通过一次调用提供这两个函数最常用的用法。

参数TARGETS 指定了在运行时加载生成的.qm 文件的目标列表。如果只有一个这样的目标，可以直接将目标名称作为第一个参数传递。

参数SOURCE_TARGETS 指定包含可翻译字符串源代码的可执行目标或库目标列表。将根据这些目标的源代码创建.ts 文件。

如果未给出SOURCE_TARGETS ，则会在PROJECT_SOURCE_DIR 的目录范围末尾调用qt_collect_translation_source_targets自动收集目标。此功能需要 CMake 3.19 或更新版本。可以使用参数IMMEDIATE_CALL 关闭该功能。

此函数将创建目标update_translations ，它将扫描lupdate 中的所有源文件，并创建和更新.ts 文件。

该函数将创建目标release_translations ，从.ts 文件生成.qm 文件。默认情况下会创建该目标。

可以使用参数TS_FILES 指定.ts 文件，但让qt_add_translations 自动找出文件路径更为方便。详情请参阅自动确定 .ts 文件路径。

源代码和包含目录

通过SOURCES ，您可以明确指定包含可翻译字符串的附加源文件。

您可以使用INCLUDE_DIRECTORIES 明确指定这些源文件的包含目录。

自动确定 .ts 文件路径

如果设置了QT_I18N_TRANSLATED_LANGUAGES，qt_add_translations 输入的.ts 文件路径可自动确定。该变量可通过qt_standard_project_setup 方便地设置。

以下项目设置通常就足够了：

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)

这将在项目的源代码目录中创建myproject_de.ts 和myproject_fr.ts 文件。

默认情况下，.ts 文件创建在CMAKE_CURRENT_SOURCE_DIR 中。你可以通过TS_OUTPUT_DIRECTORY 参数传递不同的目录来更改位置。

默认情况下，.ts 文件名由PROJECT_NAME 生成。您可以使用TS_FILE_BASE 参数指定不同的基名。

注意： TS_OUTPUT_DIRECTORY 和TS_FILE_BASE 对明确指定的.ts 文件无效。

自 Qt 6.8 起，您可以指定TS_FILES_OUTPUT_VARIABLE 参数，将自动确定的.ts 文件路径存储到变量中。

在 Qt XML 6.9 之前，参数TS_OUTPUT_DIRECTORY 被称为TS_FILE_DIR 。该名称仍然是TS_OUTPUT_DIRECTORY 的别名，以保持旧项目文件的正常运行。

复数形式

QT_I18N_SOURCE_LANGUAGE指定了编写源代码字符串的语言。为正确处理复数形式，请为该语言创建一个额外的.ts 文件，其中仅包含复数形式的可翻译字符串。详情请参阅处理复数形式。

通过PLURALS_TS_FILE ，您可以为源语言指定.ts 文件。该文件只包含复数形式。

除非指定NO_GENERATE_PLURALS_TS_FILE 选项，否则将自动生成仅包含复数形式的.ts 。

例如

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)

会生成完整的翻译文件myapp_de.ts 和仅包含复数形式的文件myapp_en.ts 。

如果需要源语言的完整翻译，请将其添加到QT_I18N_TRANSLATED_LANGUAGES中。

例如

project(myapp)
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES en de)
qt_add_executable(myapp ...)
...
qt_add_translations(myapp)

创建完整的翻译文件

myapp_en.ts
myapp_de.ts

选项

你可以使用LUPDATE_TARGET 选项指定调用 lupdate 的自定义目标的名称。同样，LRELEASE_TARGET 可以控制调用lrelease 的自定义目标名称。

你可以通过LUPDATE_OPTIONS 和LRELEASE_OPTIONS 为lupdate和lrelease设置其他选项。你可以在lupdate 选项和lrelease 选项中找到可能的选项。

例如，要使用基于 ID 的翻译，需要将LRELEASE_OPTIONS -idbased 发送至qt_add_translations 。

生成 .qm 文件的位置

默认情况下，.qm 文件将放置在当前的构建目录 (CMAKE_CURRENT_BINARY_DIR)。自 Qt 6.9 起，您可以使用QM_OUTPUT_DIRECTORY 参数在不同目录下生成.qm 文件。相对路径被视为低于CMAKE_CURRENT_BINARY_DIR 。

例如，使用以下代码，.qm 文件将在当前编译目录下的translations 目录中生成。

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

要实现更精细的控制，可以通过在相应的.ts 文件上设置源文件属性OUTPUT_LOCATION 来指定单个.qm 文件的输出目录。这必须在调用qt_add_translations 之前进行。

OUTPUT_LOCATION 源文件属性会覆盖通过QM_OUTPUT_DIRECTORY 传递的目录。

例如，使用以下代码，.qm 文件将在当前构建目录下的translations 目录中生成。

set_source_files_properties(app_en.ts app_de.ts
    PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/translations")
qt_add_translations(app)

在资源中嵌入生成的 .qm 文件

默认情况下，生成的.qm 文件会嵌入到 Qt 资源中，该资源会链接到通过TARGETS 传递的目标中。资源中的文件可通过资源前缀"/i18n" 访问。

您可以通过RESOURCE_PREFIX 设置资源前缀。

在静态 Qt 构建中，创建资源目标时，还可以创建其他目标。您可以通过OUTPUT_TARGETS <variable-name> 命令qt_add_translations 将这些目标存储在一个变量中。

如果使用OUTPUT_TARGETS ，则必须指定IMMEDIATE_CALL 或SOURCE_TARGETS 。

自动资源嵌入功能可以关闭，方法是提供QM_FILES_OUTPUT_VARIABLE 选项，然后输入变量名，命令应将生成的.qm 文件列表存储在该变量中。

`qt_add_translations` Qt 6.7 之前

在 Qt 6.7 之前，该命令只接受一个目标作为第一个参数。该目标同时用于提取可翻译源代码和嵌入.qm 文件。

自 Qt 6.7 起，第一个参数中的目标不再用于提取源代码。

合并 Qt 提供的翻译

自 Qt 6.9 起，您可以将 Qt 提供的翻译合并到特定于应用程序的.qm 文件中。为此，请向qt_add_translations 传递MERGE_QT_TRANSLATIONS 选项。这将确定属于项目所用模块的 Qt 翻译目录，并将其合并到lrelease 生成的.qm 文件中。

Qt 翻译目录由您的CMakeLists.txt 范围内调用qt_add_translations 的find_package 决定。例如，以下序列将把qtbase 和qtmultimedia 目录合并到.qm 文件中：

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

要明确指定目录，请使用QT_TRANSLATION_CATALOGS 参数：

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

如果您的项目支持的语言 Qt 没有提供自己的翻译，则在配置时会发出警告。您可以通过将 CMake 变量QT_NO_MISSING_CATALOG_LANGUAGE_WARNING 设置为ON 来抑制该警告。

如果不使用自动确定.ts 文件名的功能，则必须确保在每个.ts 文件上都设置了 QT_I18N_TRANSLATED_LANGUAGE 源文件属性。

示例

使用qt_add_translations 向目标frogger 添加德语和法语翻译：

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)

.ts frogger_de.ts frogger_fr.ts lupdate会根据qt_collect_translation_source_targets 的规则，查看所有符合翻译条件的目标的源文件。

从.ts 文件创建的.qm 文件被嵌入frogger_game 目标文件，资源前缀为"i18n" 。

上述示例中的qt_add_translations 调用大致等同于以下内容：

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}"
)

排除目录、目标和源代码

您可以从源目标的自动收集中排除目标和目录。下面的例子排除了目标helper_lib 和tests 目录下的所有内容。请参阅目录属性 QT_EXCLUDE_FROM_TRANSLATION 和目标属性 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)

在下面的示例中，我们使用QT_EXCLUDE_SOURCES_FROM_TRANSLATION目标属性排除了属于frogger_game 目标的源文件：

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/*"
)

明确指定源目标

如果不想使用源目标的自动收集功能，可以明确指定源目标：

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

自定义资源前缀

现在，让我们将.qm 文件嵌入frogger_game 和frogger_level_editor ，并设置自定义资源前缀。

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

安装 .qm 文件

与其嵌入.qm 文件，我们还可以将其作为普通文件进行安装：

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    QM_FILES_OUTPUT_VARIABLE qm_files
)
install(FILES ${qm_files} DESTINATION "translations")

影响 .ts 文件的名称

将.ts 文件放入translations 目录，并将基本名称改为frogger_i18n ：

qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
...
qt_add_translations(frogger
    TS_FILE_BASE froggo
    TS_OUTPUT_DIRECTORY translations
)

这将创建以下文件

translations/froggo_de.ts
translations/froggo_fr.ts

您也可以明确指定路径：

qt_add_translations(frogger
    TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
)

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

qt_add_translations

简介

说明

源代码和包含目录

自动确定 .ts 文件路径

复数形式

选项

生成 .qm 文件的位置

在资源中嵌入生成的 .qm 文件

qt_add_translations Qt 6.7 之前

合并 Qt 提供的翻译

示例

排除目录、目标和源代码

明确指定源目标

自定义资源前缀

安装 .qm 文件

影响 .ts 文件的名称

`qt_add_translations` Qt 6.7 之前