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

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

Не будемо зосереджуватися на самому написанні документації. Якщо вам потрібні настанови щодо цього, просто виконуйте настанови із сайта Sphinx. Коли написання документації буде завершено, перекласти її буде доволі просто, оскільки Sphinx постачається із підтримкою перекладів, яку доволі якісно описано у Internationalization. Це питання кількох директив конфігурації та виклику інструмента 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"

За допомогою цього підходу виконується переклад кількох проєктів з документування: