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