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 文件可通过参数TS_FILES 指定，但让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 ` 文件，` TS_OUTPUT_DIRECTORY ` 和 `TS_FILE_BASE ` 均无效。
从 Qt 6.8 开始，您可以指定TS_FILES_OUTPUT_VARIABLE 参数，将自动确定的.ts 文件路径存储在变量中。
在 Qt 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 文件。
如果您需要源语言的完整翻译，请将其添加到QT_I18N_TRANSLATED_LANGUAGES中
例如，
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 。
选项
您可以使用LUPDATE_TARGET 选项指定调用 lupdate 的自定义目标名称。同样，LRELEASE_TARGET 控制驱动lrelease 调用的自定义目标名称。
您可以通过LUPDATE_OPTIONS 和LRELEASE_OPTIONS 为lupdate和 lrelease设置其他选项。可在lupdate选项和lrelease选项中查看可用选项。
生成的 .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 翻译目录由在调用qt_add_translations 的CMakeLists.txt 作用域内对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 本身未提供该语言的翻译，则在 configure 阶段会发出警告。您可以通过将 CMake 变量QT_NO_MISSING_CATALOG_LANGUAGE_WARNING 设置为ON 来抑制此警告。
如果不使用自动确定.ts 文件名的方式，则必须确保为每个.ts 文件设置QT_I18N_TRANSLATED_LANGUAGES源文件属性。
示例
使用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 文件，将以资源前缀"i18n" 嵌入到frogger_game 目标中。
上述示例中的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.tstranslations/froggo_fr.ts
您也可以显式指定路径：
qt_add_translations(frogger
TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
)© 2026 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.
