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 (PO-файлы)

Помимо импорта переводов в формате CSV, Godot также поддерживает загрузку файлов переводов в формате GNU gettext (текстовые .po и скомпилированные .mo).

Примечание

Для ознакомления с gettext посмотрите A Quick Gettext Tutorial. Он написан для проектов на C, но большая часть советов применима и к Godot (за исключением xgettext).

Полную документацию см. в GNU Gettext.

Преимущества

  • gettext — это стандартный формат, который можно редактировать в любом текстовом редакторе или графических редакторах, таких как Poedit. Это может быть важно, поскольку он предоставляет множество инструментов для переводчиков, таких как отметка устаревших строк, поиск непереведённых строк и т. д.

  • gettext поддерживается такими платформами перевода, как Transifex и Weblate, что облегчает совместную работу людей над локализацией.

  • По сравнению с CSV, файлы gettext лучше работают с системами контроля версий, такими как Git, поскольку каждая локаль имеет свой собственный файл сообщений.

  • Многострочные строки удобнее редактировать в PO-файлах gettext, чем в CSV-файлах.

Недостатки

  • Файлы PO gettext имеют более сложный формат, чем CSV, и их может быть сложнее понять новичкам в локализации программного обеспечения.

  • Тем, кто поддерживает файлы локализации, потребуется установить инструменты GetText в своей системе. Однако, поскольку Godot поддерживает использование текстовых файлов сообщений (.po), переводчики могут тестировать свою работу без установки инструментов GetText.

  • gettext PO files usually use English as the base language. Translators will use this base language to translate to other languages. You could still use other languages as the base language, but this is not common.

Установка инструментов gettext

Инструменты командной строки gettext необходимы для выполнения операций обслуживания, таких как обновление файлов сообщений. Поэтому настоятельно рекомендуется их установить.

  • Windows: Загрузите программу установки с этой страницы. Работает любая архитектура и бинарный тип (разделяемый или статический); если есть сомнения, выбирайте 64-битный статический инсталлятор.

  • macOS: Установите gettext либо с помощью Homebrew с командой brew install gettext, либо с помощью MacPorts <https://www.macports.org/>`_ с командой ``sudo port install gettext.

  • Linux: В большинстве дистрибутивов установите пакет gettext из менеджера пакетов вашего дистрибутива.

Для графического интерфейса (GUI) Poedit можно загрузить с Официального сайта. Базовая версия имеет открытый исходный код и доступна по лицензии MIT.

Создание шаблона PO

Автоматическая генерация с помощью редактора

Редактор может автоматически генерировать PO-шаблон из указанных файлов сцен и GDScript. Эта генерация POT также поддерживает контексты перевода и множественное число, если используется в скрипте, с помощью необязательного второго аргумента tr() и метода tr_n().

Откройте Проект > Настройки проекта > Локализация > Генерация шаблонов, затем используйте кнопку Добавить…, чтобы указать путь к сценам и скриптам вашего проекта, содержащим локализуемые строки:

Создание PO-шаблона на вкладке Localization > Template Generation в настройках проекта

Создание PO-шаблона на вкладке Localization > Template Generation в Настройках проекта

После добавления хотя бы одной сцены или скрипта нажмите Generate в правом верхнем углу, затем укажите путь к выходному файлу с расширением pot. Этот файл можно разместить в любом месте каталога проекта, но рекомендуется хранить его в подкаталоге, например locale, так как каждая локаль будет определена в своём файле.

См. below информацию о том, как добавлять комментарии для переводчиков или исключать некоторые строки из добавления в шаблон PO для файлов GDScript.

Затем вы можете перейти к creating a messages file from a PO template.

Примечание

Не забудьте перегенерировать шаблон PO после внесения любых изменений в локализуемые строки или добавления новых сцен или сценариев. В противном случае вновь добавленные строки не будут локализованы, и переводчики не смогут обновить переводы устаревших строк.

Manual creation

Если автоматическая генерация вам не подходит, вы можете создать шаблон PO вручную в текстовом редакторе. Этот файл можно разместить в любом месте каталога проекта, но рекомендуется хранить его в подкаталоге, так как каждая локаль будет определена в отдельном файле.

Создайте каталог locale в каталоге проекта. В этом каталоге сохраните файл messages.pot со следующим содержимым:

# 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 - это переведенная строка.

Предупреждение

Значение msgstr в файлах шаблонов PO (.pot) должно всегда быть пустым. Локализация будет выполнена в сгенерированных файлах .po вместо этого.

Создание файла сообщений из шаблона PO

Команда msginit используется для превращения шаблона PO в файл сообщений. Например, чтобы создать файл французской локализации, используйте следующую команду, находясь в каталоге locale:

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

Приведенная выше команда создаст файл с именем fr.po в том же каталоге, что и шаблон PO.

Кроме того, это можно сделать графически с помощью Poedit или загрузив файл POT на выбранную вами веб-платформу.

Загрузка файла сообщений в 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 "нечёткий" комментарий. Этот комментарий означает, что перевод следует обновить в соответствии с новой исходной строкой, поскольку до обновления перевод, скорее всего, будет неточным.

Строки с "нечеткими" комментариями не будут прочитаны Godot, пока перевод не будет обновлен и "нечеткий" комментарий не будет удален.

Проверка достоверности файла или шаблона PO

Можно проверить правильность синтаксиса файла gettext.

Если открыть файл в Poeditor, он выведет соответствующие предупреждения, если есть синтаксические ошибки. Вы также можете проверить это, выполнив команду gettext ниже:

msgfmt fr.po --check

Если есть синтаксические ошибки или предупреждения, они будут выведены в консоль. В противном случае msgfmt ничего не выведет.

Использование двоичных MO-файлов (полезно только для больших проектов)

Для крупных проектов, требующих перевода нескольких тысяч строк и более, может быть целесообразно использовать двоичные (скомпилированные) файлы сообщений MO вместо текстовых PO-файлов. Двоичные MO-файлы меньше по размеру и читаются быстрее, чем аналогичные PO-файлы.

Вы можете создать MO-файл с помощью следующей команды:

msgfmt fr.po --no-hash -o fr.mo

Если PO-файл корректен, эта команда создаст файл fr.mo помимо PO-файла. Этот MO-файл затем можно загрузить в Godot, как описано выше.

Исходный PO-файл следует хранить в системе контроля версий, чтобы иметь возможность обновить перевод в будущем. Если вы потеряете исходный PO-файл и захотите декомпилировать MO-файл в текстовый PO-файл, это можно сделать следующим образом:

msgunfmt fr.mo > fr.po

Декомпилированный файл не будет содержать комментариев или нечетких строк, поскольку они изначально не компилируются в файле MO.

Извлечение локализуемых строк из файлов GDScript

Встроенный плагин редактора распознает различные шаблоны в исходном коде для извлечения локализуемых строк из файлов GDScript, включая, помимо прочего, следующие:

  • tr(), tr_n(), atr(), и atr_n() звонки;

  • назначение свойств text, placeholder_text, и tooltip_text;

  • add_tab(), add_item(), set_tab_title(), и другие звонки;

  • FileDialog фильтры типа "*.png ; PNG Images".

Примечание

Аргумент или правый операнд должен быть константной строкой, в противном случае плагин не сможет оценить выражение и проигнорирует его.

Если плагин извлекает ненужные строки, вы можете игнорировать их с помощью комментария NO_TRANSLATE. Вы также можете предоставить дополнительную информацию для переводчиков с помощью комментария TRANSLATORS:. Эти комментарии должны располагаться либо на той же строке, что и распознанный шаблон, либо перед ним.

$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?"))

Использование контекста

Параметр context можно использовать для различения ситуации, в которой используется перевод, или для различения полисемичных слов (слов с несколькими значениями).

Например:

tr("Start", "Main Menu")
tr("End", "Main Menu")
tr("Shop", "Main Menu")
tr("Shop", "In Game")

В файле gettext PO строка с контекстом может быть определена следующим образом:

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

Обновление файлов PO

Some time or later, you'll add new content to your 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.

Сначала создайте новый POT-файл, содержащий все существующие строки и вновь добавленные строки. После этого объедините существующие PO-файлы с новым POT-файлом. Это можно сделать двумя способами:

  • Используйте редактор GetText, в нем должна быть возможность обновления файла PO из файла POT.

  • Используйте инструмент gettext msgmerge:

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

Если вы хотите сохранить резервную копию исходного файла сообщения (который в данном примере будет сохранен как fr.po~), удалите аргумент --backup=none.

Пользовательский плагин для генерации POT

If you have any extra file format to deal with, you could write a custom plugin to parse 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.