Merge pull request #27408 from sftim/20210405_allow_localizations_maintain_own_strings

Allow localization teams to review their own strings

Author: k8s-ci-robot

content/en/docs/contribute/localization.md

@@ -16,18 +16,21 @@ card:
 This page shows you how to [localize](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/) the docs for a different language.
 
 
-
 <!-- body -->
 
-## Getting started
+## Contribute to an existing localization
 
-Because contributors can't approve their own pull requests, you need at least two contributors to begin a localization.
+You can help add or improve content to an existing localization. In [Kubernetes Slack](https://slack.k8s.io/) you'll find a channel for each localization. There is also a general [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations) where you can say hello.
 
-All localization teams must be self-sustaining with their own resources. The Kubernetes website is happy to host your work, but it's up to you to translate it.
+{{< note >}}
+If you want to work on a localization that already exists, check
+this page in that localization (if it exists), rather than the
+English original. You might see extra details there.
+{{< /note >}}
 
 ### Find your two-letter language code
 
-First, consult the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) to find your localization's two-letter country code. For example, the two-letter code for Korean is `ko`.
+First, consult the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) to find your localization's two-letter language code. For example, the two-letter code for Korean is `ko`.
 
 ### Fork and clone the repo
 
@@ -40,13 +43,54 @@ git clone https://github.com/<username>/website
 cd website
 ```
 
-### Open a pull request
+The website content directory includes sub-directories for each language. The localization you want to help out with is inside `content/<two-letter-code>`.
 
-Next, [open a pull request](/docs/contribute/new-content/open-a-pr/#open-a-pr) (PR) to add a localization to the `kubernetes/website` repository.
+### Suggest changes
 
-The PR must include all of the [minimum required content](#minimum-required-content) before it can be approved.
+Create or update your chosen localized page based on the English original. See
+[translating content](#translating-content) for more details.
 
-For an example of adding a new localization, see the PR to enable [docs in French](https://github.com/kubernetes/website/pull/12548).
+If you notice a technical inaccuracy or other problem with the upstream (English)
+documentation, you should fix the upstream documentation first and then repeat the
+equivalent fix by updating the localization you're working on.
+
+Please limit pull requests to a single localization, since pull requests that change
+content in multiple localizations could be difficult to review.
+
+Follow [Suggesting Content Improvements](/docs/contribute/suggest-improvements/) to propose changes to
+that localization. The process is very similar to proposing changes to the upstream (English) content.
+
+## Start a new localization
+
+If you want the Kubernetes documentation localized into a new language, here's what
+you need to do.
+
+Because contributors can't approve their own pull requests, you need _at least two contributors_
+to begin a localization.
+
+All localization teams must be self-sustaining. The Kubernetes website is happy to host your work, but
+it's up to you to translate it and keep existing localized content current.
+
+You'll need to know the two-letter language code for your language. Consult the
+[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) to find your
+localization's two-letter language code. For example, the two-letter code for Korean is
+`ko`.
+
+When you start a new localization, you must localize all the
+[minimum required content](#minimum-required-content) before
+the Kubernetes project can publish your changes to the live
+website.
+
+SIG Docs can help you work on a separate branch so that you
+can incrementally work towards that goal.
+
+### Find community
+
+Let Kubernetes SIG Docs know you're interested in creating a localization! Join the [SIG Docs Slack channel](https://kubernetes.slack.com/messages/sig-docs) and the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations). Other localization teams are happy to help you get started and answer any questions you have.
+
+Please also consider participating in the [SIG Docs Localization Subgroup meeting](https://github.com/kubernetes/community/tree/master/sig-docs).  The mission of the SIG Docs localization subgroup is to work across the SIG Docs localization teams to collaborate on defining and documenting the processes for creating localized contribution guides. In addition, the SIG Docs localization subgroup will look for opportunities for the creation and sharing of common tools across localization teams and also serve to identify new requirements to the SIG Docs Leadership team.  If you have questions about this meeting, please inquire on the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations).
+
+You can also create a Slack channel for your localization in the `kubernetes/community` repository. For an example of adding a Slack channel, see the PR for [adding a channel for Persian](https://github.com/kubernetes/community/pull/4980).
 
 ### Join the Kubernetes GitHub organization
 
@@ -70,15 +114,6 @@ Next, add a GitHub label for your localization in the `kubernetes/test-infra` re
 
 For an example of adding a label, see the PR for adding the [Italian language label](https://github.com/kubernetes/test-infra/pull/11316).
 
-### Find community
-
-Let Kubernetes SIG Docs know you're interested in creating a localization! Join the [SIG Docs Slack channel](https://kubernetes.slack.com/messages/sig-docs) and the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations). Other localization teams are happy to help you get started and answer any questions you have.
-
-Please also consider participating in the [SIG Docs Localization Subgroup meeting](https://github.com/kubernetes/community/tree/master/sig-docs).  The mission of the SIG Docs localization subgroup is to work across the SIG Docs localization teams to collaborate on defining and documenting the processes for creating localized contribution guides. In addition, the SIG Docs localization subgroup will look for opportunities for the creation and sharing of common tools across localization teams and also serve to identify new requirements to the SIG Docs Leadership team.  If you have questions about this meeting, please inquire on the [SIG Docs Localizations Slack channel](https://kubernetes.slack.com/messages/sig-docs-localizations).
-
-You can also create a Slack channel for your localization in the `kubernetes/community` repository. For an example of adding a Slack channel, see the PR for [adding a channel for Persian](https://github.com/kubernetes/community/pull/4980).
-
-## Minimum required content
 
 ### Modify the site configuration
 
@@ -107,20 +142,20 @@ Add a language-specific subdirectory to the [`content`](https://github.com/kuber
 mkdir content/de
 ```
 
-### Localize the community code of conduct
-
-Open a PR against the [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) repository to add the code of conduct in your language.
-
-### Add a localized README file
+You also need to create a directory inside `data/i18n` for
+[localized strings](#site-strings-in-i18n); look at existing localizations
+for an example. To use these new strings, you must also create a symbolic link
+from `i18n/<localization>.toml` to the actual string configuration in
+`data/i18n/<localization>/<localization>.toml` (remember to commit the symbolic
+link).
 
-To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of k/website, where `**` is the two-letter language code. For example, a German README file would be `README-de.md`.
+For example, for German the strings live in `data/i18n/de/de.toml`, and
+`i18n/de.toml` is a symbolic link to `data/i18n/de/de.toml`.
 
-Provide guidance to localization contributors in the localized `README-**.md` file. Include the same information contained in `README.md` as well as:
+### Localize the community code of conduct
 
-- A point of contact for the localization project
-- Any information specific to the localization
+Open a PR against the [`cncf/foundation`](https://github.com/cncf/foundation/tree/master/code-of-conduct-languages) repository to add the code of conduct in your language.
 
-After you create the localized README, add a link to the file from the main English `README.md`, and include contact information in English. You can provide a GitHub ID, email address, [Slack channel](https://slack.com/), or other method of contact. You must also provide a link to your localized Community Code of Conduct.
 
 ### Setting up the OWNERS files
 
@@ -174,18 +209,46 @@ For each team, add the list of GitHub users requested in [Add your localization
      - remyleone
 ```
 
+### Open a pull request
+
+Next, [open a pull request](/docs/contribute/new-content/open-a-pr/#open-a-pr) (PR) to add a localization to the `kubernetes/website` repository.
+
+The PR must include all of the [minimum required content](#minimum-required-content) before it can be approved.
+
+For an example of adding a new localization, see the PR to enable [docs in French](https://github.com/kubernetes/website/pull/12548).
+
+### Add a localized README file
+
+To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of k/website, where `**` is the two-letter language code. For example, a German README file would be `README-de.md`.
+
+Provide guidance to localization contributors in the localized `README-**.md` file. Include the same information contained in `README.md` as well as:
+
+- A point of contact for the localization project
+- Any information specific to the localization
+
+After you create the localized README, add a link to the file from the main English `README.md`, and include contact information in English. You can provide a GitHub ID, email address, [Slack channel](https://slack.com/), or other method of contact. You must also provide a link to your localized Community Code of Conduct.
+
+### Launching your new localization
+
+Once a localization meets requirements for workflow and minimum output, SIG Docs will:
+
+- Enable language selection on the website
+- Publicize the localization's availability through [Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) channels, including the [Kubernetes blog](https://kubernetes.io/blog/).
+
 ## Translating content
 
 Localizing *all* of the Kubernetes documentation is an enormous task. It's okay to start small and expand over time.
 
+### Minimum required content
+
 At a minimum, all localizations must include:
 
 Description | URLs
 -----|-----
 Home | [All heading and subheading URLs](/docs/home/)
 Setup | [All heading and subheading URLs](/docs/setup/)
 Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/hello-minikube/)
-Site strings | [All site strings in a new localized TOML file](https://github.com/kubernetes/website/tree/master/i18n)
+Site strings | [All site strings](#Site-strings-in-i18n) in a new localized TOML file
 
 Translated documents must reside in their own `content/**/` subdirectory, but otherwise follow the same URL path as the English source. For example, to prepare the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) tutorial for translation into German, create a subfolder under the `content/de/` folder and copy the English source:
 
@@ -213,27 +276,30 @@ To find source files for your target version:
 2. Select a branch for your target version from the following table:
     Target version | Branch
     -----|-----
-    Next version | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
     Latest version | [`master`](https://github.com/kubernetes/website/tree/master)
-    Previous version | `release-*.**`
+    Previous version | [`release-{{< skew prevMinorVersion >}}`](https://github.com/kubernetes/website/tree/release-{{< skew prevMinorVersion >}})
+    Next version | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})
 
-The `master` branch holds content for the current release `{{< latest-version >}}`. The release team will create `{{< release-branch >}}` branch shortly before the next release: v{{< skew nextMinorVersion >}}.
+The `master` branch holds content for the current release `{{< latest-version >}}`. The release team will create a `{{< release-branch >}}` branch before the next release: v{{< skew nextMinorVersion >}}.
 
 ### Site strings in i18n
 
-Localizations must include the contents of [`i18n/en.toml`](https://github.com/kubernetes/website/blob/master/i18n/en.toml) in a new language-specific file. Using German as an example: `i18n/de.toml`.
+Localizations must include the contents of [`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/master/data/i18n/en/en.toml) in a new language-specific file. Using German as an example: `data/i18n/de/de.toml`.
 
-Add a new localization file to `i18n/`. For example, with German (`de`):
+Add a new localization directory and file to `data/i18n/`. For example, with German (`de`):
 
-```shell
-cp i18n/en.toml i18n/de.toml
+```bash
+mkdir -p data/i18n/de
+cp data/i18n/en/en.toml data/i18n/de/de.toml
 ```
 
-Then translate the value of each string:
+Revise the comments at the top of the file to suit your localization,
+then translate the value of each string. For example, this is the German-language
+placeholder text for the search form:
 
-```TOML
-[docs_label_i_am]
-other = "ICH BIN..."
+```toml
+[ui_search_placeholder]
+other = "Suchen"
 ```
 
 Localizing site strings lets you customize site-wide text and features: for example, the legal copyright text in the footer on each page.
@@ -244,7 +310,9 @@ Some language teams have their own language-specific style guide and glossary. F
 
 ## Branching strategy
 
-Because localization projects are highly collaborative efforts, we encourage teams to work in shared localization branches.
+Because localization projects are highly collaborative efforts, we
+encourage teams to work in shared localization branches - especially
+when starting out and the localization is not yet live.
 
 To collaborate on a localization branch:
 
@@ -288,16 +356,4 @@ For more information about working from forks or directly from the repository, s
 
 SIG Docs welcomes upstream contributions and corrections to the English source.
 
-## Help an existing localization
-
-You can also help add or improve content to an existing localization. Join the [Slack channel](https://kubernetes.slack.com/messages/C1J0BPD2M/) for the localization, and start opening PRs to help. Please limit pull requests to a single localization since pull requests that change content in multiple localizations could be difficult to review.
-
-
 
-## {{% heading "whatsnext" %}}
-
-
-Once a localization meets requirements for workflow and minimum output, SIG docs will:
-
-- Enable language selection on the website
-- Publicize the localization's availability through [Cloud Native Computing Foundation](https://www.cncf.io/about/) (CNCF) channels, including the [Kubernetes blog](https://kubernetes.io/blog/).

data/i18n/de/OWNERS

@@ -0,0 +1,13 @@
+# See the OWNERS docs at https://go.k8s.io/owners
+
+# Localized strings for German.
+# Teams and members are visible at https://github.com/orgs/kubernetes/teams.
+
+reviewers:
+- sig-docs-de-reviews
+
+approvers:
+- sig-docs-de-owners
+
+labels:
+- language/de