Редактор і локалізація документації

Godot прагне зробити розробку ігор доступною для всіх, включно з людьми, які можуть не знати або не знати англійської мови. Тому ми робимо все можливе, щоб зробити найважливіші ресурси доступними багатьма мовами завдяки перекладацьким зусиллям спільноти.

Ці ресурси включають:

1. Інтерфейс редактора Godot.

2. Посилання на клас, доступне як онлайн, так і в редакторі.

3. Онлайн-документація (посібник редактора та навчальні посібники).

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

На цій сторінці наведено огляд загального робочого процесу перекладу на Weblate, а також деякі інструкції щодо окремих ресурсів, наприклад. як обробляти деякі ключові слова або локалізацію зображень.

Порада

Переклад усього офіційного вмісту Godot — це величезна робота, тому ми радимо розставляти пріоритети за ресурсами, як вони перераховані вище: спочатку інтерфейс редактора, потім посилання на клас, а потім онлайн-документація.

Використання Weblate для перекладу

Хоча наші переклади зрештою зберігаються в репозиторіях Git механізму Godot і його документації, усі оновлення перекладу обробляються через Weblate, тому прямі запити на отримання до репозиторіїв Git не приймаються. Переклади синхронізуються вручну між Weblate і репозиторіями Godot супроводжувачами.

Тому вам слід «зареєструватися на Weblate <https://hosted.weblate.org/accounts/register/>`__, щоб зробити свій внесок у переклади Godot.

Увійшовши в обліковий запис, перейдіть до ресурсу Godot, до якого ви хочете зробити свій внесок (на цій сторінці ми будемо використовувати переклад редактора як наприклад), щоб знайти список усіх мов:

Дивись також

Не соромтеся ознайомитися з документацією Weblate щодо робочого процесу перекладу <https://docs.weblate.org/en/latest/user/translating.html>`__, щоб дізнатися більше.

Додавання нової мови

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

Якщо вашої мови немає в списку, перейдіть униз списку мов і натисніть кнопку «Почати новий переклад», а потім виберіть мову, якою ви хочете перекласти:

Важливо

Якщо вашою мовою розмовляють у кількох країнах із обмеженими регіональними варіаціями, подумайте про те, щоб додати нею загальний варіант (наприклад, fr для французької мови) замість регіонального варіанту (наприклад, fr_FR для французької (Франція), fr_CA для французької (Канада) або fr_DZ для французької (Алжир)).

У Godot є величезна кількість контенту для перекладу, тому копіювання роботи для регіональних варіантів слід виконувати, лише якщо мовні варіації достатньо значні. Крім того, якщо переклад виконується за допомогою для регіонального варіанту, він буде автоматично доступний лише для користувачів, які перебувають у цьому регіоні (або для користувачів, у яких мова системи налаштована для цього регіону).

Якщо регіональні відмінності є достатньо значними, щоб вимагати окремих перекладів, радимо спершу зосередитися на завершенні загального варіанту, якщо це можливо, а потім дублювати повністю завершений переклад для регіональних варіантів і внести відповідні зміни. Зазвичай це хороша стратегія, наприклад, для Іспанська (спочатку попрацюйте над es, потім дублюйте його на es_AR, es_ES, es_MX тощо, якщо необхідно) або португальська (pt_BR проти pt_PT).

Інтерфейс перекладу

Після вибору мови ви побачите огляд статусу перекладу, включаючи кількість рядків, які залишилося перекласти або переглянути. Кожен елемент можна клацнути та використати для перегляду відповідного списку. Ви також можете натиснути кнопку «Перекласти», щоб розпочати перегляд списку рядків, які потребують дії.

Вибравши список і натиснувши «Перекласти», ви побачите головний інтерфейс перекладу, де відбувається вся робота:

На цій сторінці ви маєте:

• Панель інструментів, яка дає змогу циклічно переходити між рядками поточного списку, переходити до іншого попередньо визначеного списку або здійснювати спеціальний пошук тощо. Існує також режим редагування «Дзен» із спрощеним інтерфейсом.

• Фактичний рядок, над яким ви працюєте на панелі «Переклад». За замовчуванням має бути вихідний рядок англійською мовою та поле редагування для вашої мови. Якщо ви знайомі з іншими мовами, ви можете додати їх у налаштуваннях користувача, щоб отримати більше контексту для перекладу. Після завершення редагування поточного рядка натисніть «Зберегти», щоб підтвердити зміни та перейти до наступного запису. Або скористайтеся кнопкою «Пропустити», щоб пропустити його. Прапорець «Потребує редагування» означає, що оригінальний рядок було оновлено, тому переклад потребує перегляду, щоб врахувати ці зміни (на жаргоні PO це так звані «нечіткі» рядки). Такі рядки не використовуватимуться в перекладі, доки не буде виправлено.

• На нижній панелі є різні інструменти, які можуть допомогти з перекладом, як-от контекст із сусідніх рядків (зазвичай із того самого інструменту редактора чи сторінки документації, тому вони можуть використовувати схожі терміни), коментарі інших перекладачів, машинні переклади та список усіх інших існуючих перекладів для цього рядка.

• Угорі праворуч глосарій показує терміни, для яких раніше було додано запис і які включено в поточний рядок. Наприклад, якщо ви разом із колегами-перекладачами вирішили використати певний переклад для терміна «вузол» у Godot, ви можете додати його до глосарію, щоб переконатися, що інші перекладачі використовують ту саму конвенцію.

• Нижня права панель містить інформацію про вихідний рядок. Найрелевантнішим елементом є «розташування вихідного рядка», яке зв’язує вас із вихідним рядком на GitHub. Можливо, вам знадобиться пошукати рядок на сторінці, щоб знайти його та навколишній контекст.

Пошук оригінального вмісту

Файли PO — це впорядкований список вихідних рядків (msgid) і їх переклад (msgstr), і за замовчуванням Weblate представлятиме рядки в такому порядку. Тому може бути корисним зрозуміти, як організовано вміст у файлах PO, щоб допомогти вам знайти оригінальний вміст і використовувати його як посилання під час перекладу.

Важливо

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

• Шаблон перекладу інтерфейсу редактора створюється шляхом аналізу всього вихідного коду C++ в алфавітному порядку, тому всі рядки, визначені в даному файлі, будуть згруповані разом. Наприклад, якщо «розташування вихідного рядка» вказує editor/code_editor.cpp, поточний рядок (і сусідні) визначено у файлі коду editor/code_editor.cpp і, таким чином, пов’язаний до редакторів коду в Godot (GDScript, шейдери).

• Шаблон перекладу онлайн-документації генерується з вихідних файлів RST у тому самому порядку, що й у змісті, отже, наприклад, перші рядки взято з першої сторінки документації. Тому рекомендований робочий процес полягає в тому, щоб знайти унікальний рядок, що відповідає сторінці, яку потрібно перекласти, а потім перекласти всі рядки з однаковим розташуванням вихідного рядка, порівнюючи з онлайн-версією цієї сторінки англійською мовою. Прикладом розташування вихідного рядка може бути getting_started/step_by_step/nodes_and_scenes.rst для сторінки Вузли та Сцени.

• Шаблон перекладу посилання на клас генерується з вихідних XML-файлів у алфавітному порядку, який також збігається з порядком змісту для онлайн-версії. Тому ви можете знайти вихідний рядок, який відповідає короткому опису даного класу, щоб знайти перший рядок для перекладу, а всі інші описи з цього класу мають бути в наступних рядках на Weblate. Наприклад, описи для класу Node2D матимуть розташування вихідного рядка doc/classes/Node2D.xml.

Зручним інструментом для пошуку певних сторінок/класів є використання функції розширеного пошуку Weblate, а особливо запиту «Рядки розташування» (який також можна використовувати з маркером location:, наприклад location:nodes_and_scenes.rst):

Примітка

Якщо даний вихідний рядок використовується в кількох джерелах, усі вони будуть об’єднані в одне. Наприклад, наведений вище запит location:nodes_and_scenes.rst спочатку приземлиться на вихідний рядок «Introduction», який використовується в десятках сторінок, включно з тими, що передують nodes_and_scenes.rst у шаблоні. Натискання кнопки «Далі» переносить нас до рядка заголовка «Сцена та вузли», який відображається вище. Тож може статися так, що заголовок певного абзацу чи розділу знаходиться не там, де ви очікували б під час читання онлайн-версії сторінки.

Дотримання синтаксису розмітки

Кожен ресурс перекладу походить з іншого формату вихідного коду, і мати певні уявлення про мову розмітки, яка використовується для кожного ресурсу, важливо, щоб уникнути створення синтаксичних помилок у ваших перекладах.

Інтерфейс редактора (C++)

Переклади редактора походять із рядків C++ і можуть використовувати:

• Специфікатори формату C, такі як %s (рядок) або %d (число). Ці специфікатори замінюються вмістом під час виконання, і їх слід зберегти та розмістити у вашому перекладі, де це необхідно, щоб він був значущим після заміни. Можливо, вам знадобиться звернутися до розташування вихідного рядка, щоб зрозуміти, який тип вмісту буде замінено, якщо це не зрозуміло з речення. Приклад (%s буде замінено назвою файлу або шляхом):

  # PO file:
  "There is no '%s' file."
  
  # Weblate:
  There is no '%s' file.
  

• Escape-символи C, наприклад \n (розрив рядка) або \t (табуляція). У редакторі Weblate символи \n замінюються на ↵ (повернення), а \t на ↹. Табуляції використовуються нечасто, але вам слід переконатися, що розриви рядків використовуються так само, як і оригінальний англійський рядок (Weblate видасть попередження, якщо ви цього не зробите). Розриви рядків іноді можуть використовуватися для вертикального інтервалу або ручного обтікання довгих рядків, які інакше були б надто довгими, особливо в перекладі редактора). Приклад:

  # PO file:
  "Scene '%s' is currently being edited.\n"
  "Changes will only take effect when reloaded."
  
  # Weblate:
  Scene '%s' is currently being edited.↵
  Changes will only take effect when reloaded.
  

Примітка

Має значення лише логічний порядок символів, у тексті справа наліво специфікатори формату можуть відображатися як s%.

Онлайн-документація (RST)

Переклади документації походять із файлів reStructuredText (RST), які також використовують власний синтаксис розмітки для стилізації тексту, створення внутрішніх і зовнішніх посилань тощо. Ось кілька прикладів:

# "development" is styled bold.
# "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest.
# You should translate "Have a look here", but not the URL, unless there is
# a matching URL for the same content in your language.
# Note: The `, <, >, and _ characters all have a meaning in the hyperlink
# syntax and should be preserved.

Looking for the documentation of the current **development** branch?
`Have a look here <https://docs.godotengine.org/en/latest>`_.

# "|supported|" is an inline reference to an image and should stay unchanged.
# "master" uses the markup for inline code, and will be styled as such.
# Note: Inline code in RST uses 2 backticks on each side, unlike Markdown.
# Single backticks are used for hyperlinks.

|supported| Backwards-compatible new features (backported from the ``master``
branch) as well as bug, security, and platform support fixes.

# The :ref: Sphinx "role" is used for internal references to other pages of
# the documentation.
# It can be used with only the reference name of a page (which should not be
# changed), in which case the title of that page will be displayed:

See :ref:`doc_ways_to_contribute`.

# Or it can be used with an optional custom title, which should thus be translated:

See :ref:`how to contribute <doc_ways_to_contribute>`.

# You may encounter other Sphinx roles, such as :kbd: used for shortcut keys.
# You can translate the content between backticks to match the usual key names,
# if it's different from the English one.

Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux
or :kbd:`Cmd + S` on macOS.

Дивись також

Перегляньте reStructured Text primer від Sphinx, щоб отримати короткий огляд мови розмітки, яку ви можете знайти у вихідних рядках. Ви можете зустріти, зокрема, вбудовану розмітку (жирний шрифт, курсив, вбудований код), а також внутрішню та зовнішню розмітку гіперпосилань.

Посилання на клас (BBCode)

Посилання на клас задокументовано в основному репозиторії Godot за допомогою XML-файлів і з BBCode-подібною розміткою для стилів і внутрішніх посилань.

Деякі використовувані теги взяті з оригінального BBCode (наприклад, [b]Жирний[/b] і [i]Курсив[/i]), тоді як інші є специфічними для Godot і використовуються для розширених функцій як-от вбудований код (наприклад, [code]true[/code]), зв’язування з іншим класом (наприклад [Node2D]) або з властивістю в даному класі (наприклад [member Node2D. position]), або для блоків багаторядкового коду. Приклад:

Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
[codeblock]
red = ColorN("red", 1)
[/codeblock]
Supported color names are the same as the constants defined in [Color].

У наведеному вище прикладі [code]name[/code], [code]alpha[/code] і [Color] не слід перекладати, оскільки вони посилаються відповідно до імен аргументів і класу Godot API. Так само не слід перекладати вміст [codeblock], оскільки ColorN є функцією Godot API, а "red" є одним із іменованих кольорів, які він підтримує. Щонайбільше, ви можете перекласти назву змінної, яка містить результат (red = ...).

Зауважте також, що в XML кожен рядок є абзацом, тому вам не слід додавати розриви рядків, якщо вони не є частиною оригінального перекладу.

Дивись також

Дивіться нашу документацію для авторів довідників класу для list of BBCode-like tags, які використовуються в довідці до класу.

Офлайн переклад і тестування

Хоча ми радимо використовувати інтерфейс Weblate для написання перекладів, ви також маєте можливість завантажити файл PO локально, щоб перекласти його за допомогою програми для редагування PO, як-от Poedit або ` Локалізувати <https://userbase.kde.org/Lokalize>`__.

Щоб завантажити файл PO локально, перейдіть до огляду перекладу для вашої мови та виберіть перший пункт у меню «Файли»:

Завершивши серію редагувань, скористайтеся пунктом «Завантажити переклад» у тому самому меню та виберіть свій файл. Для режиму завантаження файлу виберіть «Додати як переклад».

Примітка

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

Якщо ви хочете перевірити зміни локально (особливо для перекладу редактора), ви можете використати завантажений файл PO та compile Godot from source.

Перейменуйте PO-файл перекладу редактора на <lang>.po (наприклад, eo.po для есперанто) і помістіть його в папку editor/translations/ (GitHub).

Ви також можете перевірити зміни посилання на клас таким же чином, перейменувавши файл PO подібним чином і помістивши його в папку doc/translations/ (GitHub).

Локалізація зображень документації

Онлайн-документація містить багато зображень, які можуть бути знімками екрана редактора Godot, спеціально створеними графіками або будь-яким іншим видом візуального вмісту. Деякі з них містять текст і тому можуть бути доречними для локалізації вашою мовою.

Ця частина обробляється не через Weblate, а безпосередньо в репозиторії godot-docs-l10n Git, де переклади документації синхронізуються з Weblate.

Примітка

Робочий процес не найпростіший і вимагає певних знань Git. Ми плануємо працювати над спрощеним веб-інструментом, який можна було б використовувати для зручного керування локалізацією зображень, абстрагуючись від цих кроків.

Щоб перекласти зображення, спочатку знайдіть його в оригінальній англійській документації. Для цього перегляньте відповідну сторінку в документах, напр. Спочатку подивіться на інтерфейс Godot. Натисніть посилання «Редагувати на GitHub» у верхньому правому куті:

На GitHub клацніть зображення, яке потрібно перекласти. Якщо потрібно, натисніть «Завантажити», щоб завантажити його локально та відредагувати за допомогою інструмента редагування зображень. Зверніть увагу на повний шлях до зображення, оскільки він знадобиться далі (тут getting_started/step_by_step/img/project_manager_first_open.png).

Створіть свою локалізовану версію зображення, або відредагувавши англійську, або зробивши знімок екрана редактора вашою мовою, якщо це знімок екрана редактора. Деякі зображення також можуть мати вихідні файли, доступні у форматі SVG, тому ви можете переглянути папку img/, яка містить їх, щоб перевірити це.

Назвіть своє локалізоване зображення, як оригінальне, але з кодом мови, доданим перед розширенням, наприклад. project_manager_first_open.png стане project_manager_first_open.fr.png для французької локалізації.

Нарешті, на godot-docs-l10n відтворіть ту саму структуру папок, що й для вихідного зображення, у підтеці images (GitHub), і розмістіть там своє перекладене зображення. У нашому прикладі має бути кінцевий результат images/getting_started/step_by_step/img/project_manager_first_open.fr.png.

Повторіть це для інших зображень і make a Pull Request.