Localization instructions

config.toml

@@ -108,8 +108,6 @@ weight = 1
 [languages.cn]
 title = "Kubernetes"
 description = "Production-Grade Container Orchestration"
-languageName ="Chinese"
+languageName = "Chinese"
 weight = 2
-contentDir = "content/cn"
-
-
+contentDir = "content/cn"

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

@@ -8,77 +8,85 @@ 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).
+In order for localizations to be accepted, however, they must fulfill some requirements related to [workflow](#workflow) (*how* to localize) and [output](#output) (*what* to localize).
 
 {{% /capture %}}
 
 {{< toc >}}
 
 {{% capture body %}}
 
-## Workflow  
+## Supported languages
 
-All l10n work must be stored and tracked within the [Kubernetes organization](https://github.com/kubernetes).
+The Kubernetes documentation is currently available in the following languages:
 
-### Basis for localizations
+{{< languages-list >}}
 
-Localizations must source from the English files for the [most recent major release](https://kubernetes.io/docs/home/supported-doc-versions/#current-version).
+## Workflow  
 
-**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.
+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).
 
-    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
+## 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)!
 
-{{< note >}}
-**Note:** To open a l10n repository, [contact the SIG docs lead](https://kubernetes.slack.com/messages/C1J0BPD2M) on Slack for assistance.
-{{< /note >}}
+We'll walk you through this whole process using the German language (language code `de`) as an example.
 
-#### Repository structure
+To get started, clone the website repo and `cd` into it:
 
-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.
+```bash
+git clone https://github.com/kubernetes/website
+cd website
+```
 
+### Source Files
 
-### Project
+Localizations must use English files from the [most recent major
+release](https://kubernetes.io/docs/home/supported-doc-versions/#current-version) as sources.
 
-Teams must track their overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/).
+To find the most recent release's documentation source files:
 
-Projects must include columns for:
-- To do
-- In progress
-- Done
+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. The branch for Kubernetes v1.9 docs, for example, is `release-1.9`.
 
-For example: the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
+### Configuration
 
-### Team function
+The website's configuration is in the [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml) file. You'll need to add a configuration block for the new language to that file, under the existing `[languages]` block. The German block, for example, could look 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, make sure to see which of the current languages has the highest weight and add 1.
 
-All l10n work must be self-sustaining with the team's own resources.
+### New directory
 
-Wherever possible, every localized page must be approved by a reviewer from a different company than the translator.
+In order to begin adding documentation for a new localization, you'll need to add a subdirectory to the [`content`](https://github.com/kubernetes/website/tree/master/content) folder. The `en` and `cn` subdirectories, for example, are for English and Chinese, respectively.
 
-### Upstream contributions
+In the configuration example [above](#configuration) the two-letter code for German is `de`. That means that a `de` directory needs to be added to the `content` directory:
 
-Upstream contributions are welcome and encouraged!
+```bash
+mkdir content/de
+```
 
-For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single squashed commit.
+## Translating documents
 
-## Output
+We understand that localizing *all* of the Kubernetes documentation would be an enormous task. We're okay with localizations smarting small and expanding later.
 
-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
 -----|-----
@@ -88,16 +96,46 @@ Tutorials | [Kubernetes Basics](https://kubernetes.io/docs/tutorials/), [Hello M
 
 {{% /capture %}}
 
-{{% capture whatsnext %}}
+## Project
 
-Once a l10n meets requirements for workflow and minimum output, SIG docs will:
+### Team function
 
-- 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.
+[Teams](#teams-function) working on localization efforts must track their 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:** Implementation of language selection is pending Kubernetes' first completed localization project.
+**Note**: For an example, see the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
 {{< /note >}}
 
+In addition, l10n teams 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.
+* Their own repository maintainers.
+
+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.
+
+### 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 whatsnext %}}
+
+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.
 
 {{% /capture %}}

layouts/shortcodes/languages-list.html

@@ -0,0 +1,10 @@
+{{- $languages := .Site.Home.AllTranslations }}
+<ul>
+    {{- range $languages.ByWeight }}
+    <li>
+        <a href="{{ .Permalink }}">
+            {{ .Language.LanguageName }}
+        </a>
+    </li>
+    {{- end }}
+</ul>