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

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

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

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

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

../../_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

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

  • A toolbar which lets you cycle through strings of the current list, change to another predefined list or do a custom search, etc. There is also a "Zen" editing mode with a simplified interface.

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

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

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

  • Правая нижняя панель содержит в себе информацию об исходной строке. Самый часто ипользуемый элемент этой панели - "Расположение исходной строки", позволяет вам быстро найти исходную строку в репозитории GitHub. Вам может пригодиться возможность найти строку в окружающем её контектсе.

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

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

Важно

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

  • Шаблон перевода интерфейса редактора генерируется парсингом всего C++ source-кода в алфавитном порядке, поэтому все строки определённые в конкретном файле будут сгруппированы вместе. Например, если "Расположение исходной строки" указывает на editor/code_editor.cpp, значит текущая строка (и все ближайшие) тоже определяются в editor/code_editor.cpp файле и это, в том числе, применимо ко встроенным редакторам кода в Godot (редакторам GDScript, и шейдеров).

  • The online documentation's translation template is generated from the source RST files in the same order as seen in the table of contents, so for example the first strings are from the front page of the documentation. The recommended workflow is therefore to find a unique string corresponding to a page that you want to translate, and then translate all the strings with the same source string location while comparing with the online version of that page in English. An example of source string location could be getting_started/step_by_step/nodes_and_scenes.rst for the page Nodes and Scenes.

  • Шаблон перевода справки классов создаётся на основе XML файлов в алфавитном порядке, который также соответствует порядку следования пунктов в оглавлении онлайн версии справки. Вы можете определить расположение исходной строки соответствующее краткому описанию данного класса чтобы найти первую строку для перевода, оставшаяся часть описания класса будет представлена последующими строками на Weblate. Например, описание для класса class_Node2D`имеет расположение исходной строки ``doc/classes/Node2D.xml`.

A handy tool to locate specific pages/classes is to use Weblate's advanced search feature, and especially the "Location strings" query (which can also be used with the location: token, e.g. location:nodes_and_scenes.rst):

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

Примечание

When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above location:nodes_and_scenes.rst query would land first on the "Introduction" source string which is used in dozens of pages, including some that come before nodes_and_scenes.rst in the template. Clicking the "Next" button then brings us to the "Scene and nodes" title string displayed above. So it may happen that a given paragraph or section title is not at the location you'd expect it when reading the online version of a page.

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

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

Интерфейс редактора (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.
    

Примечание

Only logical order of the characters matters, in the right-to-left text, format specifiers may be displayed as 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.

См.также

Вы можете ознакомиться с примером реСтруктурированногоТекста от 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 файле каждая строка является параграфом, что означает что вы должны использовать символы переноса строки только в тех местах, где это является частью оригинального перевода.

См.также

See our documentation for class reference writers for the list of BBCode-like tags which are used throughout the class reference.

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

Хоть мы и советуем использовать онлайн-интерфейс 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, для этого Git-репозиторий godot-docs-l10n , в котором переводы документации синхронизируются с Weblate, нужно править вручную.

Примечание

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

Чтобы перевести изображение, сначала вам следует найти его в оригинальной англоязычной документации. Для этого перейдите на соответствующую страницу документации, например на First look at Godot's editor, затем нажмите на ссылку "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.

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