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_FILE_DIR directory]
                    [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
                    [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])

自 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_FILE_DIR 参数传递不同的目录来更改位置。

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

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

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

复数形式

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 文件将放置在当前的构建目录 (CMAKE_CURRENT_BINARY_DIR) 中。要改变这种情况，可以在调用qt_add_translations 之前将OUTPUT_LOCATION 设置为源文件.ts 的属性。

例如，使用以下代码，.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_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_FILE_DIR 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 文件

qt_add_translations Qt 6.7 之前

示例

排除目录、目标和源代码

明确指定源目标

自定义资源前缀

安装 .qm 文件

影响 .ts 文件的名称

`qt_add_translations` Qt 6.7 之前