Мультиязычность

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

Организация файлов #

Для создания мультиязычного проекта создайте отдельные директории для каждого языка, например, src/en и src/ru. В конфиге проекта укажите каждую такую директорию как корень отдельного документа.

В поле primary укажите, какой вариант документации считается основным. Понятие основного документа важно для версионирования текста. Если поле primary опущено, основным считается самый первый документ, описанный в конфиге.

Пример конфига мультиязычного проекта:

primary: ru
languages:
  en:
    title: Documentation
    paths:
      root: src/en
      include: ['**/*.md']
  ru:
    title: Документация
    paths:
      root: src/ru
      include: ['**/*.md']

Переключение языка в HTML #

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

{% set translations = project.get_all_translations(page) %}
{% if translations | length > 1 %}
  <ul class='translations'>
    {% for translation in translations %}
    
      {% if translation is sameas page %}
        {% set name = Language.from_part1(translation.document.lang).name %}
        <li>{{ name }}</li>
        
      {% else %}
        {% set url = builder.make_internal_url(translation, page=page) %}
        {% set name = Language.from_part1(translation.document.lang).name %}
        <li><a href='{{ url }}'>{{ name }}</a></li>
        
      {% endif %}
      
    {% endfor %}
  </ul>
{% endif %}

В примере используется метод project.get_all_translations(). Он перебирает все документы с таким же кодовым именем, как у текущего документа, и в каждом из них находит страницу с таким же путём, как у текущей страницы. Сама текущая страница также попадает в возвращаемый список. В примере проверяется, что в списке более одного элемента, то есть для страницы существуют языковые версии, кроме текущей.

Чтобы отличить текущую страницу от остальных, используется стандартная проверка sameas в Jinja. Название языка текущей страницы отображается простым текстом без ссылки. Названия остальных страниц отображаются как ссылки на эти страницы.

Полные названия языков формируются с помощью библиотеки iso639. Например, для кода “ru” сформируется название “Russian”.

Ссылки на страницы формируются с помощью метода make_internal_url() класса WebBuilder, который является частью Собираки.

Версионирование текста #

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

Работа команды предполагает, что:

• один из языков проекта считается основным (см. поле primary конфига);
• в исходных файлах страниц указываются версии текста (см. поле version метаданных).

При внесении критичных изменений в оригинал обязательно увеличивайте его мажорную версию. Например, если вы добавили описание новой функциональности в оригинал, ранее имевший версию 2.4, замените её на 3.0. Благодаря этому Собирака будет знать, что переводы, написанные на основе версии оригинала 2.4, могли устареть.

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

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