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 paquetage Qt6. Chargez le paquet avec :

find_package(Qt6 REQUIRED COMPONENTS LinguistTools)

Cette commande a été introduite dans Qt 6.2.

Synopsis

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 qt6_add_translations() à la place. 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 une enveloppe de commodité autour de qt_add_lupdate et qt_add_lrelease et vise à offrir l'utilisation la plus courante des deux fonctions en un seul appel.

Le paramètre TARGETS spécifie une liste de cibles qui ont l'intention de charger les fichiers .qm générés au moment 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 comme premier argument.

Le paramètre SOURCE_TARGETS spécifie une liste de cibles exécutables ou de bibliothèques qui contiennent des sources avec des chaînes traduisibles. Des fichiers .ts seront créés à partir des sources de ces cibles.

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. Cette fonctionnalité peut être désactivée avec l'argument IMMEDIATE_CALL.

Cette fonction crée la cible update_translations qui analyse tous les fichiers sources avec lupdate et 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 construite par défaut.

Les fichiers .ts peuvent être spécifiés avec 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.

Sources et répertoires d'inclusion

Avec SOURCES, vous pouvez spécifier explicitement des fichiers sources 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 des fichiers .ts qui sont utilisés comme entrée pour qt_add_translations peuvent être déterminés automatiquement si QT_I18N_TRANSLATED_LANGUAGES a été défini. Cette variable peut être définie de manière pratique avec 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 changer l'emplacement en passant un répertoire différent avec l'argument TS_OUTPUT_DIRECTORY.

Par défaut, les noms de fichiers .ts sont construits à partir de PROJECT_NAME. Vous pouvez spécifier un nom de base différent avec l'argument TS_FILE_BASE.

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

Avant Qt 6.9, l'argument TS_OUTPUT_DIRECTORY était appelé TS_FILE_DIR. Ce nom est toujours un alias pour TS_OUTPUT_DIRECTORY afin que les anciens fichiers de projet puissent continuer à fonctionner.

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 qui ne contient que des chaînes traduisibles pour les 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 les formes plurielles.

Un fichier .ts contenant uniquement des formes plurielles est automatiquement généré, 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 complète myapp_de.ts et le fichier de traduction au pluriel myapp_en.ts.

Options

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

Vous pouvez définir des options supplémentaires pour lupdate et lrelease à l'aide des options LUPDATE_OPTIONS et LRELEASE_OPTIONS. Vous trouverez les options possibles dans les options lupdate et lrelease.

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

Par défaut, les fichiers .qm seront placés dans le répertoire de construction 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 répertoire différent. Les chemins relatifs sont considérés comme étant inférieurs à CMAKE_CURRENT_BINARY_DIR.

Par exemple, avec le code suivant, les fichiers .qm sont générés dans un répertoire translations en dessous du répertoire de construction actuel.

qt_add_translations(app QM_OUTPUT_DIRECTORY translations)

Pour un contrôle plus fin, vous pouvez spécifier le répertoire de sortie des fichiers .qm individuels en définissant la propriété du fichier source OUTPUT_LOCATION sur le fichier .ts correspondant. Cette opération doit être effectuée avant d'appeler qt_add_translations.

La propriété de 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 construction 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 XML qui sera liée aux cibles transmises par TARGETS. Les fichiers de la ressource sont accessibles sous le préfixe de ressource "/i18n".

Vous pouvez définir le préfixe de la ressource avec RESOURCE_PREFIX.

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

Si OUTPUT_TARGETS est utilisé, IMMEDIATE_CALL ou SOURCE_TARGETS doit être spécifié.

L'intégration automatique des ressources peut être désactivée en passant 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 l'extraction des sources traduisibles et pour l'intégration des fichiers .qm.

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

Fusionner les 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 à qt_add_translations, ce qui déterminera les catalogues de traduction de Qt qui appartiennent aux modules utilisés par votre projet et les fusionnera dans les fichiers .qm produits par lrelease.

Les catalogues de traduction Qt sont déterminés par les appels à find_package dans la portée 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 supporte une langue pour laquelle Qt ne propose pas sa propre traduction, un avertissement sera émis au moment de la configuration. Vous pouvez supprimer cet avertissement en définissant la variable CMake QT_NO_MISSING_CATALOG_LANGUAGE_WARNING à 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 allemande et une traduction française à la cible frogger en utilisant 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 .ts frogger_de.ts et frogger_fr.ts dans le répertoire source. lupdate voit les fichiers sources de toutes les cibles qui sont éligibles pour la traduction, selon les règles de 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 est à peu près équivalent à 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 et tout ce qui se trouve dans le répertoire tests. Voir 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 source qui font 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 les cibles source de manière explicite :

qt_add_translations(frogger_game
    SOURCE_TARGETS frogger_game
)

Préfixe de ressource personnalisé

Intégrons maintenant les fichiers .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 comme des fichiers ordinaires :

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

Influencer les noms des fichiers .ts

Placez les fichiers .ts dans un répertoire translations et changez le nom de base en 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 les chemins explicitement :

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