Перейти до змісту

Переклад контенту

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

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

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

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

Додавання перекладів

Перекласти текст

Переклад контенту

Перші кроки у перекладі

Якщо ви хочете долучитися до перекладу BeeWare, вам знадобиться обліковий запис на Weblate. Якщо у вас його ще немає, створіть новий обліковий запис, а потім повідомте нам, що ви готові допомогти з перекладами.

Є два способи повідомити нас про те, що ви хочете допомогти з перекладами:

  • Якщо ви користуєтеся Discord, приєднайтеся до сервера BeeWare, а потім перейдіть у канал #translations.
  • Якщо ви не зареєстровані в Discord, ви можете створити нову заявку в репозиторії BeeWare.

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

  • Ваше ім'я користувача у Weblate
  • Мова, на яку ви плануєте перекласти контент

Як тільки ми отримаємо цю інформацію, ми додамо вас до команди.

Додавання нового перекладу

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

  • Створіть файл /docs/mkdocs.language-code.yml, у якому буде вміст, специфічний для певної мови.
  • Оновіть tox.ini з метою включення нових команд для компіляції мов.
  • Оновіть /docs/config.yml, щоб додати мову до extra: alternate:.

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

Новий файл конфігурації MkDocs

Спочатку створіть у каталозі mkdocs.de.yml новий файл із назвою docs, вміст якого має бути таким:

INHERIT: config.yml
site_name: BeeWare Документація
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  language_url: de/
  translation_type: machine
  header:
    About: Про
    Documentation: Документація
    Community: Спільнота
    Contributing: Участь
    News: Новини
    Sponsor: Спонсори

Ось що відбувається в цьому файлі:

  • Цей файл успадковує вміст конфігурації з config.yml.
  • Значення site_name перекладено.
  • Значення site_url — це URL-адреса сайту проєкту, за якою йде код мови.
  • У docs_dir має бути вказано код мови.
  • Значенням theme: language: має бути код мови, як зазначено в темі MkDocs Material. Для більшості мов це значення збігатиметься з кодом мови docs_dir, але для деяких (зокрема, для мов із варіантами локалі, таких як zh_CN), існують відмінності.
  • У extra: language_url: має бути вказано код мови, за яким слідує одна коса риска, наприклад, de/ для німецької мови.
  • Значення extra: translation_type: має залишатися machine доти, доки переклад вперше не досягне 100%; після цього воно має стати human. Якщо рівень перекладу знизиться нижче 90%, значення machine знову зміниться на human.
  • Вміст у блоці extra: header — це переклади заголовків, що відображаються у верхній панелі. Це визначення не є обов’язковим на головному веб-сайті BeeWare; воно потрібне лише на інших сайтах (наприклад, у посібнику або документації до проєкту).

Оновлення tox.ini

Вам потрібно буде внести кілька змін у файл tox.ini.

Вам слід додати таке:

  • Новий прапор коду мови слід додати до рядка заголовка, що починається з [testenv:docs, причому код мови повинен передувати символу -, без пробілів, наприклад -de.
  • Нове виключення коду мови для першої команди, яка починається з !lint, перед якою стоїть -!, без пробілів, наприклад -!de.
  • Новий мовний код у рядку, що починається з translate : build_po_translations.
  • Новий мовний код у рядку, що починається з translate : update_machine_translations
  • Нова команда, що починається, наприклад, з de : build_md_translations для німецької мови, розміщена в алфавітному порядку серед існуючих команд для конкретної мови, яка відповідає змісту цих команд, із новим кодом мови.
  • Новий мовний код у рядку, що починається з all:.

Оновлення config.yml

Додайте мову до config.yml, щоб вона з’явилася у меню вибору мови в заголовку. Знайдіть розділ, що починається з extra:, а потім знайдіть підрозділ, що починається з alternate:. Для німецької мови потрібно додати таке:

- name: Німецька
 link: /de/
 lang: de

Назва мови має бути перекладена на цю мову. Посилання має містити символи /.

Виконати tox translate

Тепер ви можете запустити tox -e docs-translate. Це створить порожній файл перекладу; якщо у вас є обліковий запис DeepL, ви можете використати його для заповнення початкових машинних перекладів. Якщо у вас немає облікового запису DeepL, це не проблема — ми самі виконаємо початкові переклади перед тим, як прийняти запит на злиття.

Рекомендації щодо перекладу

Як тільки вас додадуть до команди, настав час увійти в Weblate і приступити до перекладу рядків.

Переклад, що передає загальний зміст, проти дослівного перекладу

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

Якщо англійський текст містить виразну англійську ідіому, не вважайте за обов’язок зберігати її, якщо у вашій мові є аналог, який підійде не гірше. Якщо термін або фраза в англійському тексті є особливо ідіоматичним або сленговим, не соромтеся повідомити нам, що варто розглянути можливість внесення змін. Навіть для носіїв англійської мови ідіоми та сленг можуть становити певну складність. Іноді нам доводиться змінювати англійський текст, щоб зробити його зрозумілішим як для перекладачів, так і для читачів.

Чи варто мені це перекласти?

Наступні елементи не слід перекладати чи оновлювати:

  • Команди. Наприклад, у реченні «You should run `briefcase create`.» слід перекласти лише частину «You should run».
  • Простори імен, такі як імена класів, методів або атрибутів.
  • URL-адреси посилань. Стандартні посилання у форматі Markdown повинні відображатися в Weblate у вигляді [Link text]{1}, де 1 — це позиція посилання в рядку відносно інших можливих посилань. Якщо повна URL-адреса вказана в рядку у вигляді [Link text](https://example.com/), її слід пропустити під час перекладу.

  • Посилання, що містять назви класів, методів або атрибутів. Їх слід залишати без змін, включаючи зворотні лапки. Жодна частина наведеного тут прикладу посилання не перекладатиметься.

    [`Class.attribute`][Class.attribute]

  • Вміст посилання «Reference». Наприклад, у наведеному нижче прикладі link-content буде пропущено:

    [Текст посилання][вміст посилання]

  • Директиви Jinja. Це будь-який вміст, укладений у дві пари відповідних фігурних дужок або в одну пару фігурних дужок, у кожній з яких на початку та в кінці стоїть знак відсотка. Примітка: Включення прикладу синтаксису в цьому місці призведе до того, що плагін «Macros» спробує його відтворити; приклади див. у документації до плагіна «Macros».

  • Користувацькі анкори. Вони розміщуються після заголовків або над певним вмістом і мають вигляд { #anchor }.

  • Синтаксис зауважень. У наведеному нижче прикладі слово «зауваження» не слід перекладати. Це стосується всіх видів зауважень, зокрема приміток, попереджень тощо. Інформацію щодо перекладу решти тексту див. у наступному розділі.

    /// admonition | Заголовок сторінки

Текст.

///

  • Зворотні лапки. Вони повинні залишатися зворотними лапками; їх використовують для форматування як вбудованого коду, так і блоків коду.

  • Синтаксис для вставлення зовнішнього вмісту. Це будь-що, що знаходиться в тому ж рядку, що й -8<-, або в рядках між двома символами -8<-, розташованими в окремих рядках.

Наступні елементи повинні бути перекладені:

  • Текст посилання. У синтаксисі посилань текст розміщується перед URL-адресою та береться в дужки, наприклад [Link text](URL). Стандартні посилання у форматі Markdown повинні відображатися в Weblate у вигляді [Link text]{1}, де 1 позначає положення посилання в рядку відносно інших можливих посилань.

  • Текст посилання. Наприклад, Link text перекладатиметься так:

    [Текст посилання][вміст посилання]

  • Заголовки та вміст нагадувань. У наведеному вище прикладі нагадування слід перекласти «Заголовок сторінки» та «Вміст».

Weblate

Для перекладу наших матеріалів ми використовуємо Weblate. Коли ми додаємо новий переклад, ми використовуємо DeepL для машинного перекладу, щоб отримати попередній варіант перекладу. Це означає, що, як правило, матеріал, який ви будете перекладати, вже перекладено машиною. Очікується, що ви, як перекладач, перевірите, відредагуєте та вдосконалите існуючий машинний переклад.

Weblate обробляє всі дані по черзі, рядок за рядком. Система об’єднує зміни в пакети, і кожні кілька годин відправляє масове оновлення, що містить усі рядки, які змінилися за цей проміжок часу. Тому може знадобитися кілька годин, перш ніж ваші зміни з’являться на веб-сайті, але, як правило, оновлення з’являється протягом чотирьох годин.

Якщо після закінчення цього часу ваші зміни все ще не з’явилися, ймовірною причиною є помилка у розмітці, що призвела до збою під час формування документації для цієї мови. Будь-яка проблема з розміткою в будь-якому рядку заблокує оприлюднення всього перекладу. Ви можете стежити за сторінкою збірки для вашої мови, щоб перевірити, чи збірка пройшла успішно. Посилання має такий самий формат, як і це посилання на сторінку збірки французької мови https://app.readthedocs.org/projects/beewareorg/; замініть код мови на код вашої мови, щоб перейти на відповідну сторінку збірки. Там ви побачите стан останньої збірки сайту. Якщо збірка завершилася невдало, перегляньте журнал збірки та спробуйте визначити джерело проблеми.