Перевод документации с помощью Sphinx

Sphinx — это инструмент для создания красивой документации. Он использует простой синтаксис reStructuredText и может генерировать вывод во многих форматах. Если вы ищете пример, то эта документация также собирается с его помощью. Очень полезным спутником при использовании Sphinx является сервис Read the Docs, который бесплатно будет собирать и публиковать вашу документацию.

Я не буду заострять внимание на написание самой документации, если вы нуждаетесь в консультации, просто следуйте инструкциям на сайте Sphinx’а. После того, как ваша документация будет написана, её перевод будет довольно простым делом, поскольку Sphinx уже поддерживает для этого всё необходимое, что хорошо описано в его документации по интернационализации. Это буквально вопрос настройки нескольких параметров и вызова инструмента sphinx-intl.

Если вы пользуетесь сервисом Read the Docs, вы запустить сборку переведённой документации на Read the Docs. Их документация по локализации покрывает практически всё, что вам нужно знать — создание ещё одного проекта, установку его языка и связывание его с основным проектом в качестве перевода.

Теперь всё, что вам нужно — это перевести содержимое документации. Sphinx генерирует PO-файл для каждого каталога или файла верхнего уровня, что может привести к тому, что у вас появится довольно большое количество файлов для перевода (в зависимости от настройки параметра gettext_compact). Вы можете импортировать в Weblate в качестве начального компонента файл index.po, а затем настроить надстройку Обнаружение компонента для автоматического обнаружения всех остальных файлов.

Конфигурация компонента

Название компонента

Документация

Маска файла

docs/locales/*/LC_MESSAGES/index.po

Шаблон для новых переводов

docs/locales/index.pot

Формат файла

PO-файл gettext

Флаги перевода

rst-text

Конфигурация обнаружения компонентов

Регулярное выражение для сопоставления с файлами перевода

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

Настроить название компонента

Документация: {{ component|title }}

Задать базовый файл для нового перевода

docs/locales/{{ component }}.pot

Подсказка

Would you prefer Sphinx to generate just single PO file? Since Sphinx 3.3.0 you can achieve this using:

gettext_compact = "docs"

You can find several documentation projects being translated using this approach: