diff --git a/config.toml b/config.toml index b9166c1ddd..ddbe5f8a78 100644 --- a/config.toml +++ b/config.toml @@ -131,7 +131,7 @@ weight = 1 [languages.cn] title = "Kubernetes" description = "Production-Grade Container Orchestration" -languageName ="Chinese" +languageName = "Chinese" weight = 2 contentDir = "content/cn" diff --git a/content/en/docs/home/contribute/localization.md b/content/en/docs/home/contribute/localization.md index 01a9bad5e7..2f8c870d0d 100644 --- a/content/en/docs/home/contribute/localization.md +++ b/content/en/docs/home/contribute/localization.md @@ -8,9 +8,13 @@ approvers: {{% capture overview %}} -We're happy to add localizations (l10n) of Kubernetes documentation to the website! +The Kubernetes documentation is currently available in [multiple languages](#supported-languages) and we encourage you to add new localizations ([l10n](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/))! -Localizations must meet the following requirements for _workflow_ (how to localize) and _output_ (what to localize). +Currently available languages: + +{{< language-repos-list >}} + +In order for localizations to be accepted, however, they must fulfill some requirements related to workflow (*how* to localize) and output (*what* to localize). {{% /capture %}} @@ -18,73 +22,120 @@ Localizations must meet the following requirements for _workflow_ (how to locali {{% capture body %}} -## Workflow +## Workflow -All l10n work must be stored and tracked within the [Kubernetes organization](https://github.com/kubernetes). +The Kubernetes documentation for all languages is built from the [kubernetes/website](https://github.com/kubernetes/website) repository on GitHub. Most day-to-work work on translations, however, happens in separate translation repositories. Changes to those repositories are then [periodically](#upstream-contributions) synced to the main kubernetes/website repository via [pull request](../create-pull-request). -### Basis for localizations - -Localizations must source from the English files for the [most recent major release](https://kubernetes.io/docs/home/supported-doc-versions/#current-version). - -**Note:** To find the most recent release's documentation source files: -1. Navigate to https://github.com/kubernetes/website. -2. Select the `release-1.X` branch for the most recent version. - - For example, the branch for Kubernetes v1.9 docs is `release-1.9`. +Work on the Chinese translation, for example, happens in the [kubernetes/kubernetes-docs-zh](https://github.com/kubernetes/kubernetes-docs-zh) repository. {{< note >}} -Source files reside in the `/docs/` directory. +**Note**: For an example localization-related [pull request](../create-pull-request), see [this pull request](https://github.com/kubernetes/website/pull/8636) to the [Kubernetes website repo](https://github.com/kubernetes/website) adding Korean localization to the Kubernetes docs. {{< /note >}} -### Repository +## Source Files -A l10n team will have a repository specifically dedicated to its work, for example: [kubernetes/kubernetes-docs-zh](https://github.com/kubernetes/kubernetes-docs-zh). +Localizations must use English files from the most recent major release as sources. To find the most recent release's documentation source files: -{{< note >}} -**Note:** To open a l10n repository, [contact the SIG docs lead](https://kubernetes.slack.com/messages/C1J0BPD2M) on Slack for assistance. -{{< /note >}} +1. Navigate to the Kubernetes website repository at https://github.com/kubernetes/website. +2. Select the `release-1.X` branch for the most recent version, which is currently **{{< latest-version >}}**, making the most recent release branch [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}}). -#### Repository structure +## Getting started -Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main [kubernetes/website](https://github.com/kubernetes/website) documentation repository. For example, the kubernetes/website `release-1.10` branch (https://github.com/kubernetes/website/tree/release-1.10) has a corresponding branch in the kubernetes/kubernetes-docs-zh repository (https://github.com/kubernetes/kubernetes-docs-zh/tree/release-1.10). These version branches keep track of the differences in the documentation between Kubernetes versions. +In order to add a new localization of the Kubernetes documentation, you'll need to make a few modifications to the site's [configuration](#configuration) and [directory structure](#new-directory), and then you can get to work [translating documents](#translating-documents)! +To get started, clone the website repo and `cd` into it: -### Project +```shell +git clone https://github.com/kubernetes/website +cd website +git checkout {{< release-branch >}} +``` -Teams must track their overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/). +## Configuration -Projects must include columns for: -- To do -- In progress -- Done +We'll walk you through the configuration process using the German language (language code `de`) as an example. -For example: the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1). +There's currently no translation for German, but you're welcome to create one using the instructions here. -### Team function +The Kubernetes website's configuration is in the [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml) file. You need to add a configuration block for the new language to that file, under the existing `[languages]` block. The German block, for example, looks like this: -L10n teams must provide a single point of contact: the name and contact information of a person who can respond to or redirect questions or concerns. +```toml +[languages.de] +title = "Kubernetes" +description = "Produktionsreife Container-Verwaltung" +languageName = "Deutsch" +contentDir = "content/de" +weight = 3 +``` -L10n teams must provide their own repository maintainers. +When assigning a `weight` parameter, see which of the current languages has the highest weight and add 1 to that value. -All l10n work must be self-sustaining with the team's own resources. +Now add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/master/content) folder. The two-letter code for German is `de`, so add a `content/de` directory: -Wherever possible, every localized page must be approved by a reviewer from a different company than the translator. +```shell +mkdir content/de +``` -### Upstream contributions +## Translating documents -Upstream contributions are welcome and encouraged! +We understand that localizing *all* of the Kubernetes documentation would be an enormous task. We're okay with localizations smarting small and expanding over time. -For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single squashed commit. - -## Output - -All localizations must include the following documentation at a minimum: +As an initial requirement, all localizations must include the following documentation at a minimum: Description | URLs -----|----- Home | [All heading and subheading URLs](https://kubernetes.io/docs/home/) Setup | [All heading and subheading URLs](https://kubernetes.io/docs/setup/) -Tutorials | [Kubernetes Basics](https://kubernetes.io/docs/tutorials/), [Hello Minikube](https://kubernetes.io/docs/tutorials/stateless-application/hello-minikube/) +Tutorials | [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/), [Hello Minikube](https://kubernetes.io/docs/tutorials/stateless-application/hello-minikube/) + +Translated documents should have the same URL endpoint as the English docs (substituting the subdirectory of the `content` folder). To translate the [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/) doc into German, for example, create the proper subfolder under the `content/de` folder and copy the English doc: + +```shell +mkdir -p content/de/docs/tutorials +cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md +``` + +## Project logistics + +### Contact with project chairs + +When starting a new localization effort, you should get in touch with one of the chairs of the Kubernetes [SIG Docs](https://github.com/kubernetes/community/tree/master/sig-docs) organization. The current chairs are listed [here](https://github.com/kubernetes/community/tree/master/sig-docs#chairs). + +### Project information + +Teams working on localization efforts must provide a single point of contact, including the name and contact information of a person who can respond to or redirect questions or concerns, listed in the translation repository's main [`README`](https://help.github.com/articles/about-readmes/). You can provide an email address, email list, [Slack channel](https://slack.com/), or some other method of contact. + +### Maintainers + +Each localization repository must select its own maintainers. Maintainers can be from a single organization or multiple organizations. + +In addition, all l10n work must be self-sustaining with the team's own resources. + +Wherever possible, every localized page must be approved by a reviewer from a different company than the translator. + +### GitHub project + +Each Kubernetes localization repository must track its overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/). + +Projects must include at least these columns: + +- To Do +- In Progress +- Done + +{{< note >}} +**Note**: For an example GitHub project, see the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1). +{{< /note >}} + +### Repository structure + +Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main [kubernetes/website](https://github.com/kubernetes/website) documentation repository. For example, the kubernetes/website `release-1.10` branch (https://github.com/kubernetes/website/tree/release-1.10) has a corresponding branch in the kubernetes/kubernetes-docs-zh repository (https://github.com/kubernetes/kubernetes-docs-zh/tree/release-1.10). These version branches keep track of the differences in the documentation between Kubernetes versions. + +### Upstream contributions + +Upstream contributions are welcome and encouraged! + +For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single [squashed commit](https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit). {{% /capture %}} @@ -95,9 +146,4 @@ Once a l10n meets requirements for workflow and minimum output, SIG docs will: - Work with the localization team to implement language selection on the website. - Publicize availability through [Cloud Native Computing Foundation](https://www.cncf.io/) (CNCF) channels. -{{< note >}} -**Note:** Implementation of language selection is pending Kubernetes' first completed localization project. -{{< /note >}} - - {{% /capture %}} diff --git a/data/repos.yml b/data/repos.yml new file mode 100644 index 0000000000..21e7eb3e04 --- /dev/null +++ b/data/repos.yml @@ -0,0 +1,2 @@ +en: kubernetes/website +cn: kubernetes/kubernetes-docs-zh \ No newline at end of file diff --git a/layouts/shortcodes/language-repos-list.html b/layouts/shortcodes/language-repos-list.html new file mode 100644 index 0000000000..293efa1ffc --- /dev/null +++ b/layouts/shortcodes/language-repos-list.html @@ -0,0 +1,38 @@ +{{- $languages := .Site.Home.AllTranslations }} +
+ Language + | ++ Language code + | ++ Repository + | +
---|---|---|
+ + {{ $name }} + + | +
+ {{ $code }}
+ |
+ + + {{ $repo }} + + | +