Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Localisation à l'aide de gettext (Fichiers PO)

In addition to importing translations in CSV format, Godot also supports loading translation files written in the GNU gettext format (text-based .po and compiled .mo).

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

For the complete documentation, see GNU Gettext.

Avantages

• gettext is a standard format, which can be edited using any text editor or GUI editors such as Poedit. This can be significant as it provides a lot of tools for translators, such as marking outdated strings, finding strings that haven't been translated, etc.

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

• Compared to CSV, gettext files work better with version control systems like Git, as each locale has its own messages file.

• Multiline strings are more convenient to edit in gettext PO files compared to CSV files.

Désavantages

• gettext PO files have a more complex format than CSV and can be harder to grasp for people new to software localization.

• Les personnes qui maintiennent les fichiers de localisation devront installer les outils gettext sur leur système. Cependant, comme Godot supporte l'utilisation de fichiers de messages basés sur du texte (.po), les traducteurs peuvent tester leur travail sans installer les outils gettext.

• gettext PO files usually use English as the base language. Translators will use this base language to translate to other languages. You could still user other languages as the base language, but this is not common.

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.

For a GUI tool you can get Poedit from its Official website. The basic version is open source and available under the MIT license.

Creating the PO template

Automatic generation using the editor

The editor can generate a PO template automatically from specified scene and GDScript 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 Project > Project Settings > Localization > Template Generation, 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 > Template Generation tab of the Project Settings

After adding at least one scene or script, click Generate in the top-right corner, then specify the path to the output file with a pot file extension. 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.

See below for how to add comments for translators or exclude some strings from being added to the PO template for GDScript files.

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.

Création manuelle

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 content:

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

If you open with Poeditor, it will display the appropriate warnings if there's some syntax errors. You can also verify by running the gettext command below:

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.

You can generate an MO file with the command below:

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

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

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 an MO file into a text-based PO file, you can do so with:

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.

Extracting localizable strings from GDScript files

The built-in editor plugin recognizes a variety of patterns in source code to extract localizable strings from GDScript files, including but not limited to the following:

• tr(), tr_n(), atr(), and atr_n() calls;

• assigning properties text, placeholder_text, and tooltip_text;

• add_tab(), add_item(), set_tab_title(), and other calls;

• FileDialog filters like "*.png ; PNG Images".

Note

The argument or right operand must be a constant string, otherwise the plugin will not be able to evaluate the expression and will ignore it.

If the plugin extracts unnecessary strings, you can ignore them with the NO_TRANSLATE comment. You can also provide additional information for translators using the TRANSLATORS: comment. These comments must be placed either on the same line as the recognized pattern or precede it.

$CharacterName.text = "???" # NO_TRANSLATE

# NO_TRANSLATE: Language name.
$TabContainer.set_tab_title(0, "Python")

item.text = "Tool" # TRANSLATORS: Up to 10 characters.

# TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
# make sure to keep this as it is important to the plot.
say(tr("He took his vorpal sword in hand. The end?"))

Using context

The context parameter can be used to differentiate the situation where a translation is used, or to differentiate polysemic words (words with multiple meanings).

Par exemple :

tr("Start", "Main Menu")
tr("End", "Main Menu")
tr("Shop", "Main Menu")
tr("Shop", "In Game")

In a gettext PO file, a string with a context can be defined as follows:

# Example of a string with a translation context.
msgctxt "Main Menu"
msgid "Shop"
msgstr ""

# A different source string that is identical, but with a different context.
msgctxt "In Game"
msgid "Shop"
msgstr ""

Updating PO files

Some time or later, you'll add new content to our game, and there will be new strings that need to be translated. When this happens, you'll need to update the existing PO files to include the new strings.

First, generate a new POT file containing all the existing strings plus the newly added strings. After that, merge the existing PO files with the new POT file. There are two ways to do this:

• Use a gettext editor, and it should have an option to update a PO file from a POT file.

• Use the gettext msgmerge tool:

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

POT generation custom plugin

If you have any extra file format to deal with, you could write a custom plugin to parse and and extract the strings from the custom file. This custom plugin will extract the strings and write into the POT file when you hit Generate POT. To learn more about how to create the translation parser plugin, see EditorTranslationParserPlugin.