Как мой проект русскоязычной документации Beautiful Soup мигрировал на sphinx-intl¶
Дата публикации: 4.09.2024
Раньше я уже писала о том, как я переводила документацию Beautiful Soup в самом начале. Если в двух словах, я брала исходный текстовый файл RST на английском с сайта crummy.com и переводила его на русский с помощью FreeTM. Позже подключила еще Passolo, с помощью которого экспортировала непереведенные строки, переводила их, а затем импортировала обратно.
Такой процесс перевода я применяла до версии Beautiful Soup 4.11.0 включительно. К моменту выхода версии Beautiful Soup 4.12.0 у меня созрело желание перейти на sphinx-intl — его я уже использовала для других проектов, и он показал себя заметно более удобным, чем связка Passolo и FreeTM. Вопрос был в том, как перейти на sphinx-intl, сохранив существующий перевод версии 4.11.0. Иными словами, нужно было придумать, как, имея исходный RST-файл и его перевод, получить целевой PO-файл.
Фрагмент исходного RST:
Beautiful Soup Documentation
============================
.. image:: 6.1.jpg
:align: right
:alt: "The Fish-Footman began by producing from under his arm a great letter, nearly as large as himself."
`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ is a
Python library for pulling data out of HTML and XML files. It works
with your favorite parser to provide idiomatic ways of navigating,
searching, and modifying the parse tree. It commonly saves programmers
hours or days of work.
Фрагмент RST с переводом:
Документация Beautiful Soup
===========================
.. image:: 6.1.jpg
:align: right
:alt: "Лакей Карась начал с того, что вытащил из-под мышки огромный конверт (чуть ли не больше его самого)."
`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ — это
библиотека Python для извлечения данных из файлов HTML и XML. Она работает
с вашим любимым парсером, чтобы дать вам естественные способы навигации,
поиска и изменения дерева разбора. Она обычно экономит программистам
часы и дни работы.
Фрагмент целевого PO-файла:
#: ../../bs4ru.rst:4
msgid "Beautiful Soup Documentation"
msgstr ""
"Документация Beautiful Soup "
#: ../../bs4ru.rst:8
msgid ""
"\"The Fish-Footman began by producing from under his arm a great letter, "
"nearly as large as himself.\""
msgstr "\"Лакей Карась начал с того, что вытащил из-под мышки огромный конверт "
"(чуть ли не больше его самого).\""
#: ../../bs4ru.rst:10
msgid ""
"`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ is a "
"Python library for pulling data out of HTML and XML files. It works with "
"your favorite parser to provide idiomatic ways of navigating, searching, "
"and modifying the parse tree. It commonly saves programmers hours or days"
" of work."
msgstr ""
"`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ — это "
"библиотека Python для извлечения данных из файлов HTML и XML. Она работает "
"с вашим любимым парсером, чтобы дать вам естественные способы навигации, "
"поиска и изменения дерева разбора. Она обычно экономит программистам "
"часы и дни работы. "
Процесс миграции проходил в три этапа:
Подготовительный: создание пустых PO-файлов для дальнейшего заполнения их переводом.
Основной: конвертация перевода.
Завершающий: тестирование, исправление ошибок и сборка готовой документации.
Создание пустых PO-файлов¶
Сначала я подготовила виртуальную среду в Miniconda и установила в нее sphinx-intl как описано в руководстве Локализация документации в Sphinx. На сайте crummy.com уже была новая версия документации Beautiful Soup 4.12.0, а мне нужно было взять исходник для версии 4.11.0. К счастью, я храню исходники всех переводимых версий, так что просто нашла и извлекла нужную.
Сделала копию имеющегося проекта переведенной документации для версии 4.11 и подсунула в него вместо русскоязычного RST-файла англоязычный — таким образом я сохранила все нужные настройки проекта, не создавая его заново.
В файле conf.py я поменяла язык на английский и добавила в него новую секцию:
# -- Options for localization -----------------------------
locale_dirs = ['locale/']
gettext_compact = False
И последний шаг этапа подготовки: сначала создать файлы POT, потом файлы PO как описано в руководстве Локализация документации в Sphinx.
Конвертация перевода¶
Поломав голову над тем, как подготовить перевод к конвертации в формат PO, и перебрав разные варианты, я остановилась на том, чтобы получить из Passolo промежуточный формат, который и можно в дальнейшем обработать.
Путем экспорта из Passolo получился TXT-файл вот такого вида:
@715 String 8 in Strings 230-------------------------------
:alt: "The Fish-Footman began by producing from under his arm a great letter, nearly as large as himself."
=
:alt: "Лакей Карась начал с того, что вытащил из-под мышки огромный конверт (чуть ли не больше его самого)."
Вручную через несколько автозамен в Notepad++ я привела экспортированный файл к виду, максимально приближенному к формату PO:
#: ../../bs4ru.rst:8
\"The Fish-Footman began by producing from under his arm a great letter, nearly as large as himself.\"
\"Лакей Карась начал с того, что вытащил из-под мышки огромный конверт (чуть ли не больше его самого).\"
Оставалось написать парсер на Python, который сопоставляет элементы из получившегося файла со строчками в PO-файле и дополняет PO-файл переводом. Основная сложность заключалась в том, что в PO-файлах строки с исходным текстом разбиваются по абзацам, в то время как Passolo хранит сегменты построчно и так же их экспортирует.
Фрагмент PO-файла:
#: ../../bs4ru.rst:10
msgid ""
"`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ is a "
"Python library for pulling data out of HTML and XML files. It works with "
"your favorite parser to provide idiomatic ways of navigating, searching, "
"and modifying the parse tree. It commonly saves programmers hours or days"
" of work."
msgstr ""
Соответствующий ему фрагмент из TXT-файла:
#: ../../bs4ru.rst:10
`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ is a
`Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ — это
#: ../../bs4ru.rst:11
Python library for pulling data out of HTML and XML files. It works
библиотека Python для извлечения данных из файлов HTML и XML. Она работает
#: ../../bs4ru.rst:12
with your favorite parser to provide idiomatic ways of navigating,
с вашим любимым парсером, чтобы дать вам естественные способы навигации,
#: ../../bs4ru.rst:13
searching, and modifying the parse tree. It commonly saves programmers
поиска и изменения дерева разбора. Она обычно экономит программистам
#: ../../bs4ru.rst:14
hours or days of work.
часы и дни работы.
Из-за этого ориентироваться по номерам строк не получалось: в примере выше строке из PO-файла #: ../../bs4ru.rst:10
соответствуют аж пять строк из TXT-файла (начиная с #: ../../bs4ru.rst:10 и заканчивая #: ../../bs4ru.rst:14).
Пришлось «склеивать» строчки и сопоставлять фрагменты по тексту исходника. Это сработало, готовые переводы были перенесены из TXT в PO.
Сборка документации и исправление ошибок¶
После первого запуска сборки выяснилось, что из-за некоторых особенностей экспорта текстов из Passolo в моем PO-файле с переводом появились ошибки. Например:
Неправильно отображаются символы в Юникоде.
Сбилась нумерация заголовков.
Не экранированы символы, которые нужно экранировать.
И так далее.
После внесения исправлений сборка прошла успешно, и полученная русскоязычная версия документации Beautiful Soup ничем не отличалась от той, которая была переведена старым способом.
Перевод для версии 4.12.0 я уже обновляла по той процедуре, которая предусмотрена для sphinx-intl (см. Добавление и перевод нового контента).
