Up to date

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

Localization using gettext

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

Note

For an introduction to gettext, check out A Quick Gettext Tutorial. It's written with C projects in mind, but much of the advice also applies to Godot (with the exception of xgettext).

Advantages

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

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

Installing gettext tools

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 this page. Any architecture and binary type (shared or static) works; if in doubt, choose the 64-bit static installer.

  • macOS: Install gettext either using Homebrew with the brew install gettext command, or using MacPorts with the sudo port install gettext command.

  • Linux: On most distributions, install the gettext package from your distribution's package manager.

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

Messages in gettext are made of msgid and msgstr pairs. msgid is the source string (usually in English), msgstr will be the translated string.

Warning

The msgstr value in PO template files (.pot) should always be empty. Localization will be done in the generated .po files instead.

Creating a messages file from a PO template

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:

msginit --no-translator --input=messages.pot --locale=fr

The command above will create a file named fr.po in the same directory as the PO template.

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 <