Як ми додали українську мову в офіційну документацію Python

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті.

Всім привіт. Я Дмитро, і нам з командою вдалося додати українську мову в офіційну документацію мови програмування Python.

Ідея

Початково ця ідея з’явилась в мене після того, як в репозиторії документації Scala одобрили мій перший PR і на сайті з’явились українські переклади кількох сторінок документації. Закортіло повторити те саме і для однієї з найпопулярніших мов програмування. Коли я висловив цю ідею в одному з Data Science чатів, було запитання «а який сенс в цьому?». Отже, моя мотивація, в першу чергу, заявити про те, що в Україні є пітоністи і вони активні. По-друге, сподіваюсь, що в більшій кількості шкіл будуть вчити Python замість Pascal, тому документація українською буде для них корисною.

Процес

Отже, коротко розповім про те, як проходив процес. Я написав про свою ідею в робочу групу ([email protected]), яка займається перекладом документаціїї на інші мови. У відповідь я отримав посилання на туторіал, де описано процес додавання нової мови.
Перший крок — це генерація файлів для перекладу (.po) з репозиторію cpython. Для цього я скористався інструментом cookiecutter. Всі ці вихідні файли я завантажив в персональний репозиторій.
Наступним було питання того, як організувати процес перекладу. Наприклад, французська команда використовує лише GitHub і багато років вручну перекладає файли. Проте інші команди користуються сервісом Transifex, а точніше конкретним проєктом , яку створила японська команда для більш зручного процесу перекладу. Проте зараз там є багато команд, які перекладають з англійської на інші мови, використовуючи одні і ті ж вихідні тексти. Української мови там не було, тому я надіслав запит, але його так довго розглядали, що я створив свій власний Transifex-проєкт. Маючи максимальні права і лише одну мову для перекладу я одразу налаштував машинний переклад за допомогою Google Translate. На моєму Google-акаунті все ще не був використані пробні $300, тому я активував його і отримав API-токен, користуючись цією статтею. Після певних налаштувань і завантаження всіх ресурсів на Transifex почався автоматичний машинний переклад. Всього за кілька годин і за $140 вся документація була перекладена на українську.

До того часу на основному Transifex проєкті Tomo Cocoa з японської команди вже додав український переклад і призначив мене модератором. Власне весь машинний переклад зі свого аккаунту я завантажив туди. Також почав додавати туди редакторів і перекладачів команди.

Настав час налаштувати завантаження перекладів з Transifex GitHub і генерації html- latex- та pdf-файлів. Для цього я взяв пайплайн у польської команди, а Maciej Olko трохи допоміг з тим. Результатом першої генераці було більше 9600 помилок. Виявилось, що під час машинного перекладу було пошкоджено безліч перехресних посилань. Тому довелося витратити майже тиждень часу, щоб за допомогою регулярних виразів і глобального пошуку, виправити всі ці помилки. Але навіть після цього Sphinx продовжував видавати помилку WARNING: rST localisation for language "uk" not found. Ймовірно, це пов’язано з відсутністю підтримки української мови у бібліотеці docutils, яку використовує sphinx, тому довелось робити ще й переклад для docutils. З цим допоміг Adam Turner з команди Sphinx, бо зовсім не було часу і бажання реєструватись на sourceforge.

На той час вже запустився процес ручного редагування і перекладу членами команди. А я, при участі Julien Palard з французської команди, почав трансфер особистого репозиторію до організації «python».

Ну і фінальний штрих — додавання українського перекладу у процес генерації документаціїї для сайту docs.python.org.

Необхідно зауважити, що більшість текстів є машинним перекладом, тому потребує перегляду і редагування. Ми продовжуємо це робити, але якщо у вас є час та натхнення долучитись до цього процесу — додавайтесь в наш чат.

Долучитись

• Зареєструйтесь на платформі Transifex.com.
• Перейдіть на сторінку проєкту.
• Натисніть кнопку Join Team, оберіть українську (uk) мову та натисніть Join.
• Приєднавшись до команди, оберіть ресурс, який хочете виправити/оновити.
• Після перегляду перекладу то відмітьте його як «Reviewed».
• Якщо ви не згодні з перекладом, який вже «Reviewed» — пишіть в чат.

Пріорітети

Для того, щоб українська з’явилась на продакшені, тобто щоб на docs.python.org у меню вибору мов з’явилась українська, необхідний мати якісний переклад наступних ресурсів:

• глосарій (34% translated, 0% reviewed)
• bugs (100% translated, 100% revieved)
• library--functions (100% translated, 24% revieved)
• tutorial--* (100% translated, 0% revieved)

Також ви можете перекласти ті документи, для яких все ще немає машинного перекладу.

Форматування і переклад

У цьому абзаці наведу правила форматування, яких необхідно дотримуватись, щоб не зламати внутрішні посилання:

1. Переносимо без перекладу назви модулів, класів, методів, атрибутів, типів тощо:
   :class:`list`
:func:`exec`
:const:`None`
:attr:`__annotations__`
:envvar:`PYTHONMALLOCSTATS`
:exc:`SyntaxError`
:program:`env`
:source:`Modules`
:pep:`572`
:mod:`importlib.abc`
:file:`{prefix}/include/pythonversion/`
:c:type:`PyMemAllocatorDomain`
:c:func:`calloc`
:c:member:`~PyTypeObject.tp_itemsize`
2. Не перекладаємо синтаксичні конструкції мови, а також результат виконання, завичай вони обгорнуті подвійними зворотніми лапками:
   ``- 1``,``None``
3. Терміни та посилання можуть не перекладатись зовсім:
   :ref:`distutils-index` -> :ref:`distutils-index`
4. Терміни і посилання, для які можна перекласти, мають містити оригінальне посилання:
   :term:`duck-typing` -> :term:`качина типізація <duck-typing>`
5. Якщо посилання вже містить альтернативний текст, то перекладаємо лише його:
   :ref:`Python Initialization Configuration <init-config>` -> :ref:`Конфігурація ініціалізації Python <init-config>`

Подяка

Велика вдячність редакторам та перекладачам:
Olga Tomakhina, Serhii Pavlenko, Andrii Soldatenko, Ihor Shrubkovskyi, Tetiana Agarkova, Dmytro Kyrychuk, Misha Fedorov, Nickolai Kyrylovych, Назар Клипич, Andrii Roiko, а також іншим учасникам команди.

UPD

До нашої команди долучився Святослав Сидоренко (github, twitter), який разом з Oleksandr Kovalchuk та Alex Solonenko переклали значну частину документації Python Package Index (PyPI), завдяки чому українська була однією з найперших перекладів.
Долучитися до проєкту з перекладу PyPI та Python Packaging User Guide можна за посиланнями. В останньму поки малий відсоток українського перекладу, тому саме час приєднатись. Правила перекладу за посиланням.