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, перегляньте Короткий Посібник з Gettext. Він написаний для проектів на С, але велика частина порад підійде і для Godot (за винятком xgettext).

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

Переваги

  • gettext — це стандартний формат, який можна редагувати за допомогою будь-якого текстового редактора або графічних редакторів, таких як Poedit. Це може бути важливим, оскільки надає багато інструментів для перекладачів, таких як позначка застарілих рядків, пошук рядків, які не були перекладені тощо.

  • gettext підтримується платформами перекладу, такими як Transifex та Weblate, що полегшує людям співпрацю по локалізації.

  • Порівняно з CSV, файли gettext краще працюють із системами контролю версій, такими як Git, оскільки кожна локалізація має свій власний файл повідомлень.

  • Багаторядкові рядки зручніше редагувати у файлах gettext PO порівняно з файлами CSV.

Недоліки

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

  • Люди, які підтримують файли локалізації, повинні будуть встановити в свою систему інструменти gettext. Однак, оскільки Godot підтримує використання текстових файлів повідомлень (.po), перекладачі можуть перевіряти свою роботу без необхідності встановлювати інструменти gettext.

  • Файли gettext PO зазвичай використовують англійську як базову мову. Перекладачі використовуватимуть цю базову мову для перекладу на інші мови. Ви все ще можете використовувати інші мови як базову, але це не поширене явище.

Встановлення інструментів gettext

Інструменти командного рядка gettext необхідні для виконання операцій технічного обслуговування, таких як оновлення файлів повідомлень. Тому настійно рекомендуємо їх встановити.

  • Windows: Завантажте інсталятор з цієї сторінки. Працює будь-яка архітектура і бінарний тип (спільний, чи статичний); якщо ви сумніваєтеся, виберіть 64-розрядний статичний інсталятор.

  • macOS: Встановіть gettext або за допомогою Homebrew за допомогою команди brew install gettext, або за допомогою MacPorts з командою sudo port install gettext.

  • Linux: У більшості дистрибутивів встановіть gettext пакет із диспетчера пакунків дистрибутива.

Для інструменту з графічним інтерфейсом ви можете завантажити Poedit з його офіційного вебсайту. Базова версія має відкритий код та доступна за ліцензією MIT.

Створення шаблону замовлення на замовлення

Автоматична генерація за допомогою редактора

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

Відкрийте Project > Project Settings > Localization > Template Generation, потім скористайтеся кнопкою Add…, щоб вказати шлях до сцен та скриптів вашого проєкту, що містять локалізовані рядки:

Створення шаблону замовлення на придбання на вкладці Локалізація > Генерація шаблонів у налаштуваннях проекту

Створення шаблону замовлення на придбання на вкладці Localization > Template Generation в Project Settings

Після додавання хоча б однієї сцени або скрипта натисніть Generate у верхньому правому куті, а потім вкажіть шлях до вихідного файлу з розширенням pot. Цей файл можна розмістити будь-де в каталозі проекту, але рекомендується зберігати його в підкаталозі, такому як locale, оскільки кожна локаль буде визначена в окремому файлі.

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

Потім ви можете перейти до створення файлу повідомлень із шаблону PO.

Примітка

Не забувайте повторно генерувати шаблон 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

Щоб зареєструвати файл messages як переклад у проєкті, відкрийте Project Settings, потім перейдіть до Localization > Translations, натисніть Add…, а потім виберіть файл .po або .mo у діалоговому вікні файлу. Локаль буде визначено з властивості "Мова: <код>\n" у файлі messages.

Примітка

Дивіться Інтернаціоналізація ігор, щоб дізнатися більше про імпорт і тестування перекладів у 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 коректним.

Якщо ви відкриєте за допомогою Poeditor, він відобразить відповідні попередження, якщо є якісь синтаксичні помилки. Ви також можете перевірити це, виконавши команду gettext нижче:

msgfmt fr.po --check

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

Використання бінарних файлів MO (корисно лише для великих проектів)

У великих проектах, де потрібно перекласти кілька тисяч рядків або більше, замість текстових PO-файлів варто використовувати бінарні (скомпільовані) файли MO-повідомлень. Бінарні 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 зображення".

Примітка

Аргумент або правий операнд має бути постійним рядком, інакше плагін не зможе обчислити вираз і проігнорує його.

Якщо плагін витягує непотрібні рядки, ви можете проігнорувати їх за допомогою коментаря 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")

У PO-файлі gettext рядок з контекстом можна визначити наступним чином:

# 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

Колись чи пізніше ви додасте новий контент до нашої гри, і з'являться нові рядки, які потрібно буде перекласти. Коли це станеться, вам потрібно буде оновити існуючі PO-файли, щоб включити нові рядки.

Спочатку згенеруйте новий 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

Якщо у вас є якийсь додатковий формат файлів, ви можете написати власний плагін для розбору та вилучення рядків з власного файлу. Цей власний плагін вилучить рядки та запише їх у POT-файл, коли ви натиснете Згенерувати POT. Щоб дізнатися більше про те, як створити плагін для розбору перекладів, див. EditorTranslationParserPlugin.