Information in this document may be out of date

This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: Localizing Kubernetes documentation

Локализация документации Kubernetes

На этой странице рассказывается, как локализовать документацию на разные языки.

Начало работы

Из-за того, что участники не могут одобрять собственные пулреквесты, нужно как минимум два участника для инициализации локализацию.

Все команды по локализации должны быть самодостаточными. Это означает, что мы с радостью разместим вашу работу, но мы не можем сделать перевод за вас.

Определение двухбуквенного кода языка

Первым делом ознакомьтесь со стандартом ISO 639-1, чтобы найти двухбуквенный код страны для вашей локализации. Например, двухбуквенный код для корейского языка будет ko.

Создание копии репозитория

Для начала создайте собственную копию репозитория оригинального репозитория kubernetes/website.

Затем клонируйте свою копию репозитория и перейдите в неё с помощью команды cd:

git clone https://github.com/<username>/website
cd website

Создание пулреквеста

Далее откройте пулреквест (PR) с локализацией в репозиторий kubernetes/website.

Для того, чтобы ваш пулреквест был одобрен, он должен содержать необходимый минимум контента.

В качестве примера добавления новой локализации, изучите PR, который добавляет документацию на французском.

Вступление в GitHub-организацию Kubernetes

Как только, как вы открыли PR с локализацией, вы можете стать членом организации Kubernetes на GitHub. Каждый член команды должен подать запрос на членство в организации в репозитории kubernetes/org.

Добавление команды локализации на GitHub

Теперь нужно добавить вашу команду локализации Kubernetes в файл sig-docs/teams.yaml. Для примера добавления команды локализации можете посмотреть PR, добавляющий испанскую команду локализации.

Члены @kubernetes/sig-docs-**-owners — могут одобрять PR, которые изменяют файлы внутри (и только там) директории с локализацией: /content/**/.

Для каждой локализации группа @kubernetes/sig-docs-**-reviews служит для автоматизации выбора проверяющих новых PR.

Члены @kubernetes/website-maintainers могут создавать новые ветки для координации работ по переводу.

Члены @kubernetes/website-milestone-maintainers могут использовать Prow-команду /milestone для контрольных точек для ишью или PR.

Настройка рабочего процесса

Затем добавьте собственную GitHub-метку для вашей локализации в репозиторий kubernetes/test-infra. Метка позволяет фильтровать ишью и пулреквесты по конкретному языку.

Смотрите пример добавления метки для итальянского языка.

Поиск сообщества

Сообщите участниками группы Kubernetes SIG Docs о вашем намерении перевода документации! Подключайтесь к Slack-каналу SIG Docs. Остальные команды по локализации с радостью помогут вам начать и ответят на любые вопросы.

Вы также можете создать Slack-канал для своей локализации в репозитории kubernetes/community. Для примера посмотрите PR с добавлением Slack-канала для индонезийского и португальского языков.

Необходимый минимум контента

Изменение конфигурации сайта

Сайт Kubernetes использует использует фреймворк Hugo. Конфигурация сайта у Hugo находится в файле hugo.toml. Для поддержки новой локализации вам нужно отредактировать файл hugo.toml.

Добавьте блок с конфигурацией для нового языка в hugo.toml после существующего блока [languages]. Например, конфигурация для немецкой локализации будет выглядить так:

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3

При выбора значения для параметра weight в блока найдите языковой блок с наибольшим значением и прибавьте к нему 1.

Для получения дополнительной информации о многоязычной поддержке в Hugo посмотрите страницу "Multilingual Mode".

Добавление директории для локализации

Добавьте директорию для вашего языка в директорию content репозитория. Например, двухбуквенный код для немецкого будет de:

mkdir content/de

Перевод норм поведения сообщества

Откройте PR в репозитории cncf/foundation и добавьте перевод норм поведения на своём языке.

Добавление перевода для файла README

Чтобы помочь другим участников локализации добавьте новый файл README-**.md в корневую директорию k/website, где ** означает двухбуквенный код языка. Например, немецкий файл README будет именоваться как README-de.md.

Подготовьте рекомендации для участников в файле для конкретной локализации README-**.md. В этом файле должна быть точно такая же информация, что и в оригинальном README.md ту же информацию, включая также:

  • Контактное лицо проекта локализации
  • Любая другая информация, относящаяся к локализации

После создания перевода файла README добавьте ссылку на файл в основной английский файл README.md и добавьте контактную информацию на английском языке. Вы можете указать логин на GitHub, адрес электронной почты, Slack-канал или какой-нибудь способ связи. Вам также нужно добавить ссылку на перевод норм поведения в сообществе.

Настройка файлов OWNERS

Для определения роли каждого пользователя, участвующего в локализации, создайте файл OWNERS в директории языка, указав в нём следующие секции:

Дополнительную информацию о файле OWNERS вы можете получить по ссылке go.k8s.io/owners.

Испанский файл OWNERS с кодом языка es выглядит следующим образом:

# See the OWNERS docs at https://go.k8s.io/owners

# This is the localization project for Spanish.
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

После добавления файла OWNERS в определенном языке нужно обновить корневой файл OWNERS_ALIASES, добавив новые команды локализации Kubernetes — sig-docs-**-owners и sig-docs-**-reviews.

Для каждой команды добавьте список GitHub-пользователей из раздела Добавление команды локализации на GitHub, перечислите их в алфавитном порядке.

--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
     - stewart-yu
     - xiangpengzhao
     - zhangxiaoyu-zidif
+  sig-docs-es-owners: # Admins for Spanish content
+    - alexbrand
+    - raelga
+  sig-docs-es-reviews: # PR reviews for Spanish content
+    - alexbrand
+    - electrocucaracha
+    - glo-pena
+    - raelga
   sig-docs-fr-owners: # Admins for French content
     - perriea
     - remyleone

Перевод контента

Локализация всей документации Kubernetes — колоссальная задача. Вполне нормально начать переводить что-то небольшое, а затем со временем делать перевод больших страниц.

Как минимум, все локализации должны включать:

ОписаниеURL-адреса
ГлавнаяВсе заголовки и подзаголовки URL-адресов
УстановкаВсе заголовки и подзаголовки URL-адресов
РуководстваОсновы Kubernetes, Привет, Minikube
Надписи на сайтеВсе надписи сайта в собственном TOML-файле

Переведенные файлы должны находиться в собственной директории content/**/, но в во всём остальном должны быть такие, как и оригинал на английском. Например, чтобы подготовить Основы Kubernetes для перевода на немецкий язык, создайте поддиректорию в директории content/de/ и скопируйте туда оригинальный английский файл:

mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md

С помощью соответствующих инструментов можно ускорить процесс перевода. Например, у некоторых редакторов есть плагины для быстрого перевода текста.

To ensure accuracy in grammar and meaning, members of your localization team should carefully review all machine-generated translations before publishing.

Исходные файлы

Локализация должна исходить из самой последней версии оригинальной документации — v1.28.

Для того, чтобы получить исходные файлы последней версии:

  1. Перейдите в репозиторий сайта Kubernetes по адресу https://github.com/kubernetes/website.
  2. Выберите ветку release-1.X самой последней версии.

Текущая последняя версия v1.28, поэтому веткой для этого релиза будет release-1.28.

Сообщения на сайте в i18n/

Локализации должны включать содержимое файла i18n/en.toml в новый языковой файл. В качестве примера рассмотрим немецкую локализацию: i18n/de.toml.

Добавьте новый файл локализации в i18n/. Например, для немецкой локализации (de):

cp i18n/en.toml i18n/de.toml

Затем переведите значение каждого сообщения:

[docs_label_i_am]
other = "ICH BIN..."

Локализация сообщений сайта позволяет изменить сообщения, используемые на всём сайте, к примеру, текст авторских прав в футере на каждой странице.

Глоссарий и руководство по оформления для языка

У некоторых языковых команд есть собственные руководства по оформлению и глоссарий. Например, посмотрите руководство корейской локализации.

Стратегия работы с ветками

Работа в проектах локализации осуществляется посредством совместных усилий, поэтому мы приветствуем решение команды работать в общих ветках разработки.

Совместная работа в рабочих ветках может быть организована следующим образом:

  1. Член команды @kubernetes/website-maintainers создает ветку из оригинальной ветки на https://github.com/kubernetes/website.

    После того, как вы добавите свою команду локализации в репозиторий kubernetes/org, ваши утверждающие из группы будет присоединены к команде @kubernetes/website-maintainers.

    Мы рекомендуем следующую схему именования веток:

    dev-<оригинальная версия>-<код языка>.<контрольная точка команды>

    Например, утверждающий в немецкой группе локализации открывает рабочую ветку dev-1.12-de.1 непосредственно в репозитории kubernetes/website из ветки для Kubernetes v1.12.

  2. Остальные участники создают новые ветки с изменениями на основе рабочей ветки.

    Например, участник немецкой группы локализации открывает пулреквест с изменениями в kubernetes:dev-1.12-de.1 из username:local-branch-name.

  3. Утверждающий проверяет изменения и объединяют ветки в рабочую веткой.

  4. Периодически утверждающий объединяет рабочую ветку в оригинальную ветку, открывая и принимая новый пулреквест. Не забудьте объединить (squash) коммиты перед слиянием пулреквеста.

Повторяйте шаги 1-4 до тех пор, пока не будет завершена локализация. Например, по мере работы над немецким переводом, рабочие ветки будут меняться: dev-1.12-de.2, dev-1.12-de.3 и т.д.

Команды должны объединять переведённый контент в ту же ветку выпуска, из которой она была создана. Например, рабочая ветка, созданная из версии release-1.28, должна сливаться с веткой версии 1.17.

Утверждающему следует поддерживать рабочую веку в актуальном состоянии в соответствии с оригинальной веткой, разрешая конфликты при слиянии. Чем дольше существует рабочая ветки, тем больше потребуется сил для ее поддержки. Поэтому лучше как можно быстрее сливать рабочую ветку и открывать новую, а не поддерживать только одну-единственную в течение длительного времени.

В начале каждой контрольной точки команды полезно открыть ишью для сравнения изменений между предыдущей веткой и текущей рабочей веткой.

Хотя только утверждающие могут открывать новую рабочую ветку и сливать пулреквесты, но любой может открыть пулреквест с новой веткой, которая может быть рабочей для команды. Никаких специальных разрешений для этого не требуется.

Для получения дополнительной информации о работе с копиями или непосредственно с оригинальным репозиторией смотрите раздел по созданию и клонированию копии репозитория.

Участие в работе над оригинальным контентом

SIG Docs приветствует участие и дополнения в английскую документацию.

Помощь для существующей локализации

Вы также можете добавлять или улучшать контент в уже существующей локализации. Обратитесь к соответствующему Slack-каналу для этого и начинайте помогать через PR.

Что дальше

Как только локализация будет соответствовать требованиям установленного рабочего процесса и содержать требуемый минимум контента, группа SIG Docs:

Изменено March 23, 2023 at 12:25 AM PST: [ru] update hugo config file (49c7340375)