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

mlango хочет быть понятным, а «понятный» зависит от языка, на котором вы думаете. Переводы приветствуются по одной странице за раз — не нужно переводить всё, прежде чем открыть pull request.

Как это устроено¶

Английский — источник истины. Переводы лежат рядом с каждой страницей, с суффиксом локали:

docs/
├── index.md          ← английский (источник)
├── index.ru.md       ← русский
├── index.es.md       ← испанский, когда кто-нибудь его напишет
├── tutorial.md
└── tutorial.ru.md

Страница, у которой нет перевода на язык читателя, автоматически откатывается к английской, поэтому частичный перевод никогда не оставит сломанную навигацию или битую ссылку. Именно это делает вклад по частям безопасным.

Добавить страницу на существующем языке¶

Скопируйте английскую страницу: cp docs/models.md docs/models.ru.md
Переведите текст. Код, идентификаторы, названия настроек, полей и команд оставьте на английском — это API, а не проза.
Соберите и посмотрите: mkdocs serve, затем переключатель языка.
Откройте pull request с заголовком docs(i18n): translate models.md to ru.

Заголовки, на которые ссылаются, требуют явного анкора

Заголовок не из латиницы даёт анкор вида _3, привязанный к порядку заголовков на странице, — то есть ссылка на него ломается, как только выше добавят раздел. Если на заголовок ссылаются, задайте анкор английской страницы явно:

### Свои данные { #bringing-your-own-data }

Тогда [текст](cli.md#bringing-your-own-data) ведёт в нужное место на любом языке.

Добавить новый язык¶

Добавьте блок локали в mkdocs.yml под плагином i18n:

- locale: es
  name: Español
  build: true
  site_description: >-
    Un framework con baterías incluidas para machine learning,
    analítica y agentes LLM.
  nav_translations:
    Getting started: Primeros pasos
    Introduction: Introducción
    Tutorial: Tutorial
    Concepts: Conceptos
    # ... остальные подписи навигации

Затем в том же pull request переведите хотя бы index.md, чтобы у языка была своя главная страница, а не английская за испанским переключателем.

Текущие языки: English (источник), Русский.

Что переводить, а что оставить¶

Переводить	Оставить на английском
Прозу, заголовки, заголовки таблиц	Блоки кода и `code` в строке
Объяснения и обоснования	Названия настроек (`METASTORE`, `DEFAULT_PROVIDER`)
Текст врезок	Названия полей и классов (`LabelField`, `Dataset`)
Alt-текст изображений	Названия команд (`manage.py train`)
Прозу в docstring'ах внутри примеров, если это помогает	Названия методов и опций `Meta`

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

Терминология¶

У части терминов нет хорошего местного аналога, и их лучше оставить как есть — записав местным алфавитом, если так читается естественнее. Рекомендации:

Английский	Как поступать
dataset	«Датасет». Слово прижилось, переводить как «набор данных» громоздко.
run	«Запуск» — одно исполнение, а не пробежка.
trace / span	Оставить: это устоявшиеся термины observability.
fingerprint	Переводить смысл («хеш объявления»), а не метафору.
queryset	Оставить: это имя конкретного класса.
batteries-included	Переводить идею, а не идиому: «со всем необходимым в комплекте».

Если термин не переводится, откройте issue про перевод и обсудите его до того, как остановиться на варианте, — единообразие между страницами важнее любого отдельного слова.

Как переводы остаются честными¶

Когда английская страница меняется по существу, её переводы молча устаревают. Две привычки держат это под контролем:

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

Слегка устаревший перевод лучше, чем никакого. Перевод, описывающий поведение, которого у фреймворка больше нет, хуже, чем никакого, — если нашли такой, пожалуйста, откройте issue, а не оставляйте как есть.

Сборка документации локально¶

pip install mkdocs-material mkdocs-static-i18n
mkdocs serve            # http://127.0.0.1:8000
mkdocs build --strict   # то, что запускает CI

--strict превращает предупреждения в ошибки, поэтому битая ссылка ломает сборку, а не уезжает в релиз.