qt_add_translations

Hinzufügen von Zielen zur Aktualisierung und Umwandlung von Qt Linguist.ts-Dateien in .qm-Dateien.

Der Befehl ist in der Komponente LinguistTools des Pakets Qt6 definiert. Laden Sie das Paket mit:

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

Dieser Befehl wurde in Qt 6.2 eingeführt.

Zusammenfassung

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

Seit Qt 6.2 (veraltet):

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

Wenn versionslose Befehle deaktiviert sind, verwenden Sie stattdessen qt6_add_translations(). Er unterstützt die gleichen Argumente wie dieser Befehl.

Beschreibung

Erzeugt Ziele für die Aktualisierung von Qt Linguist .ts Dateien und für deren Umwandlung in .qm Dateien. Diese Funktion ist ein Convenience-Wrapper um qt_add_lupdate und qt_add_lrelease und zielt darauf ab, die häufigsten Verwendungen beider Funktionen mit einem Aufruf zu ermöglichen.

Der Parameter TARGETS gibt eine Liste von Zielen an, die die generierten .qm Dateien zur Laufzeit laden sollen. Wenn es nur ein solches Ziel gibt, können Sie den Namen des Ziels direkt als erstes Argument übergeben.

Der Parameter SOURCE_TARGETS gibt eine Liste von ausführbaren oder Bibliothekszielen an, die Quellen mit übersetzbaren Zeichenfolgen enthalten. Aus den Quellen dieser Ziele werden die Dateien .ts erstellt.

Wenn SOURCE_TARGETS nicht angegeben wird, werden die Ziele automatisch durch den Aufruf von qt_collect_translation_source_targets am Ende des Verzeichnisbereichs von PROJECT_SOURCE_DIR gesammelt. Diese Funktionalität erfordert CMake 3.19 oder neuer. Diese Funktionalität kann mit dem Argument IMMEDIATE_CALL ausgeschaltet werden.

Diese Funktion erstellt das Ziel update_translations, das alle Quelldateien mit lupdate durchsucht und die Dateien .ts erstellt und aktualisiert.

Diese Funktion erstellt das Ziel release_translations, das die .qm Dateien aus den .ts Dateien erzeugt. Dieses Ziel wird standardmäßig erstellt.

Die .ts Dateien können mit dem Argument TS_FILES angegeben werden, aber es ist bequemer, qt_add_translations die Dateipfade automatisch ermitteln zu lassen. Siehe Automatische Ermittlung von .ts-Dateipfaden für Details.

Quellen und Include-Verzeichnisse

Mit SOURCES können Sie explizit zusätzliche Quelldateien angeben, die übersetzbare Zeichenketten enthalten.

Sie können INCLUDE_DIRECTORIES verwenden, um explizit Include-Verzeichnisse für diese Quelldateien anzugeben.

Automatische Ermittlung der Pfade für .ts-Dateien

Die Pfade der .ts Dateien, die als Eingabe für qt_add_translations verwendet werden, können automatisch ermittelt werden, wenn QT_I18N_TRANSLATED_LANGUAGES gesetzt wurde. Diese Variable kann bequem mit qt_standard_project_setup gesetzt werden.

Das folgende Projekt-Setup ist normalerweise ausreichend:

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)

Damit werden die Dateien myproject_de.ts und myproject_fr.ts im Quellverzeichnis des Projekts angelegt.

Standardmäßig werden die .ts Dateien in CMAKE_CURRENT_SOURCE_DIR erstellt. Sie können den Speicherort ändern, indem Sie ein anderes Verzeichnis mit dem Argument TS_OUTPUT_DIRECTORY übergeben.

Standardmäßig werden die .ts Dateinamen aus PROJECT_NAME gebildet. Sie können einen anderen Basisnamen mit dem Argument TS_FILE_BASE angeben.

Seit Qt 6.8 können Sie das Argument TS_FILES_OUTPUT_VARIABLE angeben, um die automatisch ermittelten .ts Dateipfade in einer Variablen zu speichern.

Vor Qt 6.9 wurde das Argument TS_OUTPUT_DIRECTORY TS_FILE_DIR genannt. Dieser Name ist immer noch ein Alias für TS_OUTPUT_DIRECTORY, damit ältere Projektdateien weiterhin funktionieren.

Plural-Formen

QT_I18N_SOURCE_LANGUAGE gibt die Sprache an, in der die Quellcode-Strings geschrieben werden. Um Pluralformen korrekt zu behandeln, erstellen Sie eine zusätzliche .ts Datei für diese Sprache, die nur übersetzbare Strings für Pluralformen enthält. Siehe Behandlung von Pluralformen für Details.

Mit PLURALS_TS_FILE können Sie die Datei .ts für die Ausgangssprache angeben. Diese Datei wird nur Pluralformen enthalten.

Eine Datei .ts, die nur Pluralformen enthält, wird automatisch erzeugt, wenn nicht die Option NO_GENERATE_PLURALS_TS_FILE angegeben wird.

Ein Beispiel,

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)

erstellt die vollständige Übersetzungsdatei myapp_de.ts und die Datei myapp_en.ts, die nur Pluralformen enthält.

Wenn Sie eine vollständige Übersetzung der Ausgangssprache benötigen, fügen Sie diese zu QT_I18N_TRANSLATED_LANGUAGES

Zum Beispiel,

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

erstellt die vollständigen Übersetzungsdateien

• myapp_en.ts
• myapp_de.ts

Optionen

Sie können den Namen des benutzerdefinierten Ziels, das lupdate aufruft, mit der Option LUPDATE_TARGET angeben. Ebenso steuert LRELEASE_TARGET den Namen des benutzerdefinierten Ziels, das den Aufruf von lrelease steuert.

Mit LUPDATE_OPTIONS und LRELEASE_OPTIONS können Sie zusätzliche Optionen für lupdate und lrelease festlegen. Mögliche Optionen finden Sie in den lupdate-Optionen und lrelease-Optionen.

Wenn Sie zum Beispiel ID-basierte Übersetzungen verwenden möchten, müssen Sie LRELEASE_OPTIONS -idbased an qt_add_translations übergeben.

Speicherort der erzeugten .qm-Dateien

Standardmäßig werden die .qm Dateien im aktuellen Build-Verzeichnis (CMAKE_CURRENT_BINARY_DIR) abgelegt. Seit Qt 6.9 können Sie das Argument QM_OUTPUT_DIRECTORY verwenden, um die .qm Dateien in einem anderen Verzeichnis zu erzeugen. Relative Pfade werden als unterhalb von CMAKE_CURRENT_BINARY_DIR liegend betrachtet.

Zum Beispiel werden mit dem folgenden Code die .qm Dateien in einem translations Verzeichnis unterhalb des aktuellen Build-Verzeichnisses erzeugt.

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

Für eine feinere Steuerung können Sie das Ausgabeverzeichnis einzelner .qm Dateien angeben, indem Sie die Quelldateieigenschaft OUTPUT_LOCATION auf die entsprechende .ts Datei setzen. Dies muss vor dem Aufruf von qt_add_translations geschehen.

Die Quelldateieigenschaft OUTPUT_LOCATION hat Vorrang vor dem Verzeichnis, das über QM_OUTPUT_DIRECTORY übergeben wird.

Mit dem folgenden Code werden zum Beispiel die .qm Dateien in einem translations Verzeichnis unterhalb des aktuellen Build-Verzeichnisses generiert.

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

Generierte .qm-Dateien in Ressourcen einbetten

Standardmäßig werden die generierten .qm Dateien in eine Qt-Ressource eingebettet, die in die mit TARGETS übergebenen Ziele eingebunden wird. Die Dateien in der Ressource sind unter dem Ressourcenpräfix "/i18n" zugänglich.

Sie können den Ressourcen-Präfix mit RESOURCE_PREFIX setzen.

In einem statischen Qt-Build können bei der Erstellung eines Ressourcenziels weitere Ziele erstellt werden. Sie können qt_add_translations anweisen, diese Ziele in einer Variablen zu speichern, indem Sie OUTPUT_TARGETS <variable-name> übergeben.

Wenn OUTPUT_TARGETS verwendet wird, muss entweder IMMEDIATE_CALL oder SOURCE_TARGETS angegeben werden.

Das automatische Einbetten von Ressourcen kann mit der Option QM_FILES_OUTPUT_VARIABLE ausgeschaltet werden, gefolgt von dem Namen einer Variablen, in der der Befehl die Liste der erzeugten .qm Dateien speichern soll.

qt_add_translations vor Qt 6.7

Vor Qt 6.7 akzeptierte dieser Befehl nur ein Ziel als erstes Argument. Dieses Ziel wurde sowohl für das Extrahieren von übersetzbaren Quellen als auch für das Einbetten von .qm Dateien verwendet.

Seit Qt 6.7 wird das Ziel im ersten Argument nicht mehr für die Quellextraktion verwendet.

Zusammenführen von Qt-bereitgestellten Übersetzungen

Seit Qt 6.9 können Sie die von Qt bereitgestellten Übersetzungen in anwendungsspezifische .qm Dateien einbinden. Übergeben Sie dazu die Option MERGE_QT_TRANSLATIONS an qt_add_translations. Dadurch werden die Qt-Übersetzungskataloge ermittelt, die zu den von Ihrem Projekt verwendeten Modulen gehören, und in die von lrelease erzeugten .qm Dateien zusammengeführt.

Die Qt-Übersetzungskataloge werden durch die find_package -Aufrufe in dem Bereich Ihres CMakeLists.txt bestimmt, in dem qt_add_translations aufgerufen wird. Zum Beispiel wird die folgende Sequenz die Kataloge qtbase und qtmultimedia in Ihre .qm Dateien einbinden:

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

Um die Kataloge explizit anzugeben, verwenden Sie das Argument QT_TRANSLATION_CATALOGS:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

Wenn Ihr Projekt eine Sprache unterstützt, für die Qt keine eigene Übersetzung anbietet, wird zur Konfigurationszeit eine Warnung ausgegeben. Sie können diese Warnung unterdrücken, indem Sie die CMake-Variable QT_NO_MISSING_CATALOG_LANGUAGE_WARNING auf ON setzen.

Wenn die automatische Ermittlung der .ts Dateinamen nicht verwendet wird, müssen Sie sicherstellen, dass die QT_I18N_TRANSLATED_LANGUAGE Quelldateieigenschaft auf jeder der .ts Dateien gesetzt ist.

Beispiele

Fügen Sie eine deutsche und eine französische Übersetzung zum Ziel frogger mit qt_add_translations hinzu:

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)

Dies erzeugt die .ts Dateien frogger_de.ts und frogger_fr.ts im Quellverzeichnis. lupdate sieht die Quelldateien aller Ziele, die für eine Übersetzung in Frage kommen, gemäß den Regeln von qt_collect_translation_source_targets.

Die .qm Dateien, die aus den .ts Dateien erzeugt werden, werden in das frogger_game Ziel unter dem Ressourcenpräfix "i18n" eingebettet.

Der Aufruf qt_add_translations im obigen Beispiel entspricht in etwa dem folgenden:

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

Verzeichnisse, Ziele und Quellen ausschließen

Sie können Ziele und Verzeichnisse von der automatischen Sammlung von Quellzielen ausschließen. Das folgende Beispiel schließt das Ziel helper_lib und alles unter dem Verzeichnis tests aus. Siehe die Verzeichniseigenschaft QT_EXCLUDE_FROM_TRANSLATION und die Zieleigenschaft 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)

Im folgenden Beispiel schließen wir Quelldateien aus, die Teil des frogger_game Targets sind, indem wir die Target-Eigenschaft QT_EXCLUDE_SOURCES_FROM_TRANSLATION verwenden:

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

Explizite Angabe von Quellzielen

Wenn Sie die automatische Sammlung von Quellzielen nicht verwenden möchten, können Sie die Quellziele explizit angeben:

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Benutzerdefiniertes Ressourcen-Präfix

Lassen Sie uns nun die Dateien .qm in frogger_game und frogger_level_editor einbetten und ein benutzerdefiniertes Ressourcenpräfix setzen.

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

Installieren von .qm-Dateien

Anstatt die .qm Dateien einzubetten, können wir sie auch als normale Dateien installieren:

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

Beeinflussung der Namen der .ts-Dateien

Legen Sie die .ts Dateien in ein translations Verzeichnis und ändern Sie den Basisnamen in frogger_i18n:

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

Dies erzeugt die folgenden Dateien

• translations/froggo_de.ts
• translations/froggo_fr.ts

Sie können die Pfade auch explizit angeben:

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