Перевод редактора и документации

Godot старается сделать разработку игр доступной для каждого, включая людей, кто может не знать или чувствовать себя некомфортно при работе с английским языком. Поэтому мы делаем всё возможное, чтобы самые важные ресурсы были доступны на разных языках. Это достигается благодаря усилиям переводчиков сообщества.

Эти ресурсы включают в себя:

  1. Интерфейс редактора Godot (примерно 15,000 слов).
  2. Онлайн документация (руководство редактора и учебные ресурсы, приблизительно 300,000 слов).
  3. Справка классов, доступна как онлайн, так и непосредственно в редакторе (приблизительно 200,000 слов).

Для управления переводами мы используем "GNU gettext" формат файла (PO файлы), и свободный ресурс Weblate веб-ориентированная платформа локализации, которая позволяет без труда объединить усилия большого количества участников для завершения перевода различных компонентов и помогает отслеживать их актуальность. Выше приведены ссылки для перехода к каждому из ресурсов на Weblate.

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

Совет

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

Использование Weblate для переводов

Пока наши переводы находятся в репозиториях Git движка Godot и его документации, все обновления переводов обрабатываются через Weblate - запросы на прямое помещение данных в репозитории Git не будут приниматься. Переводы между Weblate и репозиториями Godot синхронизируются вручную сопровождающими (maintainers).

Таким образом, вам следует зарегистрироваться на Weblate, чтобы иметь возможность внести свой вклад в переводы Godot.

После входа в систему перейдите к ресурсу Godot, в который вы хотите внести свой вклад (на этой странице мы будем использовать перевод редактора в качестве примера), чтобы найти список всех языков:

../../_images/l10n_01_language_list.png

См.также

Не стесняйтесь обращаться к собственной документации Weblate по `рабочему процессу перевода<https://docs.weblate.org/en/latest/user/translating.html>`__ для получения дополнительных сведений.

Добавление нового языка

Если ваш язык уже существует в списке, щёлкните по нему, чтобы получить доступ к обзору, и пропустите оставшуюся часть этого раздела.

Если вашего языка нет в списке, прокрутите список языков до конца, нажмите кнопку "Начать новый перевод" и выберите язык, на который вы хотите перевести:

../../_images/l10n_02_new_translation.png

Важно

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

Godot имеет огромное количество контента для перевода, поэтому дублировать работу для региональных вариантов следует только в том случае, если языковые вариации достаточно значительны. Кроме того, если перевод выполняется для регионального варианта, он будет автоматически доступен только для пользователей, находящихся в этом регионе (или для тех у которых язык системы настроен на этот регион).

Когда региональные различия достаточно значительны, чтобы гарантировать отдельные переводы, мы советуем сосредоточиться на завершении общего варианта, если это возможно, затем продублировать полностью завершенный перевод для региональных вариантов и внести соответствующие изменения. Обычно это хорошая стратегия для таких языков как например, испанский (сначала проработайте es, затем дублируйте его на es_AR, es_ES, es_MX и т.д., если это необходимо) или португальский (pt_BR и pt_PT).

Интерфейс перевода

После выбора языка вы увидите строку "статус перевода", отображающую количество строк оставшихся для перевода или проверки. Каждый элемент можно использовать для просмотра соответствующего списка (просто щёлкните на него). Вы также можете нажать кнопку "Перевести", чтобы начать работу со списком строк, требующих вмешательства.

../../_images/l10n_03_translation_overview.png

После выбора списка нажатием кнопки "Перевести", вы увидете основной интерфейс перевода, в котором происходит вся работа:

../../_images/l10n_04_translation_interface.png

На этой странице у вас есть:

  • Панель инструментов, которая позволяет вам циклически перемещаться по строкам текущего списка, переходить к другому предопределенному списку или выполнять пользовательский поиск и т.д. Существует также режим редактирования "Дзен" с упрощённым интерфейсом.
  • Основное поле для работы находится в блоке "Перевод". По умолчанию там должна быть исходная строка на английском языке и поле для редактирования строки на вашем языке. Если вам знакомы другие языки, вы можете добавить их в свои пользовательские настройки, чтобы получить больше контекста для перевода. Как только вы закончите редактирование текущей строки, нажмите "Сохранить", чтобы подтвердить изменения и перейти к следующей записи, так же вы можете использовать кнопку "Пропустить", чтобы пропустить её. Флажок "На правку" означает, что исходная строка была обновлена и перевод нуждается в проверке перед добавлением. (на жаргоне PO это так называемые "нечеткие" строки). Такие строки не будут использоваться в переводе, пока не будут исправлены.
  • На нижней панели есть различные инструменты, которые могут помочь с переводом, такие как контекст из соседних строк (обычно из того же инструмента редактора или страницы документации, поэтому они могут использовать похожие термины), комментарии других переводчиков, машинные переводы и список всех других существующих переводов для этой строки.
  • В верхнем правом углу находится глоссарий, в нём показаны термины, для которых ранее была добавлена запись и которые включены в текущую строку. Например, если вы вместе с другими переводчиками решили использовать определенный перевод для термина "узел" в Godot, вы можете добавить его в глоссарий, чтобы другие переводчики использовали то же соглашение.
  • Правая нижняя панель содержит в себе информацию об исходной строке. Самый часто ипользуемый элемент этой панели - "Расположение исходной строки", позволяет вам быстро найти исходную строку в репозитории GitHub. Вам может пригодиться возможность найти строку в окружающем её контектсе.

Поиск исходного контента

PO файлы представляют из себя упорядоченные списки исходных строк (msgid) и их переводов (msgstr), и по умолчанию Weblate будет выводить строки именно в таком порядке. Понимание того как организован контент в PO файлах может помочь вам определить положение исходного контента, чтобы затем использовать его в качестве шаблона для перевода.

Важно

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

  • Шаблон перевода интерфейса редактора генерируется парсингом всего C++ source-кода в алфавитном порядке, поэтому все строки определённые в конкретном файле будут сгруппированы вместе. Например, если "Расположение исходной строки" указывает на editor/code_editor.cpp, значит текущая строка (и все ближайшие) тоже определяются в editor/code_editor.cpp файле и это, в том числе, применимо ко встроенным редакторам кода в Godot (редакторам GDScript, и шейдеров).
  • Шаблон перевода онлайн-документации генерируется исходными файлами RST в порядке следования в оглавлении (первыми следуют строки первой страницы документации). Поэтому рекоммендуемая последовательность работы выглядит так: сначала вы берёте исходную строку, которой можно однозначно определить страницу которую вы хотите перевести (кусок адреса из адресной строки между названием ветки документации, например /stable, до точки с расширением текущей веб-страницы, например .html), затем последовательно переводите все строки находящиеся на этой странице, параллельно сравнивая их с онлайн версией этой страницы на английском. Например, для страницы doc_scenes_and_nodes`такой строкой является ``getting_started/step_by_step/scenes_and_nodes.rst`.
  • Шаблон перевода справки классов создаётся на основе XML файлов в алфавитном порядке, который также соответствует порядку следования пунктов в оглавлении онлайн версии справки. Вы можете определить расположение исходной строки соответствующее краткому описанию данного класса чтобы найти первую строку для перевода, оставшая часть описания класса будет представлена последующими строками на Weblate. Например, описание для класса class_Node2D`имеет расположение исходной строки ``doc/classes/Node2D.xml`.

Полезным инструментом для поиска специфичных страниц/классов будет являться использование продвинутых функций поиска в Weblate, в особенности запрос "Строки по расположению" (для его выполнения можно воспользоваться инструкцией location:, полный пример использования выглядит так: location:scenes_and_nodes.rst):

../../_images/l10n_05_search_location.png ../../_images/l10n_06_browse_by_location.png

Примечание

Если переданная строка может быть использована для определения нескольких мест исходного когда, то запрос вернёт строки из всех местоположений сразу. Например, указанный выше запрос location:scenes_and_nodes.rst сначала попадёт в раздел "Введение", исходная строка которого используется на десятках страниц, включая некоторые предшествующие scenes_and_nodes.rst в шаблоне. Нажатие на кнопку "Далее" перемещает нас к строке заголовка "Сцена и узлы", как показано выше. Таким образом может случиться, что переданный параграф или часть абзаца находятся не там, где вы ожидаете их увидеть при прочтении онлайн версии страницы.

Соблюдение синтаксиса разметки

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

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

Перевод интерфейса редактора представляет из себя строку C++, в ней могут быть использованы:

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

    # PO file:
    "There is no '%s' file."
    
    # Weblate:
    There is no '%s' file.
    
  • C escape-символы такие как \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.
    

Онлайн документация (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.

См.также

Вы можете ознакомиться с примером реСтруктурированногоТекста от Sphinx-а для быстрого обзора возможностей языка разметки которые могут встретиться вам при работе с исходными строками документации. С примерами использования inline-разметки (жирный/наклонный текст, встроенный код) и внешних и внутренних ссылок вы будете сталкиваться особенно часто.

Справка классов (BBCode)

Справка классов задокументирована в основном репозитории Godot, использующем XML файлы и имеющим сходную с BBCode разметку для стилизации и создания внутренних сылок.

Некоторые тэги взяты из оригинального BBCode (к примеру [b]Жирный[/b] и [i]Наклонный[/i]) , в то время как другие - специфичны для Godot и используются для создания продвинутых элементов, таких как inline-блок кода (например [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 файле каждая строка является параграфом, что означает что вы должны использовать символы переноса строки только в тех местах, где это является частью оригинального перевода.

См.также

Обратите внимание на нашу документацию для авторов справочника классов, для получения списка тегов типа BBCode, которые используются внутри справочника классов.

Оффлайн перевод и тестирование

Хоть мы и советуем использовать онлайн-интерфейс Weblate для написания переводов, вы также можете скачать файл PO на свой ПК и использовать любой другой специализированный редактор PO файлов по своему усмотрению, например Poedit или Lokalize.

Для того чтобы скачать файл PO локально, откройте окно статуса перевода для своего языка и выберите первый элемент в меню "Файлы":

../../_images/l10n_07_download_po_file.png

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

Примечание

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

Если вы хотите протестировать изменения локально (особенно это полезно для перевода редактора), вы можете использовать скачанный PO файл и скомпилировать Godot из исходников.

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

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

Перевод изображений документации

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

Перевод изображений нельзя выполнить с помощью Weblate, для этого репозиторий godot-docs-l10n <https://github.com/godotengine/godot-docs-l10n> _ Git, в котором переводы документации синхронизируются с Weblate, нужно править вручную.

Примечание

Рабочий процесс перевода изображений несколько сложнее процесса перевода текстов, так как требует некоторых знаний устройства Git. Мы планируем разработать специальный веб-инструмент, который позволит сделать процесс перевода изображений более удобным.

Чтобы перевести изображение, сначала вам следует найти его в оригинальной англоязычной документации. Для этого перейдите на соответствующую страницу документации, например на Введение в редактор кода Godot, затем нажмите на ссылку "Edit on GitHub" в правом верхнем углу экрана:

../../_images/l10n_08_edit_on_github.png

В GitHub, кликните на картинку, которую вы хотите перевести. Если хотите, можете использовать кнопку "Скачать", чтобы скачать файл локально и отредактировать его при помощи редактора изображений, установленного на вашем ПК. Имейте ввиду, что полный путь к изображению понадобится дальше (в текущем примере getting_started/step_by_step/img/project_manager_first_open.png).

../../_images/l10n_09_path_to_image.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.

Повторите эти шаги для других изображений и ref:сделайте Запрос На Помещение (Pull Request) <doc_pr_workflow>.