Traductions basées sur les identifiants de texte

Le mécanisme de traduction par ID de texte est un système performant destiné à l'internationalisation et à la localisation. Chaque texte de l'application dispose d'un identifiant unique (ID de texte) que vous utilisez dans le code source à la place du texte. Cela facilite considérablement la gestion d'un grand nombre de textes traduits.

Internationalisation à l'aide d'identifiants de texte

Lorsque vous utilisez des identifiants de texte à la place du texte brut, la méthode générale d’internationalisation d’une application reste la même, mais les détails diffèrent légèrement :

1. Les fonctions et macros du système de traduction basé sur les ID de texte diffèrent de celles du système de texte brut. Vous utilisez la fonction `qsTrId()` à la place de `qsTr()`, la macro ` QT_TRID_NOOP()` à la place de ` QT_TR_NOOP()`, et la macro ` QT_TRID_N_NOOP()` à la place de ` QT_TR_N_NOOP()`.
2. Utilisez les identifiants de texte comme chaînes de l’interface utilisateur plutôt que comme chaînes de texte brut. Par exemple, qsTrId("id-back-not-front")
3. vous ne pouvez pas spécifier de paramètre de contexte avec un identifiant de texte ; par conséquent, des mots s’écrivant de la même manière mais ayant des significations différentes nécessitent des identifiants de texte distincts. Par exemple, qsTrId("id-back-backstep") distingue le « Back » (retour en arrière) du « Back » ( retour) de id-back-not-front.
4. Les noms de contexte n’étant pas autorisés pour les traductions basées sur des identifiants de texte, Qt Linguist répertorie les identifiants dans un fichier sans noms de contexte.
5. Le texte en anglais technique qui s’affiche dans l’interface utilisateur des versions de développement est signalé par un commentaire « //% ». Si vous n’incluez pas ce commentaire, l’identifiant de texte s’affiche dans l’interface utilisateur. Ceci est particulièrement important lorsque vous avez des textes comportant des paramètres. Le commentaire « //% » doit inclure les indicateurs de paramètres dans la chaîne de caractères. Par exemple, //% "Number of files: %1"
6. Les commentaires « //: » qui fournissent des informations supplémentaires au traducteur sont facultatifs dans le système en texte brut. Cependant, avec le système basé sur les identifiants de texte, ces informations supplémentaires deviennent essentielles car, sans elles, vous ne disposez que de l’identifiant de texte et le traducteur pourrait ne pas être en mesure de réaliser une traduction pertinente à partir de celui-ci sans contexte supplémentaire. Vous pouvez utiliser des identifiants de texte descriptifs longs et ne pas ajouter de commentaires, mais les commentaires sont souvent plus faciles à comprendre.

Les extraits de code ci-dessous, présentés côte à côte, montrent une comparaison entre les traductions basées sur les identifiants de texte et celles basées sur le texte brut :

Text {
    id: backTxt;
    //: The back of the object, not the front
    //% "Back"
    //~ Context Not related to back-stepping
    text: qsTrId("id-back-not-front");
}

Text {
    id: backTxt;
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back","Not front")
}

Localisation avec des identifiants de texte

La localisation à l'aide d'identifiants de texte suit globalement le même processus que pour le texte brut.

Vous utilisez l’outil lupdate pour générer les fichiers TS dans lesquels vous ajoutez les traductions. Les valeurs sources dans les fichiers de traduction seront des identifiants de texte plutôt que du texte brut ; vous aurez donc besoin soit d’identifiants de texte descriptifs, soit de commentaires supplémentaires pertinents, soit les deux, pour garantir l’exactitude des traductions.

L'exemple de texte d'interface utilisateur basé sur des identifiants de texte ci-dessus donne lieu au contenu suivant dans le fichier .ts :

<message id="id-back-not-front">
    <source>Back</source>
    <extracomment>The back of the object, not the front</extracomment>
    <translation type="unfinished"></translation>
    <extra-Context>Not related to back-stepping</extra-Context>
</message>

S’il n’existe aucune traduction disponible pour un texte donné (ce qui est généralement le cas jusqu’à un stade avancé du développement), l’identifiant de texte s’affichera dans l’interface utilisateur à la place du texte proprement dit. Afin de rendre l'application plus facile à utiliser pour les tests, vous pouvez configurer lrelease pour qu'il utilise le texte source en anglais technique (issu des commentaires « //% ») comme texte traduit et le marquer à l'aide d'un indicateur, tel qu'un point d'exclamation (!), ce qui vous permettra de repérer les textes qui n'ont pas encore été traduits.

Regroupement des traductions basées sur des identifiants

Vous pouvez attribuer un libellé à chaque traduction basée sur un ID afin d’organiser les entrées de grands projets en groupes plus petits. Pour attribuer un libellé à une entrée basée sur un ID, ajoutez un commentaire « //@ » indiquant le nom du libellé, par exemple en C++ :

//% "Open file"
//@ FileOperations
qtTrId("msg.open");

Ou en QML :

//% "Open file"
//@ FileOperations
qsTrId("msg.open");

Lorsque vous ouvrez le fichier TS dans Qt Linguist, les entrées basées sur un ID portant le même libellé sont regroupées, à l’instar des entrées textuelles qui sont regroupées par contexte. Tout élément sans libellé apparaît sous « <unnamed label> ».

Génération automatique des libellés

Au lieu de spécifier manuellement les noms de libellés, vous pouvez utiliser des espaces réservés pour générer automatiquement des libellés en fonction de la structure du code :

• //@ <context> - Utilise automatiquement le contexte complet (espace de noms::classe)
• //@ <class> - Utilise automatiquement uniquement le nom de la classe (sans espaces de noms)
• //@ <file> - Utilise automatiquement le nom du fichier source

Combinaison des espaces réservés

Les espaces réservés peuvent être combinés avec du texte personnalisé pour créer des étiquettes plus descriptives :

• //@ <file>:<class> - Combine le nom de fichier et la classe : filehandler.cpp:FileHandler
• //@ <context>_customSuffix - Ajoute un suffixe : MyApp::FileHandler_customSuffix
• //@ module_<file>_<class>-label - Préfixe et suffixe personnalisés : module_filehandler.cpp_FileHandler-label
• //@ <context>:<file> - Contexte avec le fichier : MyApp::FileHandler:filehandler.cpp

Par exemple, en C++ :

namespace MyApp {
class FileHandler : QObject {
    Q_OBJECT
    void open() {
        //% "Open file"
        //@ <context>
        qtTrId("msg.open"); // Label: MyApp::FileHandler

        //% "Save file"
        //@ <class>
        qtTrId("msg.save"); // Label: FileHandler

        //% "Export"
        //@ <file>
        qtTrId("msg.export"); // Label: filehandler.cpp
    }
};
}

Ou en QML :

Item {
    id: myComponent
    Component.onCompleted: {
        //% "Loading"
        //@ <context>
        qsTrId("msg.loading") // Label: <component-name>

        //% "Ready"
        //@ <file>
        qsTrId("msg.ready") // Label: main.qml

        //% "Initialized"
        //@ <file>:<context>-state
        qsTrId("msg.init") // Label: main.qml:<component-name>-state
    }
}

Les étiquettes automatiques sont particulièrement utiles dans les grands projets où la gestion manuelle des noms d’étiquettes dans de nombreux fichiers peut s’avérer fastidieuse. Elles garantissent un regroupement cohérent basé sur la structure du code et fournissent des indications aux traducteurs sur l’emplacement où la traduction sera utilisée.

Configuration CMake

Lors de la compilation avec CMake, utilisez le préfixe qml_ pour les fichiers .ts. Par exemple, qml_en.ts. Dans le fichier CMakeLists.txt, ajoutez la fonction qt_add_translations, dans laquelle vous listez les fichiers *.ts comme valeurs de TS_FILES, et définissez la valeur de RESOURCE_PREFIX sur l’URI du fichier main.qml du projet, suivi de /i18n :

qt_add_translations(${CMAKE_PROJECT_NAME}
    TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
    RESOURCE_PREFIX Main/i18n
)

Utilisation avancée avec qmake

Pour les projets ciblant un grand nombre de locales, vous pouvez supprimer les informations TRANSLATIONS du fichier .pro et, à la place, gérer les traductions à l’aide d’un script distinct. Ce script peut appeler lrelease et lupdate pour chacune des cibles souhaitées.

Les mises à jour pourraient être automatisées à l’aide d’un script similaire à celui-ci :

lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
...

La génération des fichiers .qm finaux pourrait être automatisée à l'aide d'un script comme celui-ci :

lrelease <project-dir>/i18n/myapp-text_en_GB.ts
lrelease <project-dir>/i18n/myapp-text_en_US.ts
...