Skip to content

Commit

Permalink
Revise L10n contribution guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
zacharysarah committed Apr 17, 2019
1 parent f1750f1 commit a9ee932
Showing 1 changed file with 55 additions and 44 deletions.
99 changes: 55 additions & 44 deletions content/en/docs/contribute/localization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
title: Localizing Kubernetes Documentation
content_template: templates/concept
approvers:
- chenopis
- remyleone
- rlenferink
- zacharysarah
- zparnold
card:
name: contribute
weight: 30
Expand All @@ -13,53 +13,70 @@ card:

{{% capture overview %}}

Documentation for Kubernetes is available in multiple languages. We encourage you to add new [localizations](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/)!
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.

{{% /capture %}}

{{% capture body %}}

## Getting started

Localizations must meet some requirements for workflow (*how* to localize) and output (*what* to localize) before publishing.

To add a new localization of the Kubernetes documentation, you'll need to update the website by modifying the [site configuration](#modify-the-site-configuration) and [directory structure](#add-a-new-localization-directory). Then you can start [translating documents](#translating-documents)!
To add a new localization of the Kubernetes documentation, you'll need to follow these steps:

{{< 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.
You will need at least two contributors to begin a new localization.

All localization teams must be self-sustaining with their own resources. We're happy to host your work, but we can't translate it for you.
{{< /note >}}

Let Kubernetes SIG Docs know you're interested in creating a localization! Join the [SIG Docs Slack channel](https://kubernetes.slack.com/messages/C1J0BPD2M/). We're happy to help you get started and answer any questions you have.
### Find your two-letter language code

All localization teams must be self-sustaining with their own resources. We're happy to host your work, but we can't translate it for you.
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`.

### Fork and clone the repo

First, [create your own fork](https://help.github.com/articles/fork-a-repo/) of the [kubernetes/website](https://github.com/kubernetes/website).
First, [create your own fork](/docs/contribute/start/#improve-existing-content) of the [kubernetes/website](https://github.com/kubernetes/website).

Then, clone the website repo and `cd` into it:
Then, clone your fork and `cd` into it:

```shell
git clone https://github.com/kubernetes/website
git clone https://github.com/<username>/website
cd website
```

{{< note >}}
Contributors to `k/website` must [create a fork](/docs/contribute/start/#improve-existing-content) from which to open pull requests. For localizations, we ask additionally that:
### Open a pull request

1. Team approvers open development branches directly from https://github.com/kubernetes/website.
2. Localization contributors work from forks, with branches based on the current development branch.
Next, [open a pull request](https://kubernetes.io/docs/contribute/start/#submit-a-pull-request) (PR) to add a localization to the `kubernetes/website` repository.

This is because localization projects are collaborative efforts on long-running branches, similar to the development branches for the Kubernetes release cycle. For information about localization pull requests, see ["branching strategy"](#branching-strategy).
{{< /note >}}
The PR must include all of the [minimum required content](#minimum-required-content) before it can be approved.

### Find your two-letter language code
For an example of adding a new localization, see the PR to enable [docs in French](https://github.com/kubernetes/website/pull/8636).

### Join the Kubernetes GitHub organization

Consult the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php) for your localization's two-letter country code. For example, the two-letter code for German is `de`.
Once you've opened a localization PR, you can become members of the Kubernetes GitHub organization. Each person on the team needs to create their own [issue requesting membership](https://github.com/kubernetes/org/issues/new/choose) in the `kubernetes/org` repository.

{{< note >}}
These instructions use the [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) language code for German (`de`) as an example.
{{< /note >}}
### Add your localization team in GitHub

Next, add your Kubernetes localization team to [`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml).

For an example of adding a localization team, see the PR to add the [Spanish localization team](https://github.com/kubernetes/org/pull/685).

### Configure the workflow

Next, add a GitHub label for your localization in the `kubernetes/test-infra` repository. A label lets you filter issues and pull requests for your specific language.

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/C1J0BPD2M/). Other localization teams are happy to help you get started and answer any questions you have.

You can also create a Slack channel for your localization in the in `kubernetes/community` repository.

For an example of adding a Slack channel, see the PR for [adding channels for Indonesian and Portuguese](https://github.com/kubernetes/community/pull/3605).

## Minimum required content

### Modify the site configuration

Expand Down Expand Up @@ -88,6 +105,10 @@ 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

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`.
Expand All @@ -97,9 +118,9 @@ Provide guidance to localization contributors in the localized `README-**.md` fi
- 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 file, [`README.md`'s Localizing Kubernetes Documentation] and include contact information in English. You can provide a GitHub ID, email address, [Slack channel](https://slack.com/), or other method of contact.
After you create the localized README, add a link to the file from the main English file, [`README.md`'s Localizing Kubernetes Documentation] 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 your localized Community Code of Conduct.

## Translating documents
## Translating content

Localizing *all* of the Kubernetes documentation is an enormous task. It's okay to start small and expand over time.

Expand All @@ -119,11 +140,9 @@ mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
```

For an example of a localization-related [pull request](../create-pull-request), [this pull request](https://github.com/kubernetes/website/pull/10471) to the [Kubernetes website repo](https://github.com/kubernetes/website) added Korean localization to the Kubernetes docs.
### Source files

### Source Files

Localizations must use English files from the most recent release as their source. The most recent version is **{{< latest-version >}}**.
Localizations must be based on the English files from the most recent release. The most recent version is **{{< latest-version >}}**.

To find source files for the most recent release:

Expand Down Expand Up @@ -151,21 +170,9 @@ other = "ICH BIN..."

Localizing site strings lets you customize site-wide text and features: for example, the legal copyright text in the footer on each page.

## Project logistics

### Contact the SIG Docs chairs
## Branching strategy

Contact one of the chairs of the Kubernetes [SIG Docs](https://github.com/kubernetes/community/tree/master/sig-docs#chairs) chairs when you start a new localization.

### Maintainers

Each localization repository must provide its own maintainers. Maintainers can be from a single organization or multiple organizations. Whenever possible, localization pull requests should be approved by a reviewer from a different organization than the translator.

A localization must provide a minimum of two maintainers. (It's not possible to review and approve one's own work.)

### Branching strategy

Because localization projects are highly collaborative efforts, we encourage teams to work from a shared development branch.
Because localization projects are highly collaborative efforts, we encourage teams to work in shared development branches.

To collaborate on a development branch:

Expand Down Expand Up @@ -195,10 +202,14 @@ While only approvers can merge pull requests, anyone can open a pull request for

For more information about working from forks or directly from the repository, see ["fork and clone the repo"](#fork-and-clone-the-repo).

### Upstream contributions
## Upstream contributions

SIG Docs welcomes [upstream contributions and corrections](/docs/contribute/intermediate#localize-content) to the English source.

## Help an existing localization

You can also help add or improve content to an existing localization. Join the Slack channel for the localization, and start opening PRs to help.

{{% /capture %}}

{{% capture whatsnext %}}
Expand Down

0 comments on commit a9ee932

Please sign in to comment.