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

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

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

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

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

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

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

• У теці content мовні коди використовуються як підтеки, і локалізований контент для кожної мови знаходиться в кожній теці, переважно в підтеці docs кожної теки мовного коду.
• Тека i18n містить конфігураційний файл для кожної мови з фразами, що використовуються на вебсайті. Файли називаються за шаблоном [LANG].toml, де [LANG] — це дволітерний код мови.
• У конфігураційному файлі верхнього рівня config.toml є конфігурація для навігації та інших деталей, організованих за мовним кодом.

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

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

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

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

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

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

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

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

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

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

Переклади новою мовою

Коли ви починаєте переклад новою мовою, є необхідний мінімум. Він включає:

• Додавання теки content/[LANG]/docs, що містить файл _index.md. Це головна сторінка документації для мови.
• Створення файлу [LANG].toml в теці i18n. Спочатку ви можете скопіювати файл en.toml як відправну точку.
• Додавання розділу для мови до файлу config.toml, щоб відкрити новий мовний розділ. Наявні мовні розділи можуть слугувати відправною точкою.

Переклад

Перекладений контент має знаходитися в теці content/[LANG]/docs. Він повинен мати ту ж URL-адресу, що й англійське джерело. Наприклад, для перекладу вступу на корейську мову може бути корисно скопіювати англійське джерело як:

mkdir -p content/ko/docs/intro
cp content/en/docs/intro/install.md content/ko/docs/intro/install.md

Контент у новому файлі може бути перекладено іншою мовою.

Не додавайте неперекладену копію англійського файлу в content/[LANG]/. Як тільки мова існує на сайті, будь-які неперекладені сторінки автоматично перенаправлятимуться на англійську версію. Переклад займає час, і ви завжди хочете перекладати найактуальнішу версію документації, а не застарілу версію.

Переконайтеся, що ви видалили будь-які рядки aliases з розділу заголовка. Рядка на зразок aliases: ["/docs/using_helm/"] не має бути в перекладах. Це перенаправлення для старих посилань, які не існують для нових сторінок.

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

Навігація між мовами

Глобальний файл config.toml є місцем, де налаштована навігація між мовами.

Щоб додати нову мову, додайте новий набір параметрів, використовуючи дволітерний мовний код, визначений вище. Приклад:

# Korean
[languages.ko]
title = "Helm"
description = "Helm - The Kubernetes Package Manager."
contentDir = "content/ko"
languageName = "한국어 Korean"
weight = 1

Розвʼязання внутрішніх посилань

Перекладений контент іноді міститиме посилання на сторінки, які існують тільки в іншій мові. Це призведе до помилок збірки сайту. Приклад:

12:45:31 PM: htmltest started at 12:45:30 on app
12:45:31 PM: ========================================================================
12:45:31 PM: ko/docs/chart_template_guide/accessing_files/index.html
12:45:31 PM:   hash does not exist --- ko/docs/chart_template_guide/accessing_files/index.html --> #basic-example
12:45:31 PM: ✘✘✘ failed in 197.566561ms
12:45:31 PM: 1 error in 212 documents

Щоб вирішити це, потрібно перевірити ваш контент на наявність внутрішніх посилань.

• посилання-якоря повинні відображати перекладене значення id
• внутрішні посилання на сторінки потрібно виправити

Для внутрішніх сторінок, які не існують (або ще не були перекладені), сайт не збереться до тих пір, поки не буде внесено виправлення. Як альтернативний варіант, URL може вказувати на іншу мову, де цей контент існує, наступним чином:

< relref path="/docs/topics/library_charts.md" lang="en" >

Дивіться документацію Hugo про перехресні посилання між мовами для докладнішої інформації.