Localization using gettext
Note
For an introduction to gettext, check out . It’s written with C projects in mind, but much of the advice also applies to Godot (with the exception of xgettext
).
- gettext is a standard format, which can be edited using any text editor or GUI editors such as Poedit.
- gettext is supported by translation platforms such as and Weblate, which makes it easier for people to collaborate to localization.
- Compared to CSV, gettext works better with version control systems like Git, as each locale has its own messages file.
- Multiline strings are more convenient to edit in gettext files compared to CSV files.
Disadvantages
- gettext is a more complex format than CSV and can be harder to grasp for people new to software localization.
Caveats
- As Godot uses its own PO file parser behind the scenes (which is more limited than the reference GNU gettext implementation), some features such as pluralization aren’t supported.
The command line gettext tools are required to perform maintenance operations, such as updating message files. Therefore, it’s strongly recommended to install them.
- Windows: Download an installer from . Any architecture and binary type (shared or static) works; if in doubt, choose the 64-bit static installer.
- macOS: Use Homebrew to install gettext with the
brew install gettext
command. - Linux: On most distributions, install the
gettext
package from your distribution’s package manager.
Creating the PO template (POT) manually
Godot currently doesn’t support extracting source strings using xgettext
, so the .pot
file must be created manually. 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:
Messages in gettext are made of msgid
and msgstr
pairs. is the source string (usually in English), msgstr
will be the translated string.
Creating the PO template (POT) using pybabel
The Python tool pybabel has support for Godot and can be used to automatically create and update the POT file from your scene files and scripts.
After installing babel
and babel-godot
, for example using pip:
pip install babel babel-godot
Write a mapping file (for example babelrc
) which will indicate which files pybabel needs to process (note that we process GDScript as Python, which is generally sufficient):
You can then run pybabel like so:
pybabel extract -F babelrc -k text -k LineEdit/placeholder_text -k tr -o godot-l10n.pot .
Use the option to specify what needs to be extracted. In this case, arguments to will be translated, as well as properties named “text” (commonly used by Control nodes) and LineEdit’s “placeholder_text” property.
The msginit
command is used to turn a PO template into a messages file. For instance, to create a French localization file, use the following command while in the locale
directory:
Alternatively, you can do that graphically using Poedit, or by uploading the POT file to your web platform of choice.
Loading a messages file in 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
file in the file dialog. The locale will be inferred from the "Language: <code>\n"
property in the messages file.
Note
See Internationalizing games for more information on importing and testing translations in Godot.
Updating message files to follow the PO template
After updating the PO template, you will have to update message files so that they contain new strings, while removing strings that are no longer present in the PO template removed in the PO template. This can be done automatically using the msgmerge
tool:
# The order matters: specify the message file *then* the PO template!
If you want to keep a backup of the original message file (which would be saved as fr.po~
in this example), remove the argument.
If there are syntax errors or warnings, they will be displayed in the console. Otherwise, msgfmt
won’t output anything.