Localisation à l'aide de gettext

En plus de Importation de traductions au format CSV, Godot supporte également le chargement de fichiers de traduction écrits au format GNU gettext (.po).

Note

Pour une introduction à gettext, regardez A Quick Gettext Tutorial. Il est écrit avec les projets C en tête, mais une grande partie des conseils s'appliquent aussi à Godot (à l'exception de xgettext).

Avantages

  • gettext est un format standard, qui peut être édité en utilisant n'importe quel éditeur de texte ou d'interface graphique comme Poedit.
  • gettext est pris en charge par des plateformes de traduction telles que Transifex et Weblate, ce qui facilite la collaboration des traducteurs pour la localisation.
  • Comparé au CSV, gettext fonctionne mieux avec les systèmes de contrôle de version comme Git, car chaque région a son propre fichier de messages.
  • Les chaînes(strings) multilignes sont plus pratiques à éditer dans les fichiers gettext que dans les fichiers CSV.

Désavantages

  • gettext est un format plus complexe que le CSV et peut être plus difficile à appréhender pour les personnes qui ne connaissent pas la localisation de logiciels.
  • Les personnes qui maintiennent les fichiers de localisation devront installer les outils gettext sur leur système. Cependant, comme Godot n'utilise pas de fichiers d'objets de messages compilés (.mo), les traducteurs peuvent tester leur travail sans avoir à installer les outils gettext.

Mises en garde

  • Comme Godot utilise son propre analyseur de fichiers PO en coulisse (qui est plus limité que l'implémentation GNU gettext de référence), certaines fonctionnalités telles que la pluralisation ne sont pas supportées.

Installation des outils gettext

Les outils gettext en ligne de commande sont nécessaires pour effectuer les opérations de maintenance, telles que la mise à jour des fichiers de messages. Il est donc fortement recommandé de les installer.

  • Windows : Téléchargez le programme d'installation à partir de cette page. Toute architecture et tout type de binaire (partagé ou statique) fonctionne ; en cas de doute, choisissez le programme d'installation statique 64 bits.
  • macOS : Utilisez Homebrew pour installer gettext avec la commande brew install gettext.
  • Linux : Sur la plupart des distributions, installez le paquet gettext depuis le gestionnaire de paquets de votre distribution.

Création manuelle du modèle PO (POT)

Godot ne supporte pas actuellement l'extraction de chaînes de caractères source en utilisant xgettext, donc le fichier .pot doit être créé manuellement. Ce fichier peut être placé n'importe où dans le répertoire du projet, mais il est recommandé de le conserver dans un sous-répertoire, car chaque région sera définie dans son propre fichier.

Créez un répertoire nommé locale dans le répertoire du projet. Dans ce répertoire, sauvegardez un fichier nommé messages.pot avec le contenu suivant :

# Don't remove the two lines below, they're required for gettext to work correctly.
msgid ""
msgstr ""

msgid "Hello world!"
msgstr ""

Les messages dans gettext sont constitués de paires msgid et msgstr. msgid est la chaîne source (généralement en anglais), msgstr sera la chaîne traduite.

La valeur msgstr dans les fichiers de gabarit PO (.pot) devrait toujours être vide. La localisation sera faite dans les fichiers .po générés à la place.

Création du modèle PO (POT) à l'aide de pybabel

L'outil Python pybabel supporte Godot et peut être utilisé pour créer et mettre à jour automatiquement le fichier POT à partir de vos fichiers de scènes et de vos scripts.

Après l'installation de babel et babel-godot, par exemple en utilisant pip :

pip install babel babel-godot

Écrivez un fichier de mapping (par exemple babelrc) qui indiquera quels fichiers pybabel doit traiter (notez que nous traitons GDScript en Python, ce qui est généralement suffisant) :

[python: **.gd]
encoding = utf-8

[godot_scene: **.tscn]
encoding = utf-8

Vous pouvez alors exécuter pybabel comme cela :

pybabel extract -F babelrc -k text -k LineEdit/placeholder_text -k tr -o godot-l10n.pot .

Utilisez l'option -k pour spécifier ce qui doit être extrait. Dans ce cas, les arguments de tr() seront traduits, ainsi que les propriétés nommées "text" (couramment utilisées par les nœuds de contrôle) et la propriété "placeholder_text" de LineEdit.

Création d'un fichier de messages à partir d'un modèle PO

La commande msginit est utilisée pour transformer un modèle de PO en un fichier de messages. Par exemple, pour créer un fichier de localisation français, utilisez la commande suivante lorsque vous êtes dans le répertoire locale :

msginit --no-translator --input=messages.pot --locale=fr

La commande ci-dessus va créer un fichier nommé fr.po dans le même répertoire que le modèle de PO.

Vous pouvez aussi le faire graphiquement en utilisant Poedit, ou en téléchargeant le fichier POT sur la plateforme web de votre choix.

Chargement d'un fichier de messages dans Godot

Pour enregistrer un fichier de messages en tant que traduction dans un projet, ouvrez les Paramètres du projet, puis allez à l'onglet Localisation. Dans Traductions, cliquez sur Ajouter... puis choisissez le fichier .po dans la boîte de dialogue des fichiers. La région sera déduite de la propriété "Language: <code>\n" dans le fichier des messages.

Note

Voir Internationaliser des jeux pour plus d'informations sur l'importation et le test des traductions dans Godot.

Mise à jour des fichiers de messages pour suivre le modèle PO

Après la mise à jour du modèle PO, vous devrez mettre à jour les fichiers de message afin qu'ils contiennent de nouvelles chaînes, tout en supprimant les chaînes qui ne sont plus présentes dans le modèle PO supprimé dans le modèle PO. Cela peut être fait automatiquement à l'aide de l'outil msgmerge :

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

Si vous voulez garder une sauvegarde du fichier de message original (qui serait sauvegardé sous fr.po~ dans cet exemple), supprimez l'argument --backup=none.

Vérification de la validité d'un fichier ou d'un modèle PO

Il est possible de vérifier si la syntaxe d'un fichier gettext est valide en exécutant la commande ci-dessous :

msgfmt fr.po --check

S'il y a des erreurs de syntaxe ou des avertissements, ils seront affichés dans la console. Sinon, msgfmt ne donnera rien.