Перевод контента¶

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

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

Мы используем Weblate для управления нашими переводами. Weblate — это инструмент, который позволяет нам рассматривать каждый абзац нашей документации как список дел, над которыми мы можем работать по одному.

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

Вклад в переводы¶

Перевести контент

Начало работы с переводом¶

Если вы хотите принять участие в переводе BeeWare, вам понадобится учетная запись на Weblate. Создайте новую учетную запись, если у вас ее еще нет, а затем сообщите нам, что вы заинтересованы в помощи с переводом.

Есть два способа сообщить нам, что вы хотите помочь с переводом:

Если вы пользуетесь Discord, присоединяйтесь к серверу BeeWare и перейдите в канал #translations.
Если вы не зарегистрированы в Discord, вы можете создать новую проблему в репозитории BeeWare.

В обоих случаях оставьте сообщение, включающее следующую информацию:

Ваше имя пользователя Weblate
Язык, на который вы планируете переводить контент

Как только мы получим эту информацию, мы добавим вас в команду.

Добавление нового перевода¶

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

Создайте файл /docs/mkdocs.language-code.yml, с содержанием, специфичным для языка.
Обновите tox.ini , чтобы включить новые команды сборки языка.
Обновите /docs/config.yml , чтобы включить язык под extra: alternate:.

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

Новый файл конфигурации MkDocs¶

Сначала создайте новый файл с именем mkdocs.de.yml в каталоге docs со следующим содержанием:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Вот что происходит в этом файле:

Этот файл наследует содержимое конфигурации из config.yml.
Значение site_name переводится.
Значение site_url — это URL-адрес сайта проекта, за которым следует код языка.
docs_dir должен быть кодом языка.
Значение theme: language: должно быть кодом языка, как указано в теме MkDocs Material. Для большинства языков это будет то же самое, что и код языка docs_dir, но для некоторых (в частности, для языков с локальными вариантами, такими как zh_CN), есть различия.
extra: translation_type: должно быть machine до тех пор, пока перевод не достигнет 100% в первый раз, после чего оно должно стать human. Оно вернется к machine из human, если регрессирует ниже 90%.

Обновление `tox.ini`¶

Вам нужно будет внести несколько изменений в файл tox.ini.

Вы бы добавили следующее:

Новый флаг языкового кода в строке заголовка, которая начинается с [testenv:docs, с кодом языка, предваряемым символом -, без пробелов, например -de.
Новое исключение языкового кода для первой команды, которая начинается с !lint, предшествующей -!, без пробелов, например -!de.
Новый языковой код в конце строки, начинающейся с translate : build_po_translations.
Новый языковой код в конце строки, начинающейся с translate : update_machine_translations
Новая команда, начинающаяся, например, с de : build_md_translations для немецкого языка, после других существующих языковых команд, которые соответствуют содержанию этих команд с новым кодом языка.
Новый языковой код в конце строки, начинающейся с all,serve :.

Обновление `config.yml`¶

Добавьте язык в config.yml, чтобы он отображался в выпадающем списке языков в заголовке. Найдите раздел, начинающийся с extra:, а затем найдите подраздел, начинающийся с alternate:. Для немецкого языка необходимо добавить следующее:

    - name: Deutsch
      link: /de/
      lang: de

Название языка должно быть переведено на этот язык. Ссылка должна содержать символы /.

Новый язык теперь готов к переводу.

Руководство по переводу¶

После того, как вы были добавлены в команду, пора войти в Weblate и приступить к переводу строк.

Тон против дословного перевода¶

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

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

Мне перевести это?¶

Следующие элементы не должны переводиться или обновляться:

Команды. Например, в предложении «Вы должны запустить `briefcase create`.» следует переводить только «Вы должны запустить».
Пространства имен, такие как имена классов, методов или атрибутов.
URL-адреса ссылок. Стандартные ссылки Markdown должны отображаться в Weblate в виде [Link text]{1}, где 1 — это положение ссылки в строке по отношению к другим возможным ссылкам. Если полный URL-адрес включен в строку в виде [Link text](https://example.com), этот URL-адрес следует пропустить при переводе.
Ссылки, содержащие имена классов, методов или атрибутов. Их следует оставить без изменений, включая обратные кавычки. Ни одна часть приведенного здесь примера ссылки не будет переведена.
```
[`Class.attribute`][Class.attribute]
```
Содержание ссылки Reference. Например, link-content будет пропущено в следующем случае:
```
[Link text][link-content]
```
Директивы Jinja. Это любой контент, заключенный в две пары одинаковых фигурных скобок или в пару одинаковых фигурных скобок с процентными знаками на каждом конце. Примечание: включение примера синтаксиса в данном месте приводит к тому, что плагин Macros пытается его отобразить; примеры см. в документации по макросам.
Пользовательские анкоры. Они находятся после заголовков или над некоторым контентом и имеют формат { #anchor }.
Синтаксис предупреждений. В следующем примере слово «admonition» не следует переводить. Это относится ко всем типам предупреждений, включая заметки, предупреждения и т. д. Информацию о переводе остальной части текста см. в следующем разделе.
```
/// admonition | Page Title

Content.

///
```
Обратные кавычки. Они должны оставаться обратными кавычками; они используются для форматирования как встроенного кода, так и блоков кода.
Синтаксис для включения внешнего контента. Это все, что находится в одной строке с -8<- или в строках между двумя -8<- в отдельных строках.

Следующие элементы должны быть переведены:

Текст ссылки. В синтаксисе ссылки текст предшествует URL-адресу и заключается в скобки, как в [Link text](URL). Стандартные ссылки Markdown должны отображаться в Weblate как [Link text]{1}, где 1 — это положение ссылки в строке по отношению к другим возможным ссылкам.
Текст ссылки. Например, Link text будет переведено следующим образом:
```
[Link text][link-content]
```
Названия и содержание предупреждений. В предыдущем примере предупреждения необходимо перевести «Название страницы» и «Содержание».

Weblate¶

Для перевода контента мы используем Weblate. При добавлении нового перевода мы используем DeepL для машинного перевода, чтобы получить первую версию перевода. Это означает, что, как правило, контент, который вы будете переводить, уже переведен машиной. Ожидается, что вы, как переводчик, будете проверять, редактировать и улучшать существующий машинный перевод.

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

Если после этого времени ваши изменения все еще не отображаются, вероятной причиной является ошибка разметки, приводящая к сбою в сборке документации для данного языка. Любая проблема с разметкой в любой строке блокирует публикацию всего перевода. Вы можете следить за страницей сборки для вашего языка, чтобы увидеть, успешно ли она собрана. Ссылка имеет формат, аналогичный этой ссылке на страницу сборки для французского языка https://app.readthedocs.org/projects/beewareorg/; измените код языка на ваш язык, чтобы просмотреть соответствующую страницу сборки. Это покажет состояние самой последней сборки сайта. Если сборка не удалась, посмотрите журнал сборки и попробуйте определить источник проблемы.