Editor and docs localization

Godot aims to make game development available to everyone, including people who may not know or be comfortable with English. Therefore, we do our best to make the most important resources available in many languages, thanks to the translation effort of the community.

These resources include:

  1. The Godot editor's interface (ca. 15,000 words).
  2. The online documentation (editor manual and tutorials, ca. 300,000 words).
  3. The class reference, available both online and in the editor (ca. 200,000 words).

To manage translations, we use the GNU gettext file format (PO files), and the open source Weblate web-based localization platform, which allows easy collaboration of many contributors to complete the translation for the various components, and keep them up to date. Click the bold links above to access each resource on Weblate.

This page gives an overview of the general translation workflow on Weblate, and some resource-specific instructions on e.g. how to handle some keywords or the localization of images.

Совет

Translating all the official Godot content is a massive undertaking, so we advise prioritizing the resources as they are listed above: first the editor interface, then the online documentation, and eventually the class reference if there are enough translators to keep up with updates.

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

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

Вам следует `зарегистрироваться на Weblate<https://hosted.weblate.org/accounts/register/>`__, чтобы вносить свой вклад в переводы 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, вы можете добавить его в глоссарий, чтобы другие переводчики использовали то же соглашение.
  • The bottom right panel includes information on the source string. The most relevant item is the "source string location", which links you to the original string on GitHub. You may need to search for the string in the page to locate it and its surrounding context.

Locating original content

PO files are an ordered list of source strings (msgid) and their translation (msgstr), and by default, Weblate will present the strings in that order. It can therefore be useful to understand how the content is organized in the PO files to help you locate the original content and use it as a reference when translating.

Важно

It is primordial to use the original context as reference when translating, as many words have several possible translations depending on the context. Using the wrong translation can actually be detrimental to the user and make things harder to understand than if they stayed in English. Using the context also makes the translation effort much easier and more enjoyable, as you can see directly if the translation you wrote will make sense in context.

  • The editor interface's translation template is generated by parsing all the C++ source code in alphabetical order, so all the strings defined in a given file will be grouped together. For example, if the "source string location" indicates editor/code_editor.cpp, the current string (and the nearby ones) is defined in the editor/code_editor.cpp code file, and is thereby related to the code editors in Godot (GDScript, shaders).
  • 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/scenes_and_nodes.rst for the page Сцены и узлы.
  • The class reference's translation template is generated from the source XML files in alphabetical order, which is also the same as the order of the table of contents for the online version. You can therefore locate the source string corresponding to the brief description of a given class to find the first string to translate and all other descriptions from that class should be in the subsequent strings on Weblate. For example, the descriptions for the Node2D class would have the source string location 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:scenes_and_nodes.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:scenes_and_nodes.rst query would land first on the "Introduction" source string which is used in dozens of pages, including some that come before scenes_and_nodes.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.

Respecting the markup syntax

Each translation resource originates from a different source code format, and having some notions on the markup language used for each resource is important to avoid creating syntax errors in your translations.

Editor interface (C++)

The editor translations originate from C++ strings, and may use:

  • C format specifiers such as %s (a string) or %d (a number). These specifiers are replaced by content at runtime, and should be preserved and placed in your translation where necessary for it to be meaningful after substitution. You may need to refer to the source string location to understand what kind of content will be substituted if it's not clear from the sentence. Example (%s will be substituted with a file name or path):

    # PO file:
    "There is no '%s' file."
    
    # Weblate:
    There is no '%s' file.
    
  • C escape characters such as \n (line break) or \t (tabulation). In the Weblate editor, the \n characters are replaced by (return) and \t by . Tabs are not used much, but you should make sure to use line breaks in the same way as the original English string (Weblate will issue a warning if you don't). Line breaks might sometimes be used for vertical spacing, or manual wrapping of long lines which would otherwise be too long especially in the editor translation). Example:

    # 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.
    

Online documentation (RST)

The documentation translations originate from reStructuredText (RST) files, which also use their own markup syntax to style text, create internal and external links, etc. Here are some examples:

# "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.

См.также

See Sphinx's reStructured Text primer for a quick overview of the markup language you may find in source strings. You may encounter especially the inline markup (bold, italics, inline code) and the internal and external hyperlink markup.

Class reference (BBCode)

The class reference is documented in the main Godot repository using XML files, and with BBCode-like markup for styling and internal references.

Some of the tags used are from the original BBCode (e.g. [b]Bold[/b] and [i]Italics[/i]), while others are Godot-specific and used for advanced features such as inline code (e.g. [code]true[/code]), linking to another class (e.g. [Node2D]) or to a property in a given class (e.g. [member Node2D.position]), or for multiline code blocks. Example:

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].

In the above example, [code]name[/code], [code]alpha[/code], and [Color] should not be translated, as they refer respectively to argument names and a class of the Godot API. Similarly, the contents of the [codeblock] should not be translated, as ColorN is a function of the Godot API and "red" is one of the named colors it supports. At most, you can translate the name of the variable which holds the result (red = ...).

Note also that in the XML, each line is a paragraph, so you should not add line breaks if they are not part of the original translation.

См.также

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

Offline translation and testing

While we advise using the Weblate interface to write translations, you also have the possibility to download the PO file locally to translate it with your preferred PO editing application, such as Poedit or Lokalize.

To download the PO file locally, browse to the translation overview for your language, and select the first item in the "Files" menu:

../../_images/l10n_07_download_po_file.png

Once you are done with a series of edits, use the "Upload translation" item in that same menu and select your file. Choose "Add as translation" for the file upload mode.

Примечание

If a significant amount of time has passed between your download of the PO file and the upload of the edited version, there is a risk to overwrite the translations authored by other contributors in the meantime. This is why we advise to use the online interface so that you always work on the latest version.

If you want to test changes locally (especially for the editor translation), you can use the downloaded PO file and compile Godot from source.

Rename the editor translation PO file to <lang>.po (e.g. eo.po for Esperanto) and place it in the editor/translations/ folder (GitHub).

You can also test class reference changes the same way by renaming the PO file similarly and placing it in the doc/translations/ folder (GitHub).

Localizing documentation images

The online documentation includes many images, which can be screenshots of the Godot editor, custom-made graphs, of any other kind of visual content. Some of it includes text and might thus be relevant to localize in your language.

This part is not handled via Weblate, but directly on the godot-docs-l10n Git repository where the documentation translations are synced from Weblate.

Примечание

The workflow is not the most straightforward and requires some knowledge of Git. We plan to work on a simplified Web tool which could be used to manage image localization in a convenient way, abstracting away these steps.

To translate an image, you should first locate it in the original English documentation. To do so, browse the relevant page in the docs, e.g. Введение в редактор кода Godot. Click the "Edit on GitHub" link in the top right corner:

../../_images/l10n_08_edit_on_github.png

On GitHub, click on the image you want to translate. If relevant, click on "Download" to download it locally and edit it with an image edition tool. Note the full path to the image as it will be needed further down (here getting_started/step_by_step/img/project_manager_first_open.png).

../../_images/l10n_09_path_to_image.png

Create your localized version of the image, either by editing the English one, or by taking a screenshot of the editor with your language, if it's an editor screenshot. Some images may also have source files available in SVG format, so you can browse the img/ folder which contains them to check for that.

Name your localized image like the original one, but with the language code added before the extension, e.g. project_manager_first_open.png would become project_manager_first_open.fr.png for the French localization.

Finally, on godot-docs-l10n, recreate the same folder structure as for the original image in the images subfolder (GitHub), and place your translated image there. In our example, the end result should be images/getting_started/step_by_step/img/project_manager_first_open.fr.png.

Repeat this for other images and make a Pull Request.