Traductions basées sur l'ID de texte

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

Internationalisation avec les ID de texte

Lorsque l'on utilise des ID de texte plutôt que du texte brut, la méthode générale d'internationalisation d'une application est la même, mais les détails sont un peu différents :

1. Les fonctions et les macros du système de traduction basé sur les ID de texte sont différentes de celles du système basé sur le texte brut. Vous utilisez la fonction qsTrId() au lieu de qsTr(), la macro QT_TRID_NOOP() au lieu de QT_TR_NOOP(), et la macro QT_TRID_N_NOOP() au lieu de QT_TR_N_NOOP()).
2. Utilisez les ID textuels comme chaînes d'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 un paramètre de contexte avec un identifiant de texte. Par conséquent, les mots orthographiés de manière identique mais ayant des significations différentes doivent avoir des identifiants de texte distincts. Par exemple, qsTrId("id-back-backstep") différencie la marche arrière Back de la marche arrière id-back-not-front.
4. Les noms de contexte n'étant pas autorisés pour les traductions basées sur les ID de texte, Qt Linguist répertorie les ID dans un fichier sans nom de contexte.
5. Le texte anglais d'ingénierie que vous voyez dans l'interface utilisateur pour les versions de développement est indiqué par un commentaire //%. Si vous ne l'incluez pas, l'ID du texte est affiché dans l'interface utilisateur. Ceci est particulièrement important lorsque vous avez des textes avec des paramètres. Le commentaire //% doit inclure les indicateurs de paramètres dans la chaîne. 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 l'ID de texte, ces informations supplémentaires deviennent essentielles car, sans elles, vous n'avez que l'ID de texte et le traducteur pourrait ne pas être en mesure de faire une traduction sensée à partir de ce texte sans contexte supplémentaire. Il est possible d'utiliser des ID de texte descriptifs longs et de ne pas utiliser de commentaires, mais les commentaires sont souvent plus faciles à comprendre.

Les extraits de code ci-dessous montrent une comparaison entre les traductions basées sur l'ID 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 à l'aide d'ID de texte

La localisation à l'aide d'identifiants de texte suit à peu près 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 des fichiers de traduction seront des ID de texte plutôt que du texte brut, et vous aurez donc besoin soit d'ID de texte descriptifs, soit de bons commentaires supplémentaires, soit des deux, pour garantir l'exactitude des traductions.

L'exemple d'interface utilisateur basée sur un ID de texte présenté ci-dessus donne le 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>

Si aucune traduction n'est disponible pour un texte donné (ce qui est généralement le cas jusqu'à un stade avancé du développement), l'interface utilisateur affichera l'identifiant du texte plutôt qu'un véritable texte. Afin de rendre l'application plus utilisable pour les tests, vous pouvez faire en sorte que lrelease utilise le texte source anglais d'ingénierie (provenant des commentaires de //% ) comme texte traduit et le marque d'un indicateur, tel qu'un point d'exclamation ( !), afin que vous puissiez voir les textes qui ne sont pas encore traduits.

Regroupement des traductions basées sur des identifiants

Vous pouvez attribuer une étiquette à chaque traduction basée sur l'identifiant afin d'organiser les entrées basées sur l'identifiant de grands projets en groupes plus petits. Pour attribuer un label à une entrée basée sur l'ID, ajoutez un commentaire à //@ en nommant le label, 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 Linguistles entrées basées sur l'ID ayant la même étiquette sont regroupées, de la même manière que les entrées basées sur le texte sont regroupées par contexte. Tout élément sans étiquette apparaît sous <unnamed label>.

Génération automatique d'étiquettes

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

• //@ <context> - Utilise automatiquement le contexte complet (namespace::class)
• //@ <class> - Utilise automatiquement uniquement le nom de la classe (sans espace 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 donnent des indications aux traducteurs sur l'endroit où la traduction sera utilisée.

Configuration de CMake

Lors de la construction 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, où vous listez les fichiers *.ts comme valeurs de TS_FILES, et définissez la valeur de RESOURCE_PREFIX à l'URI du fichier main.qml pour le 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 de qmake

Pour les projets qui visent un grand nombre de langues, vous pouvez supprimer l'information TRANSLATIONS du fichier .pro et, à la place, gérer les traductions à l'aide d'un script séparé. Le script peut appeler lrelease et lupdate pour chacune des cibles souhaitées.

Les mises à jour pourraient être programmées de la manière suivante :

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 scriptée de la manière suivante :

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