Localisation à l'aide de gettext

In addition to Importation de traductions in CSV format, Godot also supports loading translation files written in the GNU gettext format (text-based .po and compiled .mo since Godot 3.5).

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.

  • People who maintain localization files will have to install gettext tools on their system. However, as Godot supports using text-based message files (.po), translators can test their work without having to install gettext tools.

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 : Installez gettext soit en utilisant Homebrew avec la commande brew install gettext, soit en utilisant MacPorts avec la commande sudo port 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 :

pip3 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

To register a messages file as a translation in a project, open the Project Settings, then go to the Localization tab. In Translations, click Add… then choose the .po or .mo file in the file dialog. The locale will be inferred from the "Language: <code>\n" property in the messages file.

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. 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.

Note

Apres avoir exécuté msgmerge, les chaînes de caractères modifiées dans la langue d'origine auront un commentaire ajouté devant elles dans le fichier .po. Ce commentaire signifie que la traduction doit être mise à jour pour correspondre à la nouvelle chaîne originale puisque la traduction peut ne plus être correcte.

Les chaînes de caractères avec des commentaires de traduction ne seront pas lus par Godot tant que la traduction n'est pas mise à jour et le commentaire retiré.

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.

Using binary MO files (useful for large projects only)

For large projects with several thousands of strings to translate or more, it can be worth it to use binary (compiled) MO message files instead of text-based PO files. Binary MO files are smaller and faster to read than the equivalent PO files.

You can generate a MO file with the command below:

msgfmt fr.po --no-hash -o fr.mo

If the PO file is valid, this command will create a fr.mo file besides the PO file. This MO file can then be loaded in Godot as described below.

The original PO file should be kept in version control so you can update your translation in the future. In case you lose the original PO file and wish to decompile a MO file into a text-based PO file, you can do so with:

msgunfmt fr.mo > fr.po

The decompiled file will not include comments or fuzzy strings, as these are never compiled in the MO file in the first place.