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

使用 gettext 进行本地化

In addition to 导入翻译 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).

备注

有关 gettext 的介绍，请查看 A Quick Gettext Tutorial。它是针对 C 项目编写的，但是很多建议也适用于 Godot（除了 xgettext）。

优势

  • gettext 是一种标准格式，可以使用任何文本编辑器或图形用户界面编辑器（如 Poedit）进行编辑。

  • Transifex 和 Weblate 等翻译平台也支持 gettext，让人们可以更方便地进行本地化协作。

  • 与 CSV 相比，gettext 更适合 Git 这样的版本控制系统，因为每个语言环境都有自己的消息文件。

  • 与 CSV 文件相比，在 gettext 文件中编辑多行字符串更方便。

缺点

  • gettext 是一种比 CSV 更复杂的格式，对于刚接触软件本地化的人来说可能更难理解。

  • 维护本地化文件的人员必须在其系统上安装 gettext 工具。但是，由于 Godot 支持使用基于文本的消息文件（.po），翻译人员无需安装 gettext 工具即可测试他们的工作。

安装 gettext 工具

需要命令行 gettext 工具来执行维护操作，如更新消息文件。因此，强烈建议您安装它们。

  • Windows：从该页面下载安装程序。任何体系结构和二进制类型（共享或静态）都可以；如果不确定，请选择 64 位静态安装程序。

  • macOS：使用 Homebrew 的 brew install gettext 命令来安装 gettext，或使用 MacPorts 的 sudo port install gettext 命令来安装。

  • Linux：在大多数发行版上，请使用发行版的包管理器安装 gettext 包。

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.

备注

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

gettext 中的消息由 msgid 和 msgstr 对组成。msgid 为源字符串（一般为英文），msgstr 为翻译后的字符串。

警告

PO 模板文件（.pot）中的 msgstr 值应始终为空。本地化会在生成的 .po 文件中进行。

从 PO 模板创建消息文件

msginit 命令用于将 PO 模板转换为消息文件。例如，要创建法语本地化文件，请在 locale 目录中使用以下命令：

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

上面的命令会在 PO 模板所在的目录下创建一个名为 fr.po 的文件。

或者，您可以使用 Poedit 以图形方式完成此操作，或者通过将 POT 文件上传到您选择的 Web 平台。

在 Godot 中加载消息文件

如果要将消息文件注册为项目的翻译，请打开项目设置，然后进入本地化选项卡。在翻译中单击添加...，然后在文件对话框中选择该 .po 或者 .mo 文件。区域设置将从消息文件的 "Language: <code>\n" 属性中推算出来。

备注

关于在 Godot 中导入和测试翻译的更多信息，请参阅 使游戏国际化。

按照 PO 模板更新消息文件

更新 PO 模板后，您必须更新消息文件以使其包含新字符串，同时删除已经在 PO 模板中不复存在的字符串。这可以使用 msgmerge 工具自动完成：

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

如果你想保留原始消息文件的备份，在本例中会保存为 fr.po~ ，请删除 --backup=none 参数。

备注

运行 msgmerge 后，如果源语言修改了某个字符串，那么在 .po 文件中就会在这个字符串之前加入“fuzzy”注释。这个注释表示的是翻译应当针对新字符串进行更新，因为现有翻译非常可能是不精确的。

Godot 不会读取带有“fuzzy”注释的字符串，需要更新翻译并移除“fuzzy”注释才行。

检查 PO 文件或模板的有效性

可以通过运行以下命令来检查 gettext 文件的语法是否有效：

msgfmt fr.po --check

如果有语法错误或警告，他们将显示在控制台。否则，msgfmt 不会输出任何东西。

使用二进制 MO 文件（仅适用于大型项目）

大型项目会有成千上万的字符串要翻译，相比于基于文本的 PO 文件，使用（编译为）二进制的 MO 消息文件可能更加划算。二进制 MO 文件比对应的 PO 文件更小、读起来更快。

你可以使用下面的命令生成 MO 文件：

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.

应该在版本控制中保留原始 PO 文件，这样以后就可以更新翻译。如果你丢失了原始的 PO 文件，希望将 MO 文件反编译为基于文本的 PO 文件，你可以这样做：

msgunfmt fr.mo > fr.po

反编译出的文件不包含注释和模糊字符串，因为它们一开始就没有编译进 MO 文件里。