Try Kubernetes

Contribute to Kubernetes docs

Edit This Page

Localizing Kubernetes Documentation

The Kubernetes documentation is currently available in multiple languages and we encourage you to add new localizations (l10n)!

Currently available languages:

Language Language code Repository
English en https://github.com/kubernetes/website
Chinese cn https://github.com/kubernetes/kubernetes-docs-zh

In order for localizations to be accepted, however, they must fulfill some requirements related to workflow (how to localize) and output (what to localize).

Workflow

The Kubernetes documentation for all languages is built from the 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 synced to the main kubernetes/website repository via pull request.

Work on the Chinese translation, for example, happens in the kubernetes/kubernetes-docs-zh repository.

Note: For an example localization-related pull request, see this pull request to the Kubernetes website repo adding Korean localization to the Kubernetes docs.

Source Files

Localizations must use English files from the most recent major release as sources. To find the most recent release’s documentation source files:

  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 v1.11, making the most recent release branch release-1.11.

Getting started

In order to add a new localization of the Kubernetes documentation, you’ll need to make a few modifications to the site’s configuration and directory structure, and then you can get to work translating documents!

To get started, clone the website repo and cd into it:

git clone https://github.com/kubernetes/website
cd website
git checkout release-1.11

Configuration

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 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:

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3

When assigning a weight parameter, see which of the current languages has the highest weight and add 1 to that value.

Now add a language-specific subdirectory to the content folder. The two-letter code for German is de, so add a content/de directory:

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
Setup All heading and subheading URLs
Tutorials Kubernetes Basics, 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 doc into German, for example, create the proper subfolder under the content/de folder and copy the English doc:

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 organization. The current chairs are listed here.

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. You can provide an email address, email list, Slack channel, 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.

Projects must include at least these columns:

Note: For an example GitHub project, see the Chinese localization project.

Repository structure

Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main 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.

What's next

Once a l10n meets requirements for workflow and minimum output, SIG docs will: