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]
                    [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_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)
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 参数指定不同的基本名称。

复数形式

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）。要更改此设置，您可以将 OUTPUT_LOCATION 设置为源 .ts 文件的属性。

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

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

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

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

您可以使用 RESOURCE_PREFIX 设置资源前缀。

在静态 Qt 构建中，当创建资源目标时，可以创建额外的目标。您可以使用 qt_add_translations 指示将这些目标存储在一个变量中，通过传递 OUTPUT_TARGETS <variable-name>。

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

可以通过提供 QM_FILES_OUTPUT_VARIABLE 选项来关闭自动资源嵌入，随后跟上命令应存储生成的 .qm 文件列表的变量名。