Add targets to update and transform Qt Linguist .ts files into .qm files.
命令的定义在
LinguistTools
组件对于
Qt6
包。加载包采用：
find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
该命令在 Qt 6.2 引入。
Since 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])
Since Qt 6.2 (deprecated):
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
in a directory scope different than the target directory scope requires at least CMake version 3.18.
Creates targets for updating Qt Linguist
.ts
files and for transforming them into
.qm
files. This function is a convenience wrapper around
qt_add_lupdate
and
qt_add_lrelease
and aims to offer the most common usage of both functions with one call.
参数
TARGETS
specifies a list of targets that intend to load the generated
.qm
files at run time. If there's only one such target, you may directly pass the target's name as the first argument.
参数
SOURCE_TARGETS
specifies a list of executable or library targets that contain sources with translatable strings. From the sources of these targets,
.ts
files will be created.
若
SOURCE_TARGETS
is not given, targets are automatically gathered by calling
qt_collect_translation_source_targets
at the end of the directory scope of
PROJECT_SOURCE_DIR
. This functionality requires CMake 3.19 or newer. This functionality can be turned off with the argument
IMMEDIATE_CALL
.
This function will create the target
update_translations
that scans all source files with
lupdate
and creates and updates the
.ts
文件。
This function will create the target
release_translations
that generates the
.qm
files from the
.ts
files. This target is built by default.
The
.ts
files may be specified with the argument
TS_FILES
, but it's more convenient to let
qt_add_translations
figure out the file paths automatically. See
Automatic Determination of .ts File Paths
了解细节。
采用
SOURCES
you can explicitly specify additional source files that contain translatable strings.
可以使用
INCLUDE_DIRECTORIES
to explicitly specify include directories for those source files.
The paths of the
.ts
files that are used as input for
qt_add_translations
can be automatically determined if
QT_I18N_TRANSLATED_LANGUAGES
has been set. This variable can be conveniently set with
qt_standard_project_setup
.
The following project setup is usually enough:
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)
This will create the files
myproject_de.ts
and
myproject_fr.ts
in the project's source directory.
默认情况下，
.ts
files are created in
CMAKE_CURRENT_SOURCE_DIR
. You can change the location by passing a different directory with the
TS_FILE_DIR
自变量。
默认情况下，
.ts
file names are constructed from
PROJECT_NAME
. You can specify a different base name with the
TS_FILE_BASE
自变量。
QT_I18N_SOURCE_LANGUAGE
specifies the language in which the source code strings are written. For handling plural forms correctly, create an additional
.ts
file for that language that only contains translatable strings for plural forms. See
句柄复数形式
了解细节。
采用
PLURALS_TS_FILE
you can specify the
.ts
file for the source language. This file will only contain plural forms.
A plurals-only
.ts
is automatically generated unless the option
NO_GENERATE_PLURALS_TS_FILE
被指定。
例如，
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)
creates the full translation file
myapp_de.ts
and the plurals-only file
myapp_en.ts
.
If you need a full translation of the source language, add it to QT_I18N_TRANSLATED_LANGUAGES
例如，
project(myapp) qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES en de) qt_add_executable(myapp ...) ... qt_add_translations(myapp)
creates the full translation files
myapp_en.ts
myapp_de.ts
You can specify the name of the custom target that calls lupdate with the
LUPDATE_TARGET
option. Likewise,
LRELEASE_TARGET
controls the name of the custom target that drives the call to
lrelease
.
You can set additional options for
lupdate
and
lrelease
with
LUPDATE_OPTIONS
and
LRELEASE_OPTIONS
. You can find possible options in the
lupdate options
and
lrelease 选项
.
For example, to use
ID based translations
, you need to pass
LRELEASE_OPTIONS -idbased
to
qt_add_translations
.
默认情况下，
.qm
files will be placed in the current build directory (
CMAKE_CURRENT_BINARY_DIR
). To change this, you can set
OUTPUT_LOCATION
as a property of the source
.ts
文件。
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")
By default, the generated
.qm
files are embedded in a Qt resource that will be linked into the targets passed with
TARGETS
. The files in the resource are accessible under the resource prefix
"/i18n"
.
You can set the resource prefix with
RESOURCE_PREFIX
.
In a static Qt build, when a resource target is created, additional targets can be created. You can instruct
qt_add_translations
to store these targets in a variable, by passing
OUTPUT_TARGETS <variable-name>
.
若
OUTPUT_TARGETS
is used, either
IMMEDIATE_CALL
or
SOURCE_TARGETS
必须指定。
The automatic resource embedding can be turned off by giving the
QM_FILES_OUTPUT_VARIABLE
option, followed by the name of a variable in which the command should store the list of generated
.qm
文件。
qt_add_translations
before Qt 6.7
Before Qt 6.7, this command accepted only one target as the first argument. This target was used for both, extracting translatable sources and embedding
.qm
文件。
Since Qt 6.7, the target in the first argument is not used for source extraction anymore.
Add a German and a French translation to the target
frogger
使用
qt_add_translations
:
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)
This will create the
.ts
文件
frogger_de.ts
and
frogger_fr.ts
in the source directory.
lupdate
sees the source files of all targets that are eligible for translation, according to the rules of
qt_collect_translation_source_targets
.
The
.qm
files that are created from the
.ts
files are embedded in the
frogger_game
target under the resource prefix
"i18n"
.
The
qt_add_translations
call in the above example is roughly equivalent to the following:
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}"
)
You can exclude targets and directories from the automatic collection of source targets. The following excludes the target
helper_lib
and everything under the
tests
directory. See the
directory property QT_EXCLUDE_FROM_TRANSLATION
和
target property 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)
In the following example, we exclude source files that are part of the
frogger_game
target using the
QT_EXCLUDE_SOURCES_FROM_TRANSLATION
target property:
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/*"
)
If you don't want to use the automatic collection of source targets you can specify the source targets explicitly:
qt_add_translations(frogger_game
SOURCE_TARGETS frogger_game
)
Now, let's embed the
.qm
files in
frogger_game
and
frogger_level_editor
and set a custom resource prefix.
qt_add_translations(
TARGETS frogger_game frogger_level_editor
RESOURCE_PREFIX "/translations"
)
Instead of embedding the
.qm
files we can install them as regular files:
qt_add_translations(
TARGETS frogger_game frogger_level_editor
QM_FILES_OUTPUT_VARIABLE qm_files
)
install(FILES ${qm_files} DESTINATION "translations")
Place the
.ts
files in a
translations
directory and change the base name to
frogger_i18n
:
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
...
qt_add_translations(frogger
TS_FILE_BASE froggo
TS_FILE_DIR translations
)
This creates the following files
translations/froggo_de.ts
translations/froggo_fr.ts
You can also specify the paths explicitly:
qt_add_translations(frogger
TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
)