Localization instructions (#9192)

* Begin re-working localization instructions * Fix dangling sentence * Re-arrange sections plus new content * Fix TOC issue with misplaced capture directive * Create new shortcodes for versions and language repos * Add more translation instructions * Remove translation docs added as an example * Finish draft of localization doc * Remove extraneous note
kubernetes · Jul 28, 2018 · 1778e77 · 1778e77
1 parent c36098d
commit 1778e77
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 47 deletions.
diff --git 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
@@ -8,83 +8,134 @@ 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  
-
-All l10n work must be stored and tracked within the [Kubernetes organization](https://github.com/kubernetes).
+## Workflow
 
-### Basis for localizations
+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).
 
-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
@@ -0,0 +1,2 @@
+en: kubernetes/website
+cn: kubernetes/kubernetes-docs-zh
diff --git a/layouts/shortcodes/language-repos-list.html b/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>
diff --git a/layouts/shortcodes/latest-version.html b/layouts/shortcodes/latest-version.html
@@ -0,0 +1 @@
+{{ .Site.Params.latest }}
diff --git a/layouts/shortcodes/release-branch.html b/layouts/shortcodes/release-branch.html
@@ -0,0 +1,3 @@
+{{- $latestVersion := .Site.Params.latest }}
+{{- $latestReleaseBranch := printf "release-%s" (replace $latestVersion "v" "") }}
+{{- $latestReleaseBranch }}