Налаштування нової локалізації

Покроковий посібник для підтримки нової локалізації мови на вебсайті OpenTelemetry.

Цей посібник допоможе адміністраторам веб-сайту OTel виконати всі необхідні зміни для додавання нової мовної локалізації. У ньому розглядаються як зміни на рівні репозиторію, так і налаштування на рівні організації GitHub.

Щодо питань, які стосуються учасників локалізації — рекомендації з перекладу, відстеження змін в англомовній версії та поточна підтримка — дивіться в розділ Локалізація сайту.

Канонічний реєстр активних команд локалізації та їхніх ресурсів знаходиться в projects/localization.md.

Попередні вимоги

Перед тим як розпочати, узгодьте наступне з командою локалізації:

Створено тікет для запуску локалізації відповідно до кроків у New localizations.
Узгоджено код мови за стандартом ISO 639-1 (LANG_ID).
Відомі GitHub-імена ментора та початкових учасників.

У решті цього посібника замініть кожне використання LANG_ID на фактичний код за стандартом ISO 639-1 (наприклад, uk для української).

Крок 1 — Налаштування мови в Hugo config

Крок 1a. Мова в config

Додайте запис для нової мови в config/_default/hugo.yaml до ключів в languages::

LANG_ID:
  languageName: NativeName (English name)
  languageCode: LANG_ID-REGION
  params:
    description: <опис сайту, перекладений на нову мову>

Наприклад, запис для польської мови виглядає так:

pl:
  languageName: Polski (Polish)
  languageCode: pl-PL
  params:
    description: Strona projektu OpenTelemetry

Крок 1b. Файл з перекладами

У теці i18n створіть новий файл з назвою LANG_ID.yaml (наприклад, uk.yaml). Цей файл міститиме деякі перекладені рядки для нової мови. Ці рядки використовуються для елементів інтерфейсу та інших компонентів сайту, які не обовʼязково є частиною основного контенту, або використовуються на кількох сторінках.

Крок 2 — Монтування контенту в Hugo

Hugo використовує монтування контенту для маршрутизації контенту, специфічного для локалі, та для показу англійських сторінок у тих розділах, які ще не перекладені. Додайте блок для LANG_ID у config/_default/module-template.yaml під верхнім рівнем секції mounts: (цей шаблон перетворюється у файл module.yaml).

Базове налаштування

Кожна локаль потребує принаймні наступних монтувань — власний контент локалі плюс альтернативний контент з основних англійських розділів:

## LANG_ID
- source: content/LANG_ID # сторіни перекладені відвідною мовою
  target: content
  sites: &LANG_ID-matrix
    matrix: { languages: [LANG_ID] }
# альтернативні сторінки (надають англійський контент, якщо переклад ще не готовий)
- source: content/en/_includes
  target: content/_includes
  sites: *LANG_ID-matrix
- source: content/en/announcements
  target: content/announcements
  sites: *LANG_ID-matrix
- source: content/en/docs
  target: content/docs
  files: ['! specs/**'] # виключити фрагменти специфікацій (занадто великі для fallback)
  sites: *LANG_ID-matrix

Додаткові розділи (наприклад, ecosystem) можна додавати по мірі розвитку локалізації. Наприклад, блок pt включає альтернативний контент для ecosystem:

## pt
- source: content/pt
  target: content
  sites: &pt-matrix
    matrix: { languages: [pt] }
# альтернативні сторінки
- source: content/en/_includes
  target: content/_includes
  sites: *pt-matrix
- source: content/en/announcements
  target: content/announcements
  sites: *pt-matrix
- source: content/en/docs
  target: content/docs
  files: ['! specs/**']
  sites: *pt-matrix
- source: content/en/ecosystem
  target: content/ecosystem
  sites: *pt-matrix

Додайте новий блок поряд з наявними блоками локалей у config/_default/module-template.yaml, дотримуючись поточних домовленостей щодо порядку, що використовуються в цьому файлі.

Крок 3 — Перевірка орфографії

3a. Перевірка наявності словника cspell

Знайдіть у npm словник cspell для мови, яку ви додаєте:

npm search @cspell/dict

Шукайте пакунок, що відповідає @cspell/dict-LANG_ID або найближчому регіональному варіанту (наприклад, @cspell/dict-pl_pl для польської). Ви також можете переглянути повний список доступних словників у репозиторії cspell-dicts.

3b. Встановлення словника (якщо доступно)

npm install --save-dev @cspell/dict-LANG_ID

Це додає пакунок до package.json. Зробіть коміт оновлених файлів package.json та package-lock.json.

3c. Створення власного списку слів

Створіть порожній файл для локальних технічних термінів сайту:

touch .cspell/LANG_ID-words.txt

Зробіть коміт з цим порожнім файлом. Учасники з часом додаватимуть сюди технічні терміни, специфічні для локалі.

3d. Оновлення `.cspell.yml`

Додайте три записи до .cspell.yml для увімкнення перевірки орфографії для нової мови:

В import: — імпортуйте словник cspell для вашої локалі:
```
- '@cspell/dict-CSPELL_DICT_ID/cspell-ext.json'
```
В dictionaryDefinitions: — зареєструйте власний список слів:
```
- name: LANG_ID-words
  path: .cspell/LANG_ID-words.txt
```
В dictionaries: — активуйте як імпортований словник, так і власний список слів:
```
- CSPELL_DICT_ID # пакунок @cspell/dict-CSPELL_DICT_ID
- LANG_ID-words # список .cspell/LANG_ID-words.txt
```

Зберігайте записи в кожному розділі в алфавітному порядку за кодом мови.

Примітка

Якщо для мови не існує пакунка словника cspell, пропустіть кроки 3b та записи import і dictionaries. Створіть лише власний список слів (крок 3c) і зареєструйте його в dictionaryDefinitions. Також додайте шлях до локалі в список ignorePaths у .cspell.yml щоб cspell не намагався перевіряти орфографію вмісту, який він не може перевірити:

ignorePaths:
  - content/LANG_ID

Крок 4 — Prettier (за певних умов)

Якщо Prettier не обробляє мову належним чином — наприклад, абетки, що пишуться справа наліво, або використовують нелатинські символи — додайте запис до .prettierignore:

content/LANG_ID/**

Перевірте наявні записи в .prettierignore щоб дізнатися, чи інші локалі з подібними скриптами вже були виключені, і дотримуйтесь того ж шаблону. Цей крок є необовʼязковим і повинен виконуватися лише тоді, коли відомо, що Prettier неправильно форматуватиме мову.

Крок 5 — Автоматизація репозиторію GitHub

Мапа міток компонентів

В .github/component-label-map.yml, додайте запис, який активує мітку lang:LANG_ID для будь-якого PR, що торкається content/LANG_ID/:

lang:LANG_ID:
  - changed-files:
      - any-glob-to-any-file:
          - content/LANG_ID/**

Власники компонентів

В .github/component-owners.yml, додайте запис, який вимагає перегляду від команди затверджувачів локалі та підтримувачів документації:

content/LANG_ID:
  - open-telemetry/docs-maintainers
  - open-telemetry/docs-LANG_ID-approvers

Обидва файли підтримують алфавітний порядок за кодом мови в межах відповідних секцій локалі.

Крок 6 — Налаштування на рівні організації GitHub

Ці кроки виконуються поза межами репозиторію і вимагають доступу рівня супровідника до організації GitHub open-telemetry.

Створення команди здійснюється шляхом відкриття pull request у open-telemetry/admin репозиторії (приватний). Дивіться цей PR для прикладу очікуваного формату.

Примітка

Члени команди повинні бути додані вручну, оскільки вони наразі не керуються через цей репозиторій.

Крок 7 — Канал Slack

Створіть канал для локалі в CNCF Slack workspace, використовуючи номенклатуру #otel-localization-LANG_ID (наприклад, #otel-localization-pl для польської). Після створення каналу додайте OpenTelemetry Admin як менеджера каналу.

Крок 8 — Моніторинг проєкту

Оновіть projects/localization.md з інформацією про нову локаль:

Додайте мову до списку підтримуваних мов у верхній частині, в алфавітному порядку за кодом мови:
```
- [NativeName - EnglishName (LANG_ID)][LANG_ID]

[LANG_ID]: https://opentelemetry.io/LANG_ID/
```

Додайте запис команди в Current language teams, дотримуючись тієї ж структури, що й наявні записи:

**EnglishName**:

- Website: <https://opentelemetry.io/LANG_ID/>
- Slack channel:
  [`#otel-localization-LANG_ID`](https://cloud-native.slack.com/archives/XXXXXXXXXXX)
- Maintainers: `@open-telemetry/docs-LANG_ID-maintainers`
- Approvers: `@open-telemetry/docs-LANG_ID-approvers`

Додайте мітку lang:LANG_ID до розділу Labels:

- [`lang:LANG_ID`][issues-lang-LANG_ID] - EnglishName localization

З відповідним визначенням посилання:

[issues-lang-LANG_ID]: https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue%20state%3Aopen%20label%3Alang%3ALANG_ID

Додайте визначення посилання для каналу Slack:

[otel-localization-LANG_ID]: https://cloud-native.slack.com/archives/CHANNEL_ID

Перевірка

Контрольний список налаштувань

Використовуйте наступний список для підтвердження, що кожен крок налаштування завершено перед тим як запитати рецензію:

Крок 1 — Додано запис мови до config/_default/hugo.yaml
Крок 2 — Додано точки монтування контенту до config/_default/module-template.yaml
Крок 3 — Налаштовано cSpell: встановлено словник (або додано локаль до ignorePaths), створено власний список слів у .cspell/LANG_ID-words.txt, та оновлено .cspell.yml
Крок 4 — Оновлено .prettierignore (якщо застосовується для скрипу)
Крок 5 — Оновлено .github/component-label-map.yml та .github/component-owners.yml з записами lang:LANG_ID
Крок 6 — Відкрито PR команди в open-telemetry/admin; учасники команди додані вручну
Крок 7 — Slack channel #otel-localization-LANG_ID створено; OpenTelemetry Admin додано як менеджера каналу
Крок 8 — projects/localization.md оновлено з записом мови, записом команди, міткою та посиланням на канал Slack

Автоматизовані перевірки

Після злиття всіх PR виконайте наступне, щоб підтвердити правильність конфігурації:

npm run build — підтверджує, що Hugo розпізнає нову мову без помилок.
npm run check:spelling — підтверджує, що конфігурація cspell дійсна і що нові записи словника не вводять помилок.
Автоматизація міток GitHub — відкрийте тестовий PR, який змінює файл в content/LANG_ID/, і підтвердьте, що мітка lang:LANG_ID застосовується автоматично.

Востаннє змінено December 26, 2024: [uk] Ukrainian documentation for OpenTelemetry (091c99cf)