Локалізація документації Helm

Цей посібник пояснює, як локалізувати документацію Helm.

Початок роботи

Внесення змін у переклади використовує той самий процес, що й внесення змін у документацію. Переклади подаються через пул-реквести до репозиторію helm-www, і пул-реквести перевіряються командою, яка управляє вебсайтом.

Дволітерний код мови

Документація організована відповідно до стандарту ISO 639-1 для мовних кодів. Наприклад, дволітерний код для корейської мови — ko, української — uk.

У контенті та конфігураціях ви знайдете використовувані мовні коди. Ось 3 приклади:

У теці i18n є підтеки для кожного коду мови. Локалізований вміст для мови знаходиться в кожній підтеці.
Локалізований вміст у кожній
Для кожної мови існує файл code.json з фразами, що використовуються на веб-сайті.

Англійська мова з кодом мови en є основною мовою та джерелом для перекладів.

Форк, Гілка, Зміна, Пул-Реквест

Щоб зробити переклад, почніть зі створення форку репозиторію helm-www на GitHub. Ви почнете з внесення змін у вашому форку.

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

Коли у вас зʼявиться гілка, внесіть зміни для додавання перекладів та локалізації контенту потрібною мовою.

Зверніть увагу, що Helm використовує Developers Certificate of Origin. Всі коміти повинні мати підпис. При виконанні коміту ви можете використовувати прапорець -s або --signoff, щоб використовувати ваше налаштоване імʼя та адресу електронної пошти для підпису коміту. Більше деталей можна знайти у файлі CONTRIBUTING.md.

Коли ви будете готові, створіть пул-реквест з перекладом назад до репозиторію helm-www.

Після створення пул-реквесту один з підтримувачів перевірить його. Деталі цього процесу можна знайти у файлі CONTRIBUTING.md.

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

Локалізація всього вмісту Helm — це велике завдання. Можна почати з малого. Згодом переклади можна розширювати.

Нижче описано файли/теки, які використовуються для перекладу вмісту документів, вмісту блогу та елементів сайту в документації Helm:

i18n/<language-code> тека:
- code.json використовується для перекладу коду React на сайті (включно з лендінгом)
- i18n/<language-code>/docusaurus-plugin-content-blog тека з перекладами блогу
- i18n/<language-code>/docusaurus-plugin-content-docs тека з:
- Теки версій для перекладів вмісту документації (наприклад, i18n/<код мови>/docusaurus-plugin-content-docs/version-3/)
JSON-файли для кожної версії документації з перекладами категорій у бічній панелі (наприклад, current.json, version-3.json тощо)
- Тека i18n/docusaurus-theme-classic з файлами footer.json та navbar.json для перекладу тексту в навігаційній панелі та нижньому колонтитулі сайту
Ключі i18n у файлі docusaurus.config.js містять перелік усіх локалей та опції конфігурації для меню локалей у навігаційній панелі сайту

Для отримання додаткової інформації див. i18n - Вступ у документації Docusaurus.

Початок роботи з новою мовою

Посібник, який допоможе вам перекласти вміст сайту, див. i18n - Tutorial у документації Docusaurus.

Щоб почати роботу з новою мовою:

Якщо ви ще цього не зробили, встановіть залежності:
```
yarn install --frozen-lockfile
```
Запустіть команду Docusaurus write-translations. Наприклад, щоб додати локаль fr (французька): yarn write-translations -- --locale fr. Це створить необхідну структуру текстових файлів для мови та ініціалізує файли перекладу JSON, необхідні для перекладу елементів сайту, таких як навігаційна панель, нижній колонтитул, цільова сторінка та бічна панель.
```
yarn write-translations --locale <language-code>
```
Виконайте мінімальні переклади для нової мови:
1. Перекладіть файл code.json.
2. У теці i18n/docusaurus-theme-classic перекладіть файли footer.json та navbar.json.
3. У файлі docusaurus-plugin-content-blog/options.json перекладіть елементи блогу у файлі options.json.

Додайте мову до ключа i18n файлу docusaurus.config.js, щоб вона зʼявилася у меню навігаційної панелі:

i18n: {
  defaultLocale: 'en',
  # додайте нову мову до цього списку локалей
  locales: ['en', 'de', 'es', 'fr', 'gr', 'ja', 'ko', 'pt', 'ru', 'uk', 'zh'],
  localeConfigs: {
    en: {
      htmlLang: 'en-us',
      label: 'English',
    },
    de: {
      label: 'Deutsch',
    },
  # new_lang {
  #   label: 'Navbar label',
  # }
  },
},

(Опціонально) Перекладіть документи або вміст блогу. Див. розділ «Переклад» нижче.
Перевірте зміни, запустивши локалізований сайт у режимі розробки, вказавши локаль:
```
yarn start --locale fr
```
примітка
Кожна локаль є окремою самостійним односторінковим застосунком. Ви можете переглянути лише одну локаль за раз. Неможливо переглянути всі локалі одночасно.

Переклад

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

У процесі перекладу можуть допомогти інструменти перекладу. До них належать і машинні переклади. Машинні переклади перед публікацією повинні бути відредаговані або перевірені носієм мови на предмет граматики та змісту.
Не додавайте неперекладену копію англійського файлу до i18n/[LANG]/plugin-content-docs або i18n/[LANG]/plugin-content-blog. Після того, як мова зʼявиться на сайті, будь-які неперекладені сторінки автоматично перенаправлятимуться на англійську. Переклад займає час, і ви завжди варто перекладати найактуальнішу версію документів, а не застарілу гілку.
Переконайтеся, що ви видалили всі рядки aliases із розділу заголовка. Рядок на зразок aliases: ["/docs/using_helm/"] не належить до перекладів. Це перенаправлення для старих посилань, які не існують для нових сторінок.
Додайте ідентифікатори анкорів до будь-яких заголовків, використовуючи формат ## Приклад заголовка {#example-anchor-id}. Ідентифікатори анкорів повинні бути англійською мовою і відповідати ідентифікаторам анкорів відповідного заголовка на англійській сторінці документації. Наприклад, ## 后端存储 {#storage-backends} відповідає ## Storage backends {#storage-backends}. Це гарантує, що будь-які анкорні посилання на заголовки все ще працюють у перекладеній версії сторінки. Для отримання додаткової інформації див. Anchor links to headings у ARCHITECTURAL_DECISIONS.md.

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

Переконайтеся, що цільова локаль існує в теці i18n. Якщо її немає, див. розділ «Початок роботи з новою мовою» вище.
Скопіюйте один або кілька файлів markdown, які ви хочете перекласти, з /docs або /versioned_docs до відповідної папки версії в i18n/<language-code>/docusaurus-plugin-content-docs. Наприклад, щоб перекласти versioned_docs/version-3/example.md корейською мовою:
```
cp versioned_docs/version-3/topics/example.md i18n/ko/docusaurus-plugin-content-docs/version-3/topics/example.md
```
Скопіюйте один або кілька файлів markdown, які ви хочете перекласти, з /blog до i18n/<код мови>/docusaurus-plugin-content-blog. Наприклад, щоб перекласти blog/2025-09-09-path-to-helm-v4.md корейською мовою:
```
cp blog/2025-09-09-path-to-helm-v4.md i18n/ko/docusaurus-plugin-content-blog/2025-09-09-path-to-helm-v4.md
```
Якщо ви ще цього не зробили, встановіть залежності:
```
yarn install --frozen-lockfile
```
Перевірте зміни, запустивши локалізований сайт у режимі розробки, вказавши локаль:
```
yarn start --locale ko
```
примітка
Кожна локаль є окремим самостійним односторінковим застосунком. Одночасно можна переглянути лише одну локаль. Неможливо переглянути всі локалі одночасно.

Перехід між мовами

Користувачі переходять між мовами за допомогою випадаючого меню локалі в навігаційній панелі сайту. Ключ i18n у глобальному файлі сайту docusaurus.config.js — це місце, де налаштовується навігація між мовами. Щоб додати нову мову, додайте локаль, використовуючи дволітерний код мови, визначений вище. Приклад:

i18n: {
  defaultLocale: 'en',
  # додайте нову мову до цього списку локалей
  locales: ['en', 'de', 'es', 'fr', 'gr', 'ja', 'ko', 'pt', 'ru', 'uk', 'zh'],
  localeConfigs: {
    en: {
        htmlLang: 'en-us',
        label: 'English',
    },
    de: {
        label: 'Deutsch',
    },
    # new_lang {
    #   label: 'Navbar label',
    # }
  },
},

Початок роботи​

Дволітерний код мови​

Форк, Гілка, Зміна, Пул-Реквест​

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

Початок роботи з новою мовою​

Переклад​

Перехід між мовами​