Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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

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.

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.

Creating the PO template

Automatic generation using the editor

Since Godot 4.0, the editor can generate a PO template automatically from specified scene and script files. This POT generation also supports translation contexts and pluralization if used in a script, with the optional second argument of tr() and the tr_n() method.

Open the Project Settings' Localization > POT Generation tab, then use the Add… button to specify the path to your project's scenes and scripts that contain localizable strings:

Creating a PO template in the Localization > POT Generation tab of the Project Settings

Creating a PO template in the Localization > POT Generation tab of the Project Settings

After adding at least one scene or script, click Generate POT in the top-right corner, then specify the path to the output file. This file can be placed anywhere in the project directory, but it's recommended to keep it in a subdirectory such as locale, as each locale will be defined in its own file.

You can then move over to creating a messages file from a PO template.

Note

Remember to regenerate the PO template after making any changes to localizable strings, or after adding new scenes or scripts. Otherwise, newly added strings will not be localizable and translators won't be able to update translations for outdated strings.

Manual creation

If the automatic generation approach doesn't work out for your needs, you can create a PO template by hand in a text editor. This file can be placed anywhere in the project directory, but it's recommended to keep it in a subdirectory, as each locale will be defined in its own file.

Create a directory named locale in the project directory. In this directory, save a file named messages.pot with the following contents:

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

# Example of a regular string.
msgid "Hello world!"
msgstr ""

# Example of a string with pluralization.
msgid "There is %d apple."
msgid_plural "There are %d apples."
msgstr[0] ""
msgstr[1] ""

# Example of a string with a translation context.
msgctxt "Actions"
msgid "Close"
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.

Avertissement

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

Utilisation de fichiers binaires MO (utile uniquement pour les grands projets)

Pour les grands projets comportant plusieurs milliers de chaînes à traduire ou plus, il peut être intéressant d'utiliser des fichiers de messages MO binaires (compilés) plutôt que des fichiers PO textuels. Les fichiers MO binaires sont plus petits et plus rapides à lire que les fichiers PO équivalents.

Vous pouvez générer un fichier MO avec la commande ci-dessous :

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

Le fichier PO original doit être conservé dans le contrôle de version afin que vous puissiez mettre à jour votre traduction à l'avenir. Si vous perdez le fichier PO original et que vous souhaitez décompiler un fichier MO en un fichier PO textuel, utilisez la commande :

msgunfmt fr.mo > fr.po

Le fichier décompilé ne comprendra pas de commentaires ou de chaînes floues, car ceux-ci ne sont jamais compilés dans le fichier MO en premier lieu.