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

Localization using gettext (PO files)

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

Bemerkung

Eine Einführung in gettext finden Sie in A Quick Gettext Tutorial. Es wurde mit Blick auf C-Projekte geschrieben, aber viele der Ratschläge gelten auch für Godot (mit Ausnahme von xgettext).

For the complete documentation, see GNU Gettext.

Vorteile

• 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 wird von Übersetzungsplattformen wie Transifex und Weblate unterstützt, wodurch die Zusammenarbeit bei der Lokalisierung erleichtert wird.

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

Nachteile

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

• Wer Lokalisierungsdateien pflegt, muss gettext-Tools auf seinem System installieren. Da Godot jedoch die Verwendung textbasierter Nachrichtendateien (.po) unterstützt, können Übersetzer ihre Arbeit testen, ohne gettext-Tools installieren zu müssen.

• 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 der gettext-Tools

Die gettext-Tools für die Kommandozeile sind erforderlich, um Wartungsarbeiten wie die Aktualisierung von Übersetzungsdateien durchzuführen. Es wird daher dringend empfohlen, sie zu installieren.

• Windows: Laden Sie ein Installationsprogramm von dieser Seite herunter. Jede Architektur und jeder Binärtyp (dynamisch oder statisch) funktioniert; im Zweifelsfall wählen Sie das statische 64-Bit-Installationsprogramm.

• macOS: Installieren Sie gettext entweder über Homebrew mit dem Befehl brew install gettext, oder über MacPorts mit dem Befehl sudo port install gettext.

• Linux: Bei den meisten Distributionen installieren Sie das Paket gettext über den Paketmanager Ihrer 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.

Erstellen der PO-Vorlage

Automatische Generierung über den 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.

Sie können dann zu Erstellung einer Nachrichtendatei aus einer PO-Vorlage übergehen.

Bemerkung

Denken Sie daran, die PO-Vorlage neu zu generieren, nachdem Sie Änderungen an lokalisierbaren Strings vorgenommen oder neue Szenen oder Skripte hinzugefügt haben. Andernfalls werden neu hinzugefügte Strings nicht lokalisierbar sein und Übersetzer werden nicht in der Lage sein, Übersetzungen für veraltete Strings zu aktualisieren.

Manuelle Erstellung

Wenn die automatische Generierung für Ihre Bedürfnisse nicht geeignet ist, können Sie eine PO-Vorlage von Hand in einem Texteditor erstellen. Diese Datei kann an beliebiger Stelle im Projektverzeichnis abgelegt werden, aber es wird empfohlen, sie in einem Unterverzeichnis zu speichern, da jedes Gebietsschema in einer eigenen Datei definiert wird.

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

Nachrichten in gettext werden aus msgid und msgstr-Paaren gebildet. msgid ist der Quellstring (normalerweise in Englisch), msgstr ist der übersetzte String.

Warnung

Der Wert msgstr in PO-Vorlagendateien (.pot) sollte immer leer sein. Die Lokalisierung wird stattdessen in den erzeugten .po-Dateien durchgeführt.

Erstellen einer Übersetzungsdatei aus einer PO-Vorlage

Der Befehl msginit wird verwendet, um eine PO-Vorlage in eine Übersetzungsdatei zu verwandeln. Um zum Beispiel eine französische Lokalisierungsdatei zu erstellen, verwenden Sie den folgenden Befehl im Verzeichnis locale:

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

Der obige Befehl erzeugt eine Datei namens fr.po im selben Verzeichnis wie die PO-Vorlage.

Alternativ können Sie dies auch grafisch mit Poedit erledigen oder die POT-Datei auf die Webplattform Ihrer Wahl hochladen.

Laden einer Übersetzungsdatei in 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.

Bemerkung

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

Aktualisieren der Übersetzungsdateien, um der PO-Vorlage zu folgen

Nach der Aktualisierung der PO-Vorlage müssen Sie die Übersetzungsdateien so aktualisieren, dass sie neue Strings enthalten, und gleichzeitig Strings entfernen, die in der PO-Vorlage nicht mehr vorhanden sind. Dies kann automatisch mit dem Tool msgmerge geschehen:

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

Wenn Sie eine Sicherungskopie der ursprünglichen Übersetzungsdatei behalten wollen (die in diesem Beispiel als fr.po~ gespeichert würde), entfernen Sie das Argument --backup=none.

Bemerkung

Nach der Ausführung von msgmerge werden Strings, die in der Ausgangssprache geändert wurden, in der Datei .po mit einem "fuzzy"-Kommentar versehen. Dieser Kommentar zeigt an, dass die Übersetzung aktualisiert werden sollte, um mit dem neuen Quellstring übereinzustimmen, da die Übersetzung höchstwahrscheinlich ungenau sein wird, bis sie aktualisiert ist.

Strings mit ""fuzzy"-Kommentaren werden nicht von Godot gelesen, bis die Übersetzung aktualisiert und der "fuzzy"-Kommentar entfernt wurde.

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

It is possible to check whether a gettext file's syntax is valid.

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

Wenn es Syntaxfehler oder Warnungen gibt, werden sie in der Konsole angezeigt. Ansonsten wird msgfmt nichts ausgeben.

Verwendung von binären MO-Dateien (nur bei großen Projekten sinnvoll)

Bei großen Projekten mit mehreren Tausend oder mehr zu übersetzenden Strings kann es sich lohnen, binäre (kompilierte) MO-Übersetzungsdateien anstelle von textbasierten PO-Dateien zu verwenden. Binäre MO-Dateien sind kleiner und schneller zu lesen als die entsprechenden PO-Dateien.

Sie können eine MO-Datei mit dem folgenden Befehl erzeugen:

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.

Die ursprüngliche PO-Datei sollte in der Versionsverwaltung aufbewahrt werden, damit Sie Ihre Übersetzung in Zukunft aktualisieren können. Falls Sie die ursprüngliche PO-Datei verlieren und eine MO-Datei in eine textbasierte PO-Datei dekompilieren möchten, können Sie dies mit tun:

msgunfmt fr.mo > fr.po

Die dekompilierte Datei enthält keine Kommentare oder Fuzzy-Strings, da diese in der MO-Datei gar nicht erst kompiliert werden.

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

Bemerkung

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

Zum Beispiel:

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

Wenn Sie eine Sicherungskopie der ursprünglichen Übersetzungsdatei behalten wollen (die in diesem Beispiel als fr.po~ gespeichert würde), entfernen Sie das 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.