Локализация с помощью gettext

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

Примечание

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

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

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

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

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

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

Недостатки

  • gettext - это более сложный формат, чем CSV, и его может быть труднее понять тем, кто только начинает заниматься локализацией программного обеспечения.

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

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

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

  • Windows: Загрузите программу установки с этой страницы <https://mlocati.github.io/articles/gettext-iconv-windows.html>`_. Работает любая архитектура и бинарный тип (разделяемый или статический); если есть сомнения, выбирайте 64-битный статический инсталлятор.

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

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

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

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

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

Откройте вкладку Localization > POT Generation в настройках проекта, затем используйте кнопку Add…, чтобы указать путь к сценам и скриптам вашего проекта, содержащим локализуемые строки:

Создание шаблона PO на вкладке "Localization > POT Generation" в Project Settings

Создание шаблона PO на вкладке Localization > POT Generation в Project Settings

После добавления хотя бы одной сцены или скрипта нажмите кнопку 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

Чтобы зарегистрировать файл сообщений в качестве перевода в проекте, откройте Project Settings и перейдите на вкладку Localization. В разделе Translations нажмите Add… и выберите файл .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 можно, выполнив приведенную ниже команду:

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