qt_add_translations

Ajouter des cibles pour mettre à jour et transformer les fichiers .ts de Qt Linguist en fichiers .qm.

La commande est définie dans le composant LinguistTools du paquet Qt6. Chargez le paquet à l'aide de la commande suivante :

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

Cette commande a été introduite dans Qt 6.2.

Syntaxe

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

Depuis Qt 6.2 (obsolète) :

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

Si les commandes sans version sont désactivées, utilisez plutôt qt6_add_translations(). Elle prend en charge le même ensemble d'arguments que cette commande.

Description

Crée des cibles pour mettre à jour les fichiers Qt Linguist .ts et pour les transformer en fichiers .qm. Cette fonction est un wrapper pratique autour de qt_add_lupdate() et qt_add_lrelease() et vise à offrir l’utilisation la plus courante de ces deux fonctions en un seul appel.

Le paramètre TARGETS spécifie une liste de cibles destinées à charger les fichiers .qm générés lors de l'exécution. S'il n'y a qu'une seule cible de ce type, vous pouvez passer directement le nom de la cible en tant que premier argument.

Le paramètre SOURCE_TARGETS spécifie une liste de cibles exécutables ou de bibliothèques contenant des sources avec des chaînes traduisibles. À partir des sources de ces cibles, des fichiers d'.ts s seront créés.

Si SOURCE_TARGETS n’est pas fourni, les cibles sont automatiquement rassemblées en appelant qt_collect_translation_source_targets() à la fin de la portée du répertoire de PROJECT_SOURCE_DIR. Cette fonctionnalité nécessite CMake 3.19 ou une version plus récente. Elle peut être désactivée à l’aide de l’argument IMMEDIATE_CALL.

Cette fonction crée la cible update_translations qui analyse tous les fichiers source à l’aide de lupdate, puis crée et met à jour les fichiers .ts.

Cette fonction crée la cible release_translations qui génère les fichiers .qm à partir des fichiers .ts. Cette cible est activée par défaut.

Les fichiers .ts peuvent être spécifiés à l’aide de l’argument TS_FILES, mais il est plus pratique de laisser qt_add_translations déterminer automatiquement les chemins d’accès aux fichiers. Voir Détermination automatique des chemins d’accès aux fichiers .ts pour plus de détails.

Fichiers sources et répertoires d’inclusion

Avec SOURCES, vous pouvez spécifier explicitement des fichiers source supplémentaires contenant des chaînes traduisibles.

Vous pouvez utiliser ` INCLUDE_DIRECTORIES ` pour spécifier explicitement les répertoires d’inclusion de ces fichiers source.

Détermination automatique des chemins d’accès aux fichiers .ts

Les chemins d’accès aux fichiers d’ .ts utilisés comme entrée pour « qt_add_translations » peuvent être déterminés automatiquement si la variable QT_I18N_TRANSLATED_LANGUAGES a été définie. Cette variable peut être définie facilement à l’aide de la fonction qt_standard_project_setup().

La configuration de projet suivante est généralement suffisante :

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)

Cela créera les fichiers myproject_de.ts et myproject_fr.ts dans le répertoire source du projet.

Par défaut, les fichiers « .ts » sont créés dans « CMAKE_CURRENT_SOURCE_DIR ». Vous pouvez modifier cet emplacement en passant un autre répertoire avec l’argument « TS_OUTPUT_DIRECTORY ».

Par défaut, les noms des fichiers « .ts » sont dérivés de « PROJECT_NAME ». Vous pouvez spécifier un nom de base différent à l’aide de l’argument « TS_FILE_BASE ».

Depuis Qt 6.8, vous pouvez spécifier l’argument TS_FILES_OUTPUT_VARIABLE pour stocker dans une variable les chemins d’accès aux fichiers .ts déterminés automatiquement.

Avant Qt 6.9, l’argument TS_OUTPUT_DIRECTORY s’appelait TS_FILE_DIR. Ce nom reste un alias de TS_OUTPUT_DIRECTORY afin de garantir la compatibilité avec les anciens fichiers de projet.

Formes plurielles

QT_I18N_SOURCE_LANGUAGE spécifie la langue dans laquelle les chaînes du code source sont écrites. Pour gérer correctement les formes plurielles, créez un fichier .ts supplémentaire pour cette langue, contenant uniquement les chaînes traduisibles relatives aux formes plurielles. Voir Gestion des formes plurielles pour plus de détails.

Avec ` PLURALS_TS_FILE `, vous pouvez spécifier le fichier ` .ts ` pour la langue source. Ce fichier ne contiendra que des formes plurielles.

Un fichier ` .ts ` contenant uniquement les pluriels est généré automatiquement, sauf si l’option ` NO_GENERATE_PLURALS_TS_FILE ` est spécifiée.

Si vous avez besoin d’une traduction complète de la langue source, ajoutez-la à QT_I18N_TRANSLATED_LANGUAGES

Par exemple,

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)

crée le fichier de traduction complet myapp_de.ts et le fichier contenant uniquement les pluriels myapp_en.ts.

Options

Vous pouvez spécifier le nom de la cible personnalisée qui appelle lupdate à l’aide de l’option LUPDATE_TARGET. De même, LRELEASE_TARGET contrôle le nom de la cible personnalisée qui déclenche l’appel à lrelease.

Vous pouvez définir des options supplémentaires pour lupdate et lrelease à l’aide de LUPDATE_OPTIONS et LRELEASE_OPTIONS. Vous trouverez les options disponibles dans les sections Options de lupdate et Options de lrelease.

Emplacement des fichiers .qm générés

Par défaut, les fichiers .qm sont placés dans le répertoire de compilation actuel (CMAKE_CURRENT_BINARY_DIR). Depuis Qt 6.9, vous pouvez utiliser l’argument QM_OUTPUT_DIRECTORY pour générer les fichiers .qm dans un autre répertoire. Les chemins relatifs sont considérés comme se trouvant sous CMAKE_CURRENT_BINARY_DIR.

Par exemple, avec le code suivant, les fichiers .qm sont générés dans un répertoire translations situé sous le répertoire de compilation actuel.

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

Pour un contrôle plus précis, vous pouvez spécifier le répertoire de sortie de chaque fichier .qm en définissant la propriété du fichier source OUTPUT_LOCATION dans le fichier .ts correspondant. Cette opération doit être effectuée avant d’appeler qt_add_translations.

La propriété du fichier source « OUTPUT_LOCATION » remplace le répertoire transmis via « QM_OUTPUT_DIRECTORY ».

Par exemple, avec le code suivant, les fichiers .qm sont générés dans un répertoire translations situé sous le répertoire de compilation actuel.

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

Intégration des fichiers .qm générés dans les ressources

Par défaut, les fichiers .qm générés sont intégrés dans une ressource Qt qui sera liée aux cibles passées avec TARGETS. Les fichiers de la ressource sont accessibles sous le préfixe de ressource "/i18n".

Vous pouvez définir le préfixe de ressource à l’aide de ` RESOURCE_PREFIX`.

Dans une compilation Qt statique, lorsqu’une cible de ressource est créée, des cibles supplémentaires peuvent être générées. Vous pouvez demander à ` qt_add_translations ` de stocker ces cibles dans une variable, en passant ` OUTPUT_TARGETS <variable-name>`.

Si la commande OUTPUT_TARGETS est utilisée, il faut spécifier soit IMMEDIATE_CALL, soit SOURCE_TARGETS.

L'intégration automatique des ressources peut être désactivée en indiquant l'option QM_FILES_OUTPUT_VARIABLE, suivie du nom d'une variable dans laquelle la commande doit stocker la liste des fichiers .qm générés.

qt_add_translations Avant Qt 6.7

Avant Qt 6.7, cette commande n'acceptait qu'une seule cible comme premier argument. Cette cible était utilisée à la fois pour extraire les sources traduisibles et pour intégrer les fichiers .qm.

Depuis Qt 6.7, la cible du premier argument n’est plus utilisée pour l’extraction des sources.

Fusion des traductions fournies par Qt

Depuis Qt 6.9, vous pouvez fusionner les traductions fournies par Qt dans des fichiers « .qm » spécifiques à l’application. Pour ce faire, passez l’option « MERGE_QT_TRANSLATIONS » à la commande « qt_add_translations ». Cela permettra de déterminer les catalogues de traduction Qt appartenant aux modules utilisés par votre projet et de les fusionner dans les fichiers « .qm » générés par la commande « lrelease ».

Les catalogues de traduction Qt sont déterminés par les appels à ` find_package ` dans le cadre de votre ` CMakeLists.txt ` où ` qt_add_translations ` est appelé. Par exemple, la séquence suivante fusionnera les catalogues ` qtbase ` et ` qtmultimedia ` dans vos fichiers ` .qm ` :

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

Pour spécifier explicitement les catalogues, utilisez l’argument QT_TRANSLATION_CATALOGS:

qt_add_translations(my_app
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase qtmultimedia
)

Si votre projet prend en charge une langue pour laquelle Qt ne propose pas sa propre traduction, un avertissement sera émis lors de la phase de configuration. Vous pouvez supprimer cet avertissement en définissant la variable CMake QT_NO_MISSING_CATALOG_LANGUAGE_WARNING sur ON.

Si la détermination automatique des noms de fichiers ` .ts ` n’est pas utilisée, vous devez vous assurer que la propriété de fichier source ` QT_I18N_TRANSLATED_LANGUAGES ` est définie sur chacun des fichiers ` .ts `.

Exemples

Ajoutez une traduction en allemand et en français à la cible frogger à l’aide de 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)

Cela créera les fichiers d’ .ts frogger_de.ts et frogger_fr.ts dans le répertoire source. lupdate détecte les fichiers source de toutes les cibles pouvant faire l’objet d’une traduction, conformément aux règles de la fonction qt_collect_translation_source_targets().

Les fichiers .qm créés à partir des fichiers .ts sont intégrés dans la cible frogger_game sous le préfixe de ressource "i18n".

L’appel à ` qt_add_translations ` dans l’exemple ci-dessus équivaut globalement à ce qui suit :

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

Exclusion de répertoires, de cibles et de sources

Vous pouvez exclure des cibles et des répertoires de la collecte automatique des cibles source. L’exemple suivant exclut la cible helper_lib ainsi que tout ce qui se trouve dans le répertoire tests. Reportez-vous à la propriété de répertoire QT_EXCLUDE_FROM_TRANSLATION et à la propriété de cible 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)

Dans l’exemple suivant, nous excluons les fichiers sources faisant partie de la cible frogger_game à l’aide de la propriété de cible QT_EXCLUDE_SOURCES_FROM_TRANSLATION:

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

Spécification explicite des cibles source

Si vous ne souhaitez pas utiliser la collecte automatique des cibles source, vous pouvez spécifier ces cibles de manière explicite :

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Préfixe de ressource personnalisé

Intégrons à présent les fichiers d'.qm dans frogger_game et frogger_level_editor et définissons un préfixe de ressource personnalisé.

qt_add_translations(
    TARGETS frogger_game frogger_level_editor
    RESOURCE_PREFIX "/translations"
)

Installation des fichiers .qm

Au lieu d’intégrer les fichiers .qm, nous pouvons les installer en tant que fichiers classiques :

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

Modification des noms des fichiers .ts

Placez les fichiers .ts dans un répertoire translations et remplacez le nom de base par frogger_i18n:

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

Cela crée les fichiers suivants

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

Vous pouvez également spécifier explicitement les chemins d’accès :

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