Référence aux méta-chaînes

Les méta-chaînes sont des commentaires spéciaux qui fournissent des informations supplémentaires à lupdate et à Qt Linguist pour le traitement des traductions. Elles utilisent des préfixes spécifiques pour identifier leur but et peuvent être utilisées dans du code C++, QML et Python.

Aperçu de la syntaxe des méta-chaînes

Les méta-chaînes sont des commentaires spéciaux qui utilisent des préfixes spécifiques pour fournir à lupdate des informations supplémentaires sur les traductions :

Commentaires du traducteur (// :)

Utilisez les commentaires de //: pour fournir un contexte supplémentaire et des conseils aux traducteurs. Ces commentaires apparaissent dans l'interface de traduction Qt Linguist et aident les traducteurs à comprendre la signification et l'utilisation du texte.

Exemple C++

//: Button to navigate backwards in the application
tr("Back");

//: This is a file menu item that opens an existing document.
//: Keep translation short to fit in menu.
tr("Open");

Exemple QML

Button {
  //: Emergency stop button - must be clearly visible
  text: qsTr("STOP")
}

Exemple Python

#: Button to navigate backwards in the application
self.tr("Back")

#: This is a file menu item that opens an existing document.
#: Keep translation short to fit in menu.
self.tr("Open")

Plusieurs commentaires de traducteurs peuvent être utilisés pour la même chaîne de caractères et seront concaténés avec des nouvelles lignes dans le fichier TS.

Format du fichier TS

Les commentaires du traducteur apparaissent comme des éléments <extracomment> dans le fichier TS :

<message>
    <source>Back</source>
    <extracomment>Button to navigate backwards in the application</extracomment>
    <translation type="unfinished"></translation>
</message>

Texte source (//%)

La méta-chaîne //% définit le texte anglais d'ingénierie qui apparaît dans l'interface utilisateur pendant le développement lors de l'utilisation de traductions basées sur l'ID. Ce texte est essentiel pour rendre l'application utilisable avant que les traductions ne soient terminées.

Exemple C++

//% "Save Document"
qtTrId("file.save");

//% "Found %n items"
qtTrId("search.results", count);

Exemple QML

Text {
  //% "Welcome to the application"
  text: qsTrId("welcome.message")
}

Remarques importantes

• Inclure les caractères de remplacement des paramètres (%1, %n) dans le texte source.
• Le texte source doit être un anglais prêt pour la production
• Sans les commentaires //%, l'ID du texte lui-même apparaît dans l'interface utilisateur.

Format du fichier TS

Le texte source apparaît comme l'élément <source>:

<message id="file.save">
    <source>Save Document</source>
    <translation type="unfinished"></translation>
</message>

Étiquettes (//@)

Utilisez les méta-chaînes //@ pour organiser les traductions basées sur l'ID en groupes ou catégories logiques au sein de Qt Linguist. Ceci est particulièrement utile pour les grands projets comportant de nombreuses chaînes de traduction.

Exemple C++

//% "New Document"
//@ FileOperations
qtTrId("file.new");

//% "Print Document"
//@ FileOperations
qtTrId("file.print");

//% "Connection failed"
//@ NetworkErrors
qtTrId("network.error.connection");

Exemple QML

Button {
  //% "Login"
  //@ Authentication
  text: qsTrId("auth.login")
}

Les chaînes de caractères ayant la même étiquette sont regroupées dans Qt Linguist, ce qui permet aux traducteurs de travailler plus facilement sur des contenus connexes.

Pour la génération automatique d'étiquettes à l'aide de caractères génériques tels que <context>, <class>, <file>, et leurs combinaisons, voir Génération automatique d'étiquettes.

Format de fichier TS

Les étiquettes apparaissent sous la forme d'un élément label:

<message id="file.new" label="FileOperations">
    <source>New Document</source>
    <label>FileOperations</label>
    <translation type="unfinished"></translation>
</message>

Métadonnées supplémentaires (//~)

La chaîne méta //~ vous permet d'attacher des métadonnées clés-valeurs arbitraires aux traductions. Ces métadonnées peuvent être utilisées pour un traitement personnalisé ou pour guider le traducteur.

Syntaxe

//~ key value
//~ key "quoted value with spaces"

Exemple C++

//% "Error"
//: Critical system error dialog
//~ Severity High
//~ MaxLength "20"
//~ Context "Error dialogs"
qtTrId("system.error");

Exemple QML

Text {
  //% "Loading..."
  //~ Context "Progress indicators"
  //~ ShowDuration "true"
  text: qsTrId("progress.loading")
}

Exemple Python

#~ Severity High
#~ Context "Error dialogs"
self.tr("Critical system error")

Format de fichier TS

Les métadonnées supplémentaires apparaissent sous la forme d'éléments <extra-*> dans le fichier TS et peuvent être traitées par des outils personnalisés ou des flux de traduction.

<message id="system.error">
    <source>Error</source>
    <comment>Critical system error dialog</comment>
    <translation type="unfinished"></translation>
    <extra-Severity>High</extra-Severity>
    <extra-MaxLength>20</extra-MaxLength>
    <extra-Context>Error dialogs</extra-Context>
</message>

Clés supplémentaires reconnues

Bien que n'importe quelle clé puisse être utilisée avec //~, l'indicateur no-wrap dans po-flags est reconnu par lconvert. Voir les options spécifiques au format PO.

Commentaires magiques du TRADUCTEUR

TRANSLATOR Les commentaires fournissent des informations contextuelles sur une classe ou un fichier source afin d'aider les traducteurs à comprendre où les traductions sont utilisées.

Exemple C++

/*
  TRANSLATOR MainWindow

  This class contains the main application window interface.
  All menu items and toolbar buttons are defined here.
*/
class MainWindow : public QMainWindow
{
  // ... translations for this context
};

Exemple QML

// TRANSLATOR LoginDialog Login dialog for user authentication
Item {
  Text {
      text: qsTr("Username")
  }
}

Exemple Python

# TRANSLATOR MainWindow
#
# Main application window containing the primary user interface.
# Keep button labels concise due to space constraints.
#
class MainWindow(QMainWindow):
  def setupUi(self):
      self.tr("File")  # translations for this context

Format de fichier TS

Les commentaires TRANSLATOR apparaissent sous la forme d'éléments <message> avec un texte source vide sur l'élément <context>:

<context>
    <name>Main</name>
    <message>
        <source></source>
        <comment>LoginDialog Login dialog for user authentication</comment>
        <translation></translation>
    </message>
</context>

Combinaison de méta-chaînes

Les méta-chaînes peuvent être combinées pour fournir des métadonnées de traduction complètes :

Exemple complet en C++

//: File dialog - confirm destructive action
//: This will permanently delete the selected files
//% "Delete Selected Files"
//@ FileOperations
//~ Severity High
//~ RequiresConfirmation "true"
qtTrId("file.delete.confirm");

Exemple complet en QML

Text {
  //: Shows current connection status to server
  //: Updates automatically every few seconds
  //% "Connected to server"
  //@ NetworkStatus
  //~ UpdateFrequency "5000ms"
  //~ Color "green"
  text: qsTrId("status.connected")
}

Meilleures pratiques

• Utiliser généreusement les commentaires du traducteur (// :) pour fournir un contexte.
• Toujours inclure le texte source (//%) pour les traductions basées sur l'ID
• Regrouper les traductions apparentées à l'aide d'étiquettes (//@) dans les grands projets
• Placer les méta-chaînes immédiatement avant l'appel à la fonction de traduction
• Les commentaires du traducteur doivent être clairs et concis, mais informatifs.
• Utiliser des noms cohérents pour les étiquettes et les clés de métadonnées supplémentaires