Переклад документації за допомогою Sphinx

Sphinx — інструмент для створення чудової документації. У ньому використовується простий синтаксис reStructuredText, він може видавати результат у багатьох форматах. Якщо ви шукаєте приклад, цю документацію також побудовано з його використанням. Дуже корисним помічником у використанні Sphinx є служба Read the Docs, яка надає змогу збирати і оприлюднювати вашу документацію безкоштовно.

I will not focus on writing documentation itself, if you need guidance with that, just follow instructions on the Sphinx website. Once you have documentation ready, translating it is quite easy as Sphinx comes with support for this and it is quite nicely covered in their Internationalization. It’s matter of few configuration directives and invoking of the sphinx-intl tool.

If you are using Read the Docs service, you can start building translated documentation on the Read the Docs. Their Localization of Documentation covers pretty much everything you need - creating another project, set its language and link it from main project as a translation.

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
Формат файлу	файл PO gettext
Прапорці перекладу	rst-text

Налаштовування виявлення складників

Регулярний вираз для зіставлення файлів перекладу	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>.

Дивись також

The Odorik python module documentation is built using Sphinx, Read the Docs and translated using Weblate.