286 lines
23 KiB
Markdown
286 lines
23 KiB
Markdown
---
|
||
title: Локализация документации Kubernetes
|
||
content_type: concept
|
||
card:
|
||
name: contribute
|
||
weight: 30
|
||
title: Перевод документации
|
||
---
|
||
|
||
<!-- overview -->
|
||
|
||
На этой странице рассказывается, как [локализовать](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/) документацию на разные языки.
|
||
|
||
|
||
|
||
<!-- body -->
|
||
|
||
## Начало работы
|
||
|
||
Из-за того, что участники не могут одобрять собственные пулреквесты, нужно как минимум два участника для инициализации локализацию.
|
||
|
||
Все команды по локализации должны быть самодостаточными. Это означает, что мы с радостью разместим вашу работу, но мы не можем сделать перевод за вас.
|
||
|
||
### Определение двухбуквенного кода языка
|
||
|
||
Первым делом ознакомьтесь со [стандартом ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php), чтобы найти двухбуквенный код страны для вашей локализации. Например, двухбуквенный код для корейского языка будет `ko`.
|
||
|
||
### Создание копии репозитория
|
||
|
||
Для начала [создайте собственную копию репозитория](/ru/docs/contribute/start/#улучшение-существующего-текста) оригинального репозитория [kubernetes/website](https://github.com/kubernetes/website).
|
||
|
||
Затем клонируйте свою копию репозитория и перейдите в неё с помощью команды `cd`:
|
||
|
||
```shell
|
||
git clone https://github.com/<username>/website
|
||
cd website
|
||
```
|
||
|
||
### Создание пулреквеста
|
||
|
||
Далее [откройте пулреквест](/ru/docs/contribute/start/#отправка-пулреквеста) (PR) с локализацией в репозиторий `kubernetes/website`.
|
||
|
||
Для того, чтобы ваш пулреквест был одобрен, он должен содержать [необходимый минимум контента](#необходимый-минимум-контента).
|
||
|
||
В качестве примера добавления новой локализации, изучите PR, который добавляет [документацию на французском](https://github.com/kubernetes/website/pull/12548).
|
||
|
||
### Вступление в GitHub-организацию Kubernetes
|
||
|
||
Как только, как вы открыли PR с локализацией, вы можете стать членом организации Kubernetes на GitHub. Каждый член команды должен подать [запрос на членство в организации](https://github.com/kubernetes/org/issues/new/choose) в репозитории `kubernetes/org`.
|
||
|
||
### Добавление команды локализации на GitHub
|
||
|
||
Теперь нужно добавить вашу команду локализации Kubernetes в файл [`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml). Для примера добавления команды локализации можете посмотреть PR, добавляющий [испанскую команду локализации](https://github.com/kubernetes/org/pull/685).
|
||
|
||
Члены `@kubernetes/sig-docs-**-owners` — могут одобрять PR, которые изменяют файлы внутри (и только там) директории с локализацией: `/content/**/`.
|
||
|
||
Для каждой локализации группа `@kubernetes/sig-docs-**-reviews` служит для автоматизации выбора проверяющих новых PR.
|
||
|
||
Члены `@kubernetes/website-maintainers` могут создавать новые ветки для координации работ по переводу.
|
||
|
||
Члены `@kubernetes/website-milestone-maintainers` могут использовать [Prow-команду](https://prow.k8s.io/command-help) `/milestone` для контрольных точек для ишью или PR.
|
||
|
||
### Настройка рабочего процесса
|
||
|
||
Затем добавьте собственную GitHub-метку для вашей локализации в репозиторий `kubernetes/test-infra`. Метка позволяет фильтровать ишью и пулреквесты по конкретному языку.
|
||
|
||
Смотрите пример добавления [метки для итальянского языка](https://github.com/kubernetes/test-infra/pull/11316).
|
||
|
||
### Поиск сообщества
|
||
|
||
Сообщите участниками группы Kubernetes SIG Docs о вашем намерении перевода документации! Подключайтесь к [Slack-каналу SIG Docs](https://kubernetes.slack.com/messages/C1J0BPD2M/). Остальные команды по локализации с радостью помогут вам начать и ответят на любые вопросы.
|
||
|
||
Вы также можете создать Slack-канал для своей локализации в репозитории `kubernetes/community`. Для примера посмотрите PR с [добавлением Slack-канала для индонезийского и португальского языков](https://github.com/kubernetes/community/pull/3605).
|
||
|
||
## Необходимый минимум контента
|
||
|
||
### Изменение конфигурации сайта
|
||
|
||
Сайт Kubernetes использует использует фреймворк Hugo. Конфигурация сайта у Hugo находится в файле [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml). Для поддержки новой локализации вам нужно отредактировать файл `config.toml`.
|
||
|
||
Добавьте блок с конфигурацией для нового языка в `config.toml` после существующего блока `[languages]`. Например, конфигурация для немецкой локализации будет выглядить так:
|
||
|
||
```toml
|
||
[languages.de]
|
||
title = "Kubernetes"
|
||
description = "Produktionsreife Container-Verwaltung"
|
||
languageName = "Deutsch"
|
||
contentDir = "content/de"
|
||
weight = 3
|
||
```
|
||
|
||
При выбора значения для параметра `weight` в блока найдите языковой блок с наибольшим значением и прибавьте к нему 1.
|
||
|
||
Для получения дополнительной информации о многоязычной поддержке в Hugo посмотрите страницу "[Multilingual Mode](https://gohugo.io/content-management/multilingual/)".
|
||
|
||
### Добавление директории для локализации
|
||
|
||
Добавьте директорию для вашего языка в директорию [`content`](https://github.com/kubernetes/website/tree/master/content) репозитория. Например, двухбуквенный код для немецкого будет `de`:
|
||
|
||
```shell
|
||
mkdir content/de
|
||
```
|
||
|
||
### Перевод норм поведения сообщества
|
||
|
||
Откройте PR в репозитории [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) и добавьте перевод норм поведения на своём языке.
|
||
|
||
### Добавление перевода для файла README
|
||
|
||
Чтобы помочь другим участников локализации добавьте новый файл [`README-**.md`](https://help.github.com/articles/about-readmes/) в корневую директорию k/website, где `**` означает двухбуквенный код языка. Например, немецкий файл README будет именоваться как `README-de.md`.
|
||
|
||
Подготовьте рекомендации для участников в файле для конкретной локализации `README-**.md`. В этом файле должна быть точно такая же информация, что и в оригинальном README.md ту же информацию, включая также:
|
||
|
||
- Контактное лицо проекта локализации
|
||
- Любая другая информация, относящаяся к локализации
|
||
|
||
После создания перевода файла README добавьте ссылку на файл в основной английский файл `README.md` и добавьте контактную информацию на английском языке. Вы можете указать логин на GitHub, адрес электронной почты, Slack-канал или какой-нибудь способ связи. Вам также нужно добавить ссылку на перевод норм поведения в сообществе.
|
||
|
||
### Настройка файлов OWNERS
|
||
|
||
Для определения роли каждого пользователя, участвующего в локализации, создайте файл `OWNERS` в директории языка, указав в нём следующие секции:
|
||
|
||
- **reviewers**: список Kubernetes-команд с ролями рецензентов, в данном случае команда `sig-docs-**-reviews` будет создана в разделе [Добавление команды локализации на GitHub](#добавление-команды-локализации-на-github).
|
||
- **approvers**: список Kubernetes-команд с ролями утверждающих, в данном случае команда `sig-docs-**-owners` будет создана в разделе [Добавление команды локализации на GitHub](#добавление-команды-локализации-на-github).
|
||
- **labels**: список GitHub-меток, которые будут автоматически добавляться к PR, в данном случае метка языка будет создана в разделе [Настройка рабочего процесса](#настройка-рабочего-процесса).
|
||
|
||
Дополнительную информацию о файле `OWNERS` вы можете получить по ссылке [go.k8s.io/owners](https://go.k8s.io/owners).
|
||
|
||
[Испанский файл OWNERS](https://git.k8s.io/website/content/es/OWNERS) с кодом языка `es` выглядит следующим образом:
|
||
|
||
```yaml
|
||
# 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`](https://git.k8s.io/website/OWNERS_ALIASES), добавив новые команды локализации Kubernetes — `sig-docs-**-owners` и `sig-docs-**-reviews`.
|
||
|
||
Для каждой команды добавьте список GitHub-пользователей из раздела [Добавление команды локализации на GitHub](#добавление-команды-локализации-на-github), перечислите их в алфавитном порядке.
|
||
|
||
```diff
|
||
--- 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-адресов](/ru/docs/home/)
|
||
Установка | [Все заголовки и подзаголовки URL-адресов](/ru/docs/setup/)
|
||
Руководства | [Основы Kubernetes](/ru/docs/tutorials/kubernetes-basics/), [Привет, Minikube](/ru/docs/tutorials/stateless-application/hello-minikube/)
|
||
Надписи на сайте | [Все надписи сайта в собственном TOML-файле](https://github.com/kubernetes/website/tree/master/i18n)
|
||
|
||
Переведенные файлы должны находиться в собственной директории `content/**/`, но в во всём остальном должны быть такие, как и оригинал на английском. Например, чтобы подготовить [Основы Kubernetes](/ru/docs/tutorials/kubernetes-basics/) для перевода на немецкий язык, создайте поддиректорию в директории `content/de/` и скопируйте туда оригинальный английский файл:
|
||
|
||
```shell
|
||
mkdir -p content/de/docs/tutorials
|
||
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
|
||
```
|
||
|
||
С помощью соответствующих инструментов можно ускорить процесс перевода. Например, у некоторых редакторов есть плагины для быстрого перевода текста.
|
||
|
||
{{< caution >}}
|
||
Использование только машинного перевода не будет соответствовать минимальному уровню качества и поэтому такой перевод требует тщательного ручного рассмотрения для соблюдения стандарта качества.
|
||
{{< /caution >}}
|
||
|
||
To ensure accuracy in grammar and meaning, members of your localization team should carefully review all machine-generated translations before publishing.
|
||
|
||
### Исходные файлы
|
||
|
||
Локализация должна исходить из самой последней версии оригинальной документации — {{< latest-version >}}.
|
||
|
||
Для того, чтобы получить исходные файлы последней версии:
|
||
|
||
1. Перейдите в репозиторий сайта Kubernetes по адресу https://github.com/kubernetes/website.
|
||
2. Выберите ветку `release-1.X` самой последней версии.
|
||
|
||
Текущая последняя версия {{< latest-version >}}, поэтому веткой для этого релиза будет [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}}).
|
||
|
||
### Сообщения на сайте в i18n/
|
||
|
||
Локализации должны включать содержимое файла [`i18n/en.toml`](https://github.com/kubernetes/website/blob/main/i18n/en.toml) в новый языковой файл. В качестве примера рассмотрим немецкую локализацию: `i18n/de.toml`.
|
||
|
||
Добавьте новый файл локализации в `i18n/`. Например, для немецкой локализации (`de`):
|
||
|
||
```shell
|
||
cp i18n/en.toml i18n/de.toml
|
||
```
|
||
|
||
Затем переведите значение каждого сообщения:
|
||
|
||
```TOML
|
||
[docs_label_i_am]
|
||
other = "ICH BIN..."
|
||
```
|
||
|
||
Локализация сообщений сайта позволяет изменить сообщения, используемые на всём сайте, к примеру, текст авторских прав в футере на каждой странице.
|
||
|
||
### Глоссарий и руководство по оформления для языка
|
||
|
||
У некоторых языковых команд есть собственные руководства по оформлению и глоссарий. Например, посмотрите [руководство корейской локализации](/ko/docs/contribute/localization_ko/).
|
||
|
||
## Стратегия работы с ветками
|
||
|
||
Работа в проектах локализации осуществляется посредством совместных усилий, поэтому мы приветствуем решение команды работать в общих ветках разработки.
|
||
|
||
Совместная работа в рабочих ветках может быть организована следующим образом:
|
||
|
||
1. Член команды [@kubernetes/website-maintainers](https://github.com/orgs/kubernetes/teams/website-maintainers) создает ветку из оригинальной ветки на https://github.com/kubernetes/website.
|
||
|
||
После того, как вы [добавите свою команду локализации](#добавление-команды-локализации-на-github) в репозиторий [`kubernetes/org`](https://github.com/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-branch >}}, должна сливаться с веткой версии 1.17.
|
||
|
||
Утверждающему следует поддерживать рабочую веку в актуальном состоянии в соответствии с оригинальной веткой, разрешая конфликты при слиянии. Чем дольше существует рабочая ветки, тем больше потребуется сил для ее поддержки. Поэтому лучше как можно быстрее сливать рабочую ветку и открывать новую, а не поддерживать только одну-единственную в течение длительного времени.
|
||
|
||
В начале каждой контрольной точки команды полезно открыть ишью для сравнения изменений между предыдущей веткой и текущей рабочей веткой.
|
||
|
||
Хотя только утверждающие могут открывать новую рабочую ветку и сливать пулреквесты, но любой может открыть пулреквест с новой веткой, которая может быть рабочей для команды. Никаких специальных разрешений для этого не требуется.
|
||
|
||
Для получения дополнительной информации о работе с копиями или непосредственно с оригинальным репозиторией смотрите раздел по [созданию и клонированию копии репозитория](#создание-копии-репозитория).
|
||
|
||
## Участие в работе над оригинальным контентом
|
||
|
||
SIG Docs приветствует [участие и дополнения](/ru/docs/contribute/intermediate#локализация-контента) в английскую документацию.
|
||
|
||
## Помощь для существующей локализации
|
||
|
||
Вы также можете добавлять или улучшать контент в уже существующей локализации. Обратитесь к соответствующему [Slack-каналу](https://kubernetes.slack.com/messages/C1J0BPD2M/) для этого и начинайте помогать через PR.
|
||
|
||
|
||
|
||
## {{% heading "whatsnext" %}}
|
||
|
||
|
||
Как только локализация будет соответствовать требованиям установленного рабочего процесса и содержать требуемый минимум контента, группа SIG Docs:
|
||
|
||
- Добавит язык на сайт
|
||
- Сообщит о новой локализации на каналах [Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF), включая [блог Kubernetes](https://kubernetes.io/blog/).
|