Локализация документации 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 находится в файле config.toml. Для поддержки новой локализации вам нужно отредактировать файл config.toml.
Добавьте блок с конфигурацией для нового языка в config.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 в директории языка, указав в нём следующие секции:
- reviewers: список Kubernetes-команд с ролями рецензентов, в данном случае команда
sig-docs-**-reviewsбудет создана в разделе Добавление команды локализации на GitHub. - approvers: список Kubernetes-команд с ролями утверждающих, в данном случае команда
sig-docs-**-ownersбудет создана в разделе Добавление команды локализации на GitHub. - labels: список GitHub-меток, которые будут автоматически добавляться к PR, в данном случае метка языка будет создана в разделе Настройка рабочего процесса.
Дополнительную информацию о файле 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.24.
Для того, чтобы получить исходные файлы последней версии:
- Перейдите в репозиторий сайта Kubernetes по адресу https://github.com/kubernetes/website.
- Выберите ветку
release-1.Xсамой последней версии.
Текущая последняя версия v1.24, поэтому веткой для этого релиза будет release-1.24.
Сообщения на сайте в i18n/
Локализации должны включать содержимое файла i18n/en.toml в новый языковой файл. В качестве примера рассмотрим немецкую локализацию: i18n/de.toml.
Добавьте новый файл локализации в i18n/. Например, для немецкой локализации (de):
cp i18n/en.toml i18n/de.toml
Затем переведите значение каждого сообщения:
[docs_label_i_am]
other = "ICH BIN..."
Локализация сообщений сайта позволяет изменить сообщения, используемые на всём сайте, к примеру, текст авторских прав в футере на каждой странице.
Глоссарий и руководство по оформления для языка
У некоторых языковых команд есть собственные руководства по оформлению и глоссарий. Например, посмотрите руководство корейской локализации.
Стратегия работы с ветками
Работа в проектах локализации осуществляется посредством совместных усилий, поэтому мы приветствуем решение команды работать в общих ветках разработки.
Совместная работа в рабочих ветках может быть организована следующим образом:
Член команды @kubernetes/website-maintainers создает ветку из оригинальной ветки на https://github.com/kubernetes/website.
После того, как вы добавите свою команду локализации в репозиторий
kubernetes/org, ваши утверждающие из группы будет присоединены к команде@kubernetes/website-maintainers.Мы рекомендуем следующую схему именования веток:
dev-<оригинальная версия>-<код языка>.<контрольная точка команды>Например, утверждающий в немецкой группе локализации открывает рабочую ветку
dev-1.12-de.1непосредственно в репозитории kubernetes/website из ветки для Kubernetes v1.12.Остальные участники создают новые ветки с изменениями на основе рабочей ветки.
Например, участник немецкой группы локализации открывает пулреквест с изменениями в
kubernetes:dev-1.12-de.1изusername:local-branch-name.Утверждающий проверяет изменения и объединяют ветки в рабочую веткой.
Периодически утверждающий объединяет рабочую ветку в оригинальную ветку, открывая и принимая новый пулреквест. Не забудьте объединить (squash) коммиты перед слиянием пулреквеста.
Повторяйте шаги 1-4 до тех пор, пока не будет завершена локализация. Например, по мере работы над немецким переводом, рабочие ветки будут меняться: dev-1.12-de.2, dev-1.12-de.3 и т.д.
Команды должны объединять переведённый контент в ту же ветку выпуска, из которой она была создана. Например, рабочая ветка, созданная из версии release-1.24, должна сливаться с веткой версии 1.17.
Утверждающему следует поддерживать рабочую веку в актуальном состоянии в соответствии с оригинальной веткой, разрешая конфликты при слиянии. Чем дольше существует рабочая ветки, тем больше потребуется сил для ее поддержки. Поэтому лучше как можно быстрее сливать рабочую ветку и открывать новую, а не поддерживать только одну-единственную в течение длительного времени.
В начале каждой контрольной точки команды полезно открыть ишью для сравнения изменений между предыдущей веткой и текущей рабочей веткой.
Хотя только утверждающие могут открывать новую рабочую ветку и сливать пулреквесты, но любой может открыть пулреквест с новой веткой, которая может быть рабочей для команды. Никаких специальных разрешений для этого не требуется.
Для получения дополнительной информации о работе с копиями или непосредственно с оригинальным репозиторией смотрите раздел по созданию и клонированию копии репозитория.
Участие в работе над оригинальным контентом
SIG Docs приветствует участие и дополнения в английскую документацию.
Помощь для существующей локализации
Вы также можете добавлять или улучшать контент в уже существующей локализации. Обратитесь к соответствующему Slack-каналу для этого и начинайте помогать через PR.
Что дальше
Как только локализация будет соответствовать требованиям установленного рабочего процесса и содержать требуемый минимум контента, группа SIG Docs:
- Добавит язык на сайт
- Сообщит о новой локализации на каналах Cloud Native Computing Foundation (CNCF), включая блог Kubernetes.