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

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

Не будемо зосереджуватися на самому написанні документації. Якщо вам потрібні настанови щодо цього, просто виконуйте настанови із сайта Sphinx. Коли написання документації буде завершено, перекласти її буде доволі просто, оскільки Sphinx постачається із підтримкою перекладів, яку доволі якісно описано у Internationalization. Достатньо декількох інструкцій налаштовування і виклику програми sphinx-intl.

Якщо ви користуєтеся службою «Read the Docs», ви можете почати збирати перекладену документацію на «Read the Docs». У їхній Localization of Documentation описано майже усе, що вам знадобиться — створення проєкту, встановлення мови для нього та пов’язування його із основним проєктом як перекладу.

Усе, що вам потрібно, це перекласти дані вашої документації. 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? Існує доволі гакерський спосіб цього досягти (використовується у документації до Weblate) — можна перевизначити спосіб Sphinx для отримання домену Gettext документа. Вставте наведений нижче фрагмент до ваших налаштувань Sphinx у 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"

Можливо, підтримку цього може бути реалізовано безпосередньо у майбутніх випусках Sphinx, див. <https://github.com/sphinx-doc/sphinx/issues/784>.

Дивись також

Документацію до модуля Python Odorik зібрано за допомогою Sphinx, «Read the Docs» і перекладено за допомогою Weblate.