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

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

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

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

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

Настройки компонента

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

Documentation

Маска файла

docs/locales/*/LC_MESSAGES/index.po

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

docs/locales/index.pot

Формат файла

PO-файл gettext

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

rst-text
Настройка обнаружения компонентов

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

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

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

Documentation: {{ component|title }}

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

docs/locales/{{ component }}.pot

Подсказка

Вы хотите чтобы Sphinx создавал только один PO-файл? Начиная со Sphinx 3.3.0 это можно сделать с помощью:

gettext_compact = "docs"

Вот список некоторых проектов, которые используют этот подход для перевода документации: