Référence des 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 de la traduction. Elles utilisent des préfixes spécifiques pour identifier leur fonction et peuvent être utilisées dans du code C++, QML et Python.

Présentation 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 des commentaires « //: » pour fournir un contexte supplémentaire et des indications aux traducteurs. Ces commentaires apparaissent dans l'interface de traduction d'Qt Linguist et aident les traducteurs à comprendre le sens et l'utilisation du texte.

Exemple en 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 en QML

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

Exemple en 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 du traducteur peuvent être utilisés pour une même chaîne de caractères ; ils seront concaténés avec des sauts de ligne dans le fichier TS.

Format du fichier TS

Les commentaires des traducteurs apparaissent sous la forme d'é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 en anglais technique qui s'affiche dans l'interface utilisateur pendant le développement lorsque l'on utilise des traductions basées sur des identifiants. Cela est essentiel pour rendre l'application utilisable avant que les traductions ne soient terminées.

Exemple en C++

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

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

Exemple en QML

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

Remarques importantes

• Incluez les espaces réservés aux paramètres (%1, %n) dans le texte source
• Le texte source doit être rédigé en anglais prêt à être utilisé en production
• Sans commentaires //%, l'identifiant du texte apparaît tel quel dans l'interface utilisateur

Format de fichier TS

Le texte source apparaît sous la forme de 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 des identifiants en groupes ou catégories logiques au sein de Qt Linguist. Cela s’avère particulièrement utile pour les projets volumineux comportant de nombreuses chaînes de traduction.

Exemple en C++

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

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

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

Exemple en QML

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

Les chaînes portant le même libellé apparaissent regroupées dans Qt Linguist, ce qui facilite le travail des traducteurs sur les contenus associés.

Pour la génération automatique d’étiquettes à l’aide d’espaces réservés tels que <context>, <class>, <file> et leurs combinaisons, consultez la section Génération automatique d’étiquettes.

Format de fichier TS

Les libellés 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 de métadonnées //~ vous permet d’associer des métadonnées de type clé-valeur arbitraires aux traductions. Cela peut être utilisé pour un traitement personnalisé ou pour guider le traducteur.

Syntaxe

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

Exemple en C++

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

Exemple en QML

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

Exemple en Python

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

Format de fichier TS

Les métadonnées supplémentaires apparaissent sous forme d'éléments <extra-*> dans le fichier TS et peuvent être traitées par des outils personnalisés ou des workflows 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 ` //~`, le drapeau ` no-wrap ` contenu dans ` po-flags ` est reconnu par ` lconvert`. Voir les options spécifiques au format PO.

Commentaires magiques TRANSLATOR

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 en 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 en 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 QML complet

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

Bonnes pratiques

• Utilisez généreusement les commentaires du traducteur (//:) pour fournir du contexte
• Incluez toujours le texte source (//%) pour les traductions basées sur des identifiants
• Regroupez les traductions associées à l’aide d’étiquettes (//@) dans les projets de grande envergure
• Placez les chaînes méta immédiatement avant l'appel à la fonction de traduction
• Veillez à ce que les commentaires des traducteurs soient clairs, concis et informatifs
• Utilisez une nomenclature cohérente pour les étiquettes et les clés de métadonnées supplémentaires