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

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

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

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

Now all you need is translating the documentation content. Sphinx generates PO file for each directory or top level file, what can lead to quite a lot of files to translate (depending on gettext_compact settings). You can import the index.po into Weblate as an initial component and then configure Обнаружение компонента addon to automatically discover all others.

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

Название компонента	Documentation
Маска файла	docs/locales/*/LC_MESSAGES/index.po
Шаблон для новых переводов	docs/locales/index.pot
Формат файла	gettext PO file
Флаги перевода	rst-text

Component discovery configuration

Регулярное выражение для сопоставления с файлами перевода	docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po
Настроить название компонента	Documentation: {{ component|title }}
Задать базовый файл для нового перевода	docs/locales/{{ component }}.pot

Подсказка

Would you prefer Sphinx to generate just single PO file? There is a hacky way to achieve this (used by Weblate documentation) by overriding Sphinx way to get a Gettext domain of a document. Place following snippet to your Sphinx configuration in conf.py:

import sphinx.transforms.i18n
import sphinx.util.i18n

# Hacky way to have all localized content in single domain
sphinx.transforms.i18n.docname_to_domain = (
    sphinx.util.i18n.docname_to_domain
) = lambda docname, compact: "docs"

This might be directly supported by Sphinx in future releases, see <https://github.com/sphinx-doc/sphinx/issues/784>.

См.также

Документация по python’ьему модулю Odorik собрана при помощи Sphinx и Read the Docs и переведена с помощью Weblate.