Як ми додали українську мову в офіційну документацію 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 можна за посиланнями. В останньму поки малий відсоток українського перекладу, тому саме час приєднатись. Правила перекладу за посиланням.

Сподобалась стаття? Натискай «Подобається» внизу. Це допоможе автору виграти подарунок у програмі #ПишуНаDOU

👍ПодобаєтьсяСподобалось49
До обраногоВ обраному12
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Дуже крута ініціатива, не зупиняйтесь.
Але на мою думку, деякі речі не мають перекладатися. У нашій справі англіцизми — це норм і їх переклад лише ускладнює читання і відвертає від матеріалу
token — це токен (так, я бачив що це автоматичний поки що переклад в даному випадку)
binary operation — це бінарна операція (а не двійкова)
thread — це тред
stream — це стрім
Я якось взяв книжку з Apache Kafka російською і відклав назавжди через 10 сторінок. Бо просто неможливо читати коли виробник замість продюсера, споживач замість консюмера, ведуча частина замість leader partition.
Більш того, якщо людина почне знайомство з таких перекладів, то коли потрапить у реальне бойове середовище — буде не у своїй тарілці. Бо у роботі всі використовують англіцизми, на конфах та вебінарах ніхто не говорить «жетон авторизації»

Так може тоді й перекладати не потрібно? Бо буде що «продюсер провайдить дату і меседжі консюмеру в кількох стрімах відповідно до їх сабскріпшнів».

Я якось взяв книжку з Apache Kafka російською і відклав назавжди через 10 сторінок. Бо просто неможливо читати коли виробник замість продюсера, споживач замість консюмера, ведуча частина замість leader partition.

«У всьому потрібні міра, норма і ліміт» (tm).
Тред, бінарна операція, токен — має значення. Продюсер, консумер — вже дуже підозріло. «Лідер партішон» — так і будете писати? Це вже точно перегин.

Більш того, якщо людина почне знайомство з таких перекладів, то коли потрапить у реальне бойове середовище — буде не у своїй тарілці. Бо у роботі всі використовують англіцизми, на конфах та вебінарах ніхто не говорить «жетон авторизації»

Але і «лідер партішон» не кажуть. «Ведуча париція» ще може бути, але не більше.

Дуже крута ініціатива, молодці!

супер, молодці! взагалі було б ідеально робити це не в Transifex, а використати український софт — Crowdin, тоді б ціни вам не було. і підтримати розвиток української локалізації і української компанії.

Якщо українська компанія готова нам надати безоплатну підписку, то ми розглянемо цей варіант. Зараз ми користуємось Transifex-проєктом японської команди безкоштовно.

так звісно, підписка безоплатна для всіх open-source проектів.
Достатньо залиши тут свій емейл і назву проекту: crowdin.com/...​rce-project-setup-request
і з вами зв’яжеться команда, щоб допомогти з міграцією та налаштуванням.

Звісно, допоможемо! Лише створіть аккаунт (організацію) тут:
accounts.crowdin.com/workspace/create

Ми допоможемо із безкоштовною ліцензією (спершу активується безкоштовний пробний період). Якщо ви плануєте перекладати проєкт публічно, тоді використайте Crowdsource крок у воркфлові (при створенні проєкту буде такий шаблон), якщо ж це буде приватно то краще використати In-House Translation шаблон.

Створіть організацію, а далі точно розберемось :)

качкова типізація
Якщо воно ходить як качок, крякає як качок, наривається як качок — то це качок

І знову ця ідіотська витівка радянських перекладачів 1970-х — thread як «потік». Ладно росіяни, а ви-то навіщо цю дурість повторили?

Token — «жетон» — самі вигадали чи десь вже було? Виглядає дивно і незвично.

Є цілі абзаци англійською. Ок, мабуть, дійдете і до них.

Взагалі більше принципових проблем не помітив. Ну що ж, мабуть, робота корисна. (Я сам подібну документацію принципово читаю тільки англійською, тому все одно не оціню смисл перекладу — тому і «мʼяке» «мабуть».)

Як я вже писав

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

Зараз статистика така: 98.54% translated, 0.8% reviewed.

Якщо ви вважаєте, що деякі переклад невірний, то можете долучитись і зробити переклад краще. Можна почати зі зміни терміну на Вікі
uk.wikipedia.org/wiki/Потік_(інформатика

Можна почати зі зміни терміну на Вікі

Там в обговоренні варіант «нитка» обсмоктаний з усіх сторін. Але це не допомагає, інерція сильніша.

👋 давно не бачились :)

І знову ця ідіотська витівка радянських перекладачів 1970-х — thread як «потік». Ладно росіяни, а ви-то навіщо цю дурість повторили?

Я чув, що іноді нитками обзивають. Але поки ужиток не стане поширеним, будь-що звучатиме незвично 🤷.

Ти ж знаєш, що такі ініціативи багато на ентузіазмі живуть? Може долучишся? Ми от, коли перекладали PyPI, багато з друзями дебатували як перекладати деякі речі. Наприклад, фічі «yank» / «unyank», що ніяк ні з чим в голові не асоціювалися. Втім кілька днів обговорень і пинань англомовного тві+авторів відповідного пепа дозволили знайти цілком прийнятний варіант...

Одним із випробувань подібних проєктів є дотримання консистентної термінології, спільний глосарій тощо. Якщо є конкретні пропозиції й аргументи, то справді варто їх висловлювати і знаходити рішення.

Token — «жетон» — самі вигадали чи десь вже було? Виглядає дивно і незвично.

Це прямий переклад слова (поза контекстом) з англійської. Дійсно, в різних контекстах навіть на вікі термінологія з токенами різниться. Як-от «маркер» отут [1].

Мене особисто турбує зловживання неправильним перекладом слова «application», яке не є тим самим, що «додаток» (attachment, appendix), але «прикладна програма» та «застосунок» (від слова «apply» — «застосовувати»). Використання «додаток» в цьому контексті — русизм/калька [2].

[1]: uk.wikipedia.org/wiki/Маркер_доступу
[2]: web.archive.org/...​et/?view=application-term

Я чув, що іноді нитками обзивають. Але поки ужиток не стане поширеним, будь-що звучатиме незвично 🤷.

Кому як. Мені «тред» і «нитка» нормально і звично, а «потік» це stream або flow, але не thread — тому що частково вчився на юніксових книгах 1990-х. В вікі в обговоренні все це пережовано декілька разів, але що толку, коли перекладачі всі працюють на москалів.

Ти ж знаєш, що такі ініціативи багато на ентузіазмі живуть? Може долучишся?

Я відійшов від пітона, да й коли він був головним, використовував його не так, як більшість (у якої звичайно веб чи врапери навколо математики). Тому скоріш за все миттєво загублю натхнення і забуду. Але подивлюсь.

Це прямий переклад слова (поза контекстом) з англійської.

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

Використання «додаток» в цьому контексті — русизм/калька [2].

Я теж цілковито і двома руками за «застосунок» :)

Дякую вам, Дмитро і команда 👏

Це дуже корисно, що з’явився український переклад. Але в переліку мов, що випадає немає Української

Я трохи описав це в розділі «Пріорітети». Для того, щоб мова з’явилась в проді (перелік мов в меню) треба мати якісний переклад пріорітетних сторінок.
В нас вже є машинний переклад і ми працюємо над рев’ю, тому зовсім скоро українська теж буде там

Здоров‘я вам і наснаги для подальшої українізації) Дуже дякую

Підписатись на коментарі