Lokalisierung mittels gettext

In addition to Übersetzungen importieren in CSV format, Godot also supports loading translation files written in the GNU gettext (.po) format.

Bemerkung

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

Vorteile

  • gettext ist ein Standardformat, dass mit jedem Text Editor oder GUI Editor wie Poedit editiert werden kann.
  • 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.
  • Mehrzeilige Zeichenfolgen lassen sich in gettext-Dateien bequemer bearbeiten als in CSV-Dateien.

Nachteile

  • 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 doesn't use compiled message object files (.mo), translators can test their work without having to install gettext tools.

Vorsichtsmaßnahmen

  • Da Godot hinter den Kulissen einen eigenen PO-Datei-Parser verwendet (der eingeschränkter ist als die Referenz-GNU-Gettext-Implementierung), werden einige Funktionen wie die Pluralisierung nicht unterstützt.

gettext Tools installieren

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: Verwenden Sie Homebrew <https://brew.sh/>`_, um gettext mit dem Befehl ``brew install gettext zu installieren.
  • Linux: Bei den meisten Distributionen installieren Sie das Paket gettext über den Paketmanager Ihrer Distribution.

Manuelles Erstellen der PO-Vorlage (POT)

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:

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

msgid "Hello world!"
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.

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

Erstellen der PO-Vorlage (POT) mit 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.

Nach der Installation von babel und `babel-godot, zum Beispiel mit 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):

[python: **.gd]
encoding = utf-8

[godot_scene: **.tscn]
encoding = utf-8

Sie können dann pybabel wie folgt ausführen:

pybabel extract -F babelrc -k text -k LineEdit/placeholder_text -k tr -o godot-l10n.pot .

Use the -k option to specify what needs to be extracted. In this case, arguments to tr() will be translated, as well as properties named "text" (commonly used by Control nodes) and LineEdit's "placeholder_text" property.

Erstellen einer Nachrichtendatei aus einer PO-Vorlage

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.

Laden einer Nachrichtendatei 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.

Bemerkung

Weitere Informationen zum Importieren und Testen von Übersetzungen in Godot finden Sie unter Übersetzung von Spielen.

Aktualisieren der Nachrichtendateien, um der PO-Vorlage zu folgen

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!
msgmerge --update --backup=none fr.po messages.pot

If you want to keep a backup of the original message file (which would be saved as fr.po~ in this example), remove the --backup=none argument.

Überprüfen der Gültigkeit einer PO-Datei oder -Vorlage

It is possible to check whether a gettext file's syntax is valid by running the command below:

msgfmt fr.po --check

If there are syntax errors or warnings, they will be displayed in the console. Otherwise, msgfmt won't output anything.