Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Локалізація за допомогою 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, перегляньте Короткий Посібник з Gettext. Він написаний для проектів на С, але велика частина порад підійде і для 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<https://brew.sh/>`_ за допомогою команди brew install gettext, або за допомогою `MacPorts<https://www.macports.org/>`_ з командою 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 буде перекладеним рядком.

Попередження

Значення 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. Цей коментар означає, що переклад повинен бути оновлений відповідно до нового вихідного рядка, оскільки переклад, швидше за все, буде неточним, поки він не буде оновлений.

Рядки з "нечіткими" коментарями ("fuzzy") не будуть прочитані Godot, поки переклад не буде оновлений і "нечіткий" коментар не буде видалений.

Перевірка дійсності файлу 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.