qt_add_translations

Fügen Sie Ziele hinzu, um „ Qt Linguist “-Dateien im .ts-Format zu aktualisieren und in .qm-Dateien umzuwandeln.

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

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

Dieser Befehl wurde in Qt 6.2 eingeführt.

Übersicht

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 versionlose Befehle deaktiviert sind, verwenden Sie stattdessen „ qt6_add_translations() “. Dieser Befehl unterstützt dieselben Argumente wie der vorliegende Befehl.

Beschreibung

Erstellt Ziele zum Aktualisieren von „ Qt Linguist “- und „ .ts “-Dateien sowie zum Umwandeln dieser Dateien in „ .qm “-Dateien. Diese Funktion ist ein Komfort-Wrapper um „qt_add_lupdate()“ und „qt_add_lrelease()“ und zielt darauf ab, die gängigste Verwendung beider Funktionen mit einem einzigen 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 ` .ts `-Dateien erstellt.

Wird „ SOURCE_TARGETS “ nicht angegeben, werden die Ziele automatisch durch Aufruf von „qt_collect_translation_source_targets()“ am Ende des Verzeichnisbereichs von „ PROJECT_SOURCE_DIR “ erfasst. Diese Funktionalität erfordert CMake 3.19 oder neuer. Sie kann mit dem Argument „ IMMEDIATE_CALL “ deaktiviert werden.

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

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

Die „ .ts “-Dateien können mit dem Argument „ TS_FILES “ angegeben werden, es ist jedoch praktischer, wenn „ qt_add_translations “ die Dateipfade automatisch ermittelt. Weitere Informationen finden Sie unter „Automatische Ermittlung von .ts-Dateipfaden “.

Quell- und Include-Verzeichnisse

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

Mit „ INCLUDE_DIRECTORIES “ können Sie Einbindungsverzeichnisse für diese Quelldateien explizit angeben.

Automatische Ermittlung von .ts-Dateipfaden

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 ist. Diese Variable lässt sich bequem mit „qt_standard_project_setup()“ setzen.

Die folgende Projekteinrichtung reicht in der Regel aus:

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)

Dadurch werden die Dateien „ myproject_de.ts “ und „ myproject_fr.ts “ im Quellverzeichnis des Projekts erstellt.

Standardmäßig werden die „ .ts “-Dateien im Verzeichnis „ CMAKE_CURRENT_SOURCE_DIR “ erstellt. Sie können den Speicherort ändern, indem Sie mit dem Argument „ TS_OUTPUT_DIRECTORY “ ein anderes Verzeichnis angeben.

Standardmäßig werden die Dateinamen unter „ .ts “ auf der Grundlage von „ PROJECT_NAME “ gebildet. Sie können mit dem Argument „ TS_FILE_BASE “ einen anderen Basisnamen angeben.

Seit Qt 6.8 können Sie das Argument „ TS_FILES_OUTPUT_VARIABLE “ angeben, um die automatisch ermittelten Pfade der „ .ts “-Dateien in einer Variablen zu speichern.

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

Pluralformen

QT_I18N_SOURCE_LANGUAGE gibt die Sprache an, in der die Zeichenfolgen des Quellcodes geschrieben sind. Um Pluralformen korrekt zu behandeln, erstellen Sie für diese Sprache eine zusätzliche Datei „ .ts “, die ausschließlich übersetzbare Zeichenfolgen für Pluralformen enthält. Weitere Informationen finden Sie unter „Behandlung von Pluralformen “.

Mit „ PLURALS_TS_FILE “ können Sie die Datei „ .ts “ für die Quellsprache angeben. Diese Datei enthält ausschließlich Pluralformen.

Eine ausschließlich Pluralformen enthaltende ` .ts `-Datei wird automatisch generiert, sofern die Option ` NO_GENERATE_PLURALS_TS_FILE ` nicht angegeben ist.

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

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)

wird die vollständige Übersetzungsdatei „ myapp_de.ts “ und die Plural-Datei „ myapp_en.ts “ erstellt.

Optionen

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

Mit „ LUPDATE_OPTIONS “ und „ LRELEASE_OPTIONS “ können Sie zusätzliche Optionen für „lupdate“ und „lrelease“ festlegen. Die möglichen Optionen finden Sie unter den „lupdate-Optionen “ und den „lrelease-Optionen“.

Speicherort der generierten .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 generieren. Relative Pfade werden als unterhalb von „ CMAKE_CURRENT_BINARY_DIR “ liegend betrachtet.

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

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

Für eine feinere Steuerung können Sie das Ausgabeverzeichnis einzelner „ .qm “-Dateien festlegen, indem Sie die Quelldateieigenschaft „ OUTPUT_LOCATION “ in der entsprechenden „ .ts “-Datei setzen. Dies muss vor dem Aufruf von „ qt_add_translations “ erfolgen.

Die Eigenschaft „ OUTPUT_LOCATION “ der Quelldatei überschreibt das über „ QM_OUTPUT_DIRECTORY “ übergebene Verzeichnis.

Mit dem folgenden Code werden die „ .qm “-Dateien beispielsweise in einem Verzeichnis „ translations “ 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)

Einbetten generierter .qm-Dateien in Ressourcen

Standardmäßig werden die generierten „ .qm “-Dateien in eine Qt-Ressource eingebettet, die in die mit „ TARGETS “ übergebenen Ziele eingebunden wird. Auf die Dateien in der Ressource kann unter dem Ressourcenpräfix „ "/i18n" “ zugegriffen werden.

Sie können das Ressourcenpräfix mit ` RESOURCE_PREFIX` festlegen.

Bei einem statischen Qt-Build können beim Erstellen eines Ressourcen-Ziels zusätzliche 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.

Die automatische Einbettung von Ressourcen kann deaktiviert werden, indem die Option „ QM_FILES_OUTPUT_VARIABLE “ angegeben wird, gefolgt vom Namen einer Variablen, in der der Befehl die Liste der generierten „ .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 zum Extrahieren übersetzbarer Quellen als auch zum Einbetten von „ .qm “-Dateien verwendet.

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

Zusammenführen von Qt-bereitgestellten Übersetzungen

Seit Qt 6.9 können Sie die von Qt bereitgestellten Übersetzungen in anwendungsspezifische „ .qm “-Dateien zusammenführen. Ü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 „ .qm “-Dateien zusammengeführt, die von „ lrelease “ erzeugt werden.

Die Qt-Übersetzungskataloge werden durch die Aufrufe von ` find_package ` im Geltungsbereich Ihres ` CMakeLists.txt ` ermittelt, in dem ` qt_add_translations ` aufgerufen wird. Die folgende Abfolge führt beispielsweise dazu, dass die Kataloge ` qtbase ` und ` qtmultimedia ` in Ihre ` .qm `-Dateien zusammengeführt werden:

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 beim Konfigurieren 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 Dateinamen für „ .ts “ nicht verwendet wird, müssen Sie sicherstellen, dass die Eigenschaft „QT_I18N_TRANSLATED_LANGUAGES“ für jede der „ .ts “-Dateien gesetzt ist.

Beispiele

Fügen Sie dem Ziel- frogger mithilfe von „ qt_add_translations “ eine deutsche und eine französische Übersetzung 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)

Dadurch werden im Quellverzeichnis die „ .ts “-Dateien „ frogger_de.ts “ und „ frogger_fr.ts “ erstellt. „lupdate“ erkennt die Quelldateien aller Ziele, die gemäß den Regeln von „qt_collect_translation_source_targets()“ für eine Übersetzung in Frage kommen.

Die aus den „ .ts “-Dateien erstellten „ .qm “-Dateien werden im Ziel „ frogger_game “ unter dem Ressourcenpräfix „ "i18n" “ eingebettet.

Der Aufruf von ` qt_add_translations ` im obigen Beispiel entspricht in etwa Folgendem:

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

Ausschluss von Verzeichnissen, Zielen und Quellen

Sie können Ziele und Verzeichnisse von der automatischen Erfassung von Quellzielen ausschließen. Der folgende Befehl schließt das Ziel „ helper_lib “ sowie alle Inhalte des Verzeichnisses „ 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, die Teil des Ziels „ frogger_game “ sind, mithilfe der Ziel-Eigenschaft QT_EXCLUDE_SOURCES_FROM_TRANSLATION aus:

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 Erfassung von Quellzielen nicht verwenden möchten, können Sie die Quellziele explizit angeben:

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Benutzerdefiniertes Ressourcenpräfix

Nun betten wir die „ .qm “-Dateien in „ frogger_game “ und „ frogger_level_editor “ ein und legen ein benutzerdefiniertes Ressourcenpräfix fest.

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

Installation von .qm-Dateien

Anstatt die „ .qm “-Dateien einzubinden, können wir sie als reguläre 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 einem Verzeichnis „ translations “ ab 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
)

Dadurch werden die folgenden Dateien erstellt

• 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
)