Localization instructions

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"
 

content/en/docs/home/contribute/localization.md

@@ -8,83 +8,136 @@ 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 %}}
 
 {{< toc >}}
 
 {{% 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
+Work on the Chinese translation, for example, happens in the [kubernetes/kubernetes-docs-zh](https://github.com/kubernetes/kubernetes-docs-zh) repository.
 
-Localizations must source from the English files for the [most recent major release](https://kubernetes.io/docs/home/supported-doc-versions/#current-version).
+{{< note >}}
+**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 >}}
 
-**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.
+## Source Files
 
-    For example, the branch for Kubernetes v1.9 docs is `release-1.9`.
+Localizations must use English files from the most recent major release as sources. To find the most recent release's documentation source files:
 
-{{< note >}}
-Source files reside in the `/docs/` directory.
-{{< /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
+## Getting started
 
-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).
+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:
+
+```shell
+git clone https://github.com/kubernetes/website
+cd website
+git checkout {{< release-branch >}}
+```
 
 {{< note >}}
-**Note:** To open a l10n repository, [contact the SIG docs lead](https://kubernetes.slack.com/messages/C1J0BPD2M) on Slack for assistance.
+**Note**: There is currently no German translation of the Kubernetes documentation, but you're welcome to create one using the instructions outlined here!
 {{< /note >}}
 
-#### Repository structure
+## Configuration
 
-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.
+We'll walk you through the configuration process using the German language (language code `de`) as an example. There's currently no translation for German, but you're welcome to create one using the instructions here.
 
+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:
 
-### Project
+```toml
+[languages.de]
+title = "Kubernetes"
+description = "Produktionsreife Container-Verwaltung"
+languageName = "Deutsch"
+contentDir = "content/de"
+weight = 3
+```
 
-Teams must track their overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/).
+When assigning a `weight` parameter, see which of the current languages has the highest weight and add 1 to that value.
 
-Projects must include columns for:
-- To do
-- In progress
-- Done
+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:
+
+```shell
+mkdir content/de
+```
+
+## Translating documents
+
+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.
+
+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/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
 
-For example: the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
+### Contact with project chairs
 
-### Team function
+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).
 
-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.
+### Project information
 
-L10n teams must provide their own repository maintainers.
+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.
 
-All l10n work must be self-sustaining with the team's own resources.
+### 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.
 
-### Upstream contributions
+### GitHub project
 
-Upstream contributions are welcome and encouraged!
+Each Kubernetes localization repository must track its overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/).
 
-For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single squashed commit.
+Projects must include at least these columns:
 
-## Output
+- To Do
+- In Progress
+- Done
 
-All localizations must include the following documentation at a minimum:
+{{< note >}}
+**Note**: For an example GitHub project, see the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
+{{< /note >}}
 
-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/)
+### 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 +148,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 %}}

data/repos.yml

@@ -0,0 +1,2 @@
+en: kubernetes/website
+cn: kubernetes/kubernetes-docs-zh

layouts/shortcodes/language-repos-list.html

@@ -0,0 +1,38 @@
+{{- $languages := .Site.Home.AllTranslations }}
+<table>
+    <thead>
+        <tr>
+            <th>
+                Language
+            </th>
+            <th>
+                Language code
+            </th>
+            <th>
+                Repository
+            </th>
+        </tr>
+    </thead>
+    <tbody>
+        {{- range $languages.ByWeight }}
+        {{- $name := .Language.LanguageName }}
+        {{- $code := string .Language }}
+        {{- $repo := printf "https://github.com/%s" (index .Site.Data.repos $code) }}
+        <tr>
+            <td>
+                <a href="{{ .Permalink }}">
+                    {{ $name }}
+                </a>
+            </td>
+            <td>
+                <code>{{ $code }}</code>
+            </td>
+            <td>
+                <a href="{{ $repo }}">
+                    {{ $repo }}
+                </a>
+            </td>
+        </tr>
+        {{- end }}
+    </tbody>
+</table>

layouts/shortcodes/latest-version.html

@@ -0,0 +1 @@
+{{ .Site.Params.latest }}

layouts/shortcodes/release-branch.html

@@ -0,0 +1,3 @@
+{{- $latestVersion := .Site.Params.latest }}
+{{- $latestReleaseBranch := printf "release-%s" (replace $latestVersion "v" "") }}
+{{- $latestReleaseBranch }}