website/content/ja/docs/contribute/localization.md

title	content_template	card
Kubernetesのドキュメントをローカライズする	templates/concept	name weight title contribute 30 Translating the docs

{{% capture overview %}}

このページでは、ドキュメントを異なる言語にローカライズする方法について紹介します。

{{% /capture %}}

{{% capture body %}}

はじめる

コントリビューターが自分自身のプルリクエストを承認することはできないため、ローカライゼーションを始めるには、最低でも2人が必要です。

すべてのローカライゼーションチームは、自分たちのリソースを継続的に自己管理しなければいけません。私たちはドキュメントを喜んでホストしますが、あなたの代わりに翻訳することはできないからです。

2文字の言語コードを探す

まず最初に、ISO 639-1標準のドキュメントから、ローカライゼーションの2文字の国コードを探してください。たとえば、韓国語のための国コードはkoです。

リポジトリをフォーク・クローンする

初めに、kubernetes/websiteリポジトリの自分用のフォークを作成します。

そして、フォークをクローンして、ディレクトリにcdします。

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

プルリクエストを開く

次に、kubernetes/websiteリポジトリにローカライゼーションを追加するためのプルリクエスト(PR)を開きます。

このPRが承認されるためには、最低限必要なコンテンツが含まれていなければなりません。

新しいローカライゼーションを追加する例としては、フランス語版ドキュメントを追加するPRを参考にしてください。

Kubernetes GitHub organizationに参加する

ローカライゼーションのPRを作ると、Kubernetes GitHub organizationのメンバーになることができます。チームの各個人は、それぞれkubernetes/orgリポジトリにOrganization Membership Requestを作成する必要があります。

ローカライゼーションチームをGitHubに追加する

次に、Kubernetesのローカライゼーションチームをsig-docs/teams.yamlに追加します。ローカライゼーションチームを追加する例として、スペイン語のローカライゼーションチームを追加するPRを見てください。

@kubernetes/sig-docs-**-ownersのメンバーは、ローカライゼーションのディレクトリ/content/**/以下のコンテンツのみを変更するPRを承認できます。

各ローカライゼーションごとに、新しいPRに対して@kubernetes/sig-docs-**-reviewsチームがレビューに自動的にアサインされます。

@kubernetes/website-maintainersのメンバーは、翻訳作業をコーディネートするために新しい開発ブランチを作ることができます。

@kubernetes/website-milestone-maintainersのメンバーは、issueやPRにマイルストーンをアサインするために、/milestoneProwコマンドが使用できます。

ワークフローを設定する

次に、kubernetes/test-infraリポジトリに新しいローカライゼーション用のGitHubラベルを追加します。ラベルを利用すると、issueやプルリクエストを特定の言語のものだけにフィルタできます。

ラベルを追加する例としては、イタリア語の言語ラベルを追加するPRを見てください。

コミュニティを見つける

Kubernetes SIG Docsに、ローカライゼーションを作りたいと思っていることを知らせてください！SIG Docs Slackチャンネルに参加してください。他のローカライゼーションメンバーが、あなたがローカライゼーションを始めるのを喜んで助けてくれ、どんな疑問にも答えてくれます。

kubernetes/communityリポジトリ内で、ローカライゼーション用のSlackチャンネルを作ることもできます。Slackチャンネルを追加する例としては、インドネシア語とポルトガル語用のチャンネルを追加するためのPRを見てください。

最低限必要なコンテンツ

サイトの設定を修正する

Kubernetesのウェブサイトでは、Hugoをウェブフレームワークとして使用しています。ウェブサイトのHugoの設定は、config.tomlファイルの中に書かれています。新しいローカライゼーションをサポートするには、config.tomlを修正する必要があります。

config.tomlの既存の[languages]ブロックの下に、新しい言語の設定ブロックを追加してください。たとえば、ドイツ語のブロックの場合、次のようになります。

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

ブロックのweightパラメーターの設定では、最も高い重みを持つ言語ブロックを探し、その値に1を加えた値を指定してください。

Hugoの多言語サポートについての詳しい情報は、「多言語モード」を参照してください。

新しいローカライゼーションのディレクトリを追加する

contentフォルダーに、言語用のサブディレクトリを追加してください。2文字の言語コードがdeであるドイツ語の場合、次のようにディレクトリを作ります。

mkdir content/de

Community Code of Conductをローカライズする

あなたの言語のcode of conductを追加するために、PRをcncf/foundationリポジトリに対して開いてください。

ローカライズしたREADMEを追加する

他のローカライゼーションのコントリビューターをガイドするために、kubernetes/websiteのトップレベルに新しいREADME-**.mdを追加してください。ここで、**は2文字の言語コードです。たとえば、ドイツ語のREADMEファイルはREADME-de.mdです。

ローカライズされたREADME-**.mdファイルの中で、ローカライゼーションのコントリビューターにガイダンスを提供してください。README.mdに含まれているのと同じ情報に加えて、以下の情報も追加してください。

• ローカライゼーションプロジェクトのための連絡先
• ローカライゼーション固有の情報

ローカライズされたREADMEを作成したら、メインの英語のREADME.mdからそのファイルへのリンクを追加し、英語で連絡先情報も書いてください。GitHub ID、メールアドレス、Slackチャンネル、その他の連絡手段を提供できます。ローカライズされたCommunity Code of Conductへのリンクも必ず提供してください。

OWNERSファイルを設定する

ローカライゼーションにコントリビュートする各ユーザーのロールを設定するには、言語用のサブディレクトリの中にOWNERSファイルを作成し、以下の項目を設定します。

• レビュア: レビュアのロールを持つkubernetesチームのリストです。この場合は、GitHubでローカライゼーションチームを追加で作成したsig-docs-**-reviewsチームです。
• 承認者: 承認者のロールを持つkubernetesチームのリストです。この場合は、GitHubでローカライゼーションチームを追加で追加したsig-docs-**-ownersチームです。
• ラベル: PRに自動的に適用されるGitHub上のラベルのリストです。この場合は、ワークフローを設定するで作成した言語ラベルです。

OWNERSファイルに関するより詳しい情報は、go.k8s.io/ownersを参照してください。

言語コードがesのスペイン語のOWNERSファイルは次のようになります。

# See the OWNERS docs at https://go.k8s.io/owners

# This is the localization project for Spanish.
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

特定の言語用のOWNERSファイルを追加したら、ルートのOWNERS_ALIASESファイルを、ローカライゼーションのための新しいKuerbetesチーム、sig-docs-**-ownersおよびsig-docs-**-reviewsで更新します。

各チームごとに、ローカライゼーションチームをGitHubに追加するでリクエストしたGitHubユーザーのリストをアルファベット順で追加してください。

--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
     - stewart-yu
     - xiangpengzhao
     - zhangxiaoyu-zidif
+  sig-docs-es-owners: # Admins for Spanish content
+    - alexbrand
+    - raelga
+  sig-docs-es-reviews: # PR reviews for Spanish content
+    - alexbrand
+    - electrocucaracha
+    - glo-pena
+    - raelga
   sig-docs-fr-owners: # Admins for French content
     - perriea
     - remyleone

コンテンツを翻訳する

Kubernetesのドキュメントの すべて をローカライズするのは、非常に大きな作業です。小さく始めて、時間をかけて拡大していけば大丈夫です。

最低限、すべてのローカライゼーションには以下のコンテンツが必要です。

説明	URL
ホーム	すべての見出しと小見出しのURL
セットアップ	すべての見出しと小見出しのURL
チュートリアル	Kubernetes Basics、Hello Minikube
サイト文字列	ローカライズされた新しいTOMLファイル内のすべてのサイト文字列

翻訳されたドキュメントは、言語ごとにcontent/**/サブディレクトリに置き、英語のソースと同じURLパスに従うようにしなければいけません。たとえば、Kubernetes Basicsのチュートリアルをドイツ語に翻訳する準備をするには、次のように、content/de/フォルダ以下にサブディレクトリを作り、英語のソースをコピーします。

mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md

翻訳ツールを使えば、翻訳のプロセスをスピードアップできます。たとえば、エディタによってはテキストを高速に翻訳してくれるプラグインがあります。

{{< caution >}} 機械生成された翻訳は、そのままでは最低限の品質基準を満たしません。基準を満たすためには、人間による十分なレビューが必要です。 {{< /caution >}}

文法と意味の正確さを保証するために、公開する前にローカライゼーションチームのメンバーが機械生成されたすべての翻訳を注意深くレビューしなければいけません。

ソースファイル

ローカライゼーションは、最新のリリース{{< latest-version >}}の英語のファイルをベースにしなければなりません。

最新のリリースのソースファイルを見つけるには、次のように探してください。

1. Kubernetesのウェブサイトのリポジトリ https://github.com/kubernetes/website に移動する。
2. 最新バージョンのrelease-1.Xブランチを選択する。

最新バージョンは{{< latest-version >}}であるため、最新のリリースブランチは[{{< release-branch >}}](https://github.com/kubernetes/website/tree/{{< release-branch >}})です。

i18n/内のサイト文字列

ローカライゼーションには、i18n/en.tomlの内容を新しい言語用のファイル内に含める必要があります。ドイツ語を例に取ると、ファイル名はi18n/de.tomlです。

新しいローカライゼーションファイルをi18n/に追加します。たとえば、ドイツ語(de)であれば次のようになります。

cp i18n/en.toml i18n/de.toml

そして、各文字列の値を翻訳します。

[docs_label_i_am]
other = "ICH BIN..."

サイト文字列をローカライズすることで、サイト全体で使われるテキストや機能をカスタマイズできます。たとえば、各ページのフッターにある法的な著作権のテキストなどです。

言語固有のスタイルガイドと用語集

一部の言語チームでは、言語固有のスタイルガイドや用語集を持っています。たとえば、韓国語のローカライゼーションガイドを見てください。

ブランチの戦略

ローカライゼーションプロジェクトは非常に協力的な活動であるため、チームでは共有の開発ブランチで作業することを推奨します。

開発ブランチ上で共同作業するためには、以下の手順を行います。

1. @kubernetes/website-maintainersのチームメンバーが https://github.com/kubernetes/website のソースブランチから開発ブランチを作る。

   kubernetes/orgリポジトリにローカライゼーションチームを追加したとき、チームの承認者は@kubernetes/website-maintainersチームに参加します。

   次のようなブランチの命名規則に従うことを推奨します。

   dev-<ソースのバージョン>-<言語コード>.<チームのマイルストーン>

   たとえば、ドイツ語のローカライゼーションチームの承認者は、Kubernetes v1.12のソースブランチをベースに、k/websiteリポジトリから直接開発ブランチdev-1.12-de.1を作ります。

2. 各コントリビューターが、開発ブランチをベースにフィーチャーブランチを作る。

   たとえば、ドイツ語のコントリビューターは、username:local-branch-nameからkubernetes:dev-1.12-de.1に対して、変更を含むプルリクエストを開きます。

3. 承認者がフィーチャーブランチをレビューして、開発ブランチにマージする。

4. 定期的に新しいプルリクエストを開いて承認することで、承認者が開発ブランチをソースブランチにマージする。プルリクエストを承認する前にコミットをsquashするようにしてください。

ローカライゼーションが完了するまで、1-4のステップを必要なだけ繰り返します。たとえば、ドイツ語のブランチは、dev-1.12-de.2、dev-1.12-de.3と続きます。

チームは、ローカライズしたコンテンツを元となったリリースブランチにマージする必要があります。たとえば、{{< release-branch >}}から作られた開発ブランチは、必ず{{< release-branch >}}にマージしなければなりません。

承認者は、ソースブランチを最新の状態に保ち、マージのコンフリクトを解決することで、開発ブランチをメンテナンスしなければなりません。開発ブランチが長く開いたままであるほど、一般により多くのメンテナンスが必要になります。そのため、非常に長い期間に渡って開発ブランチを維持するよりは、定期的に開発ブランチをマージして、新しいブランチを作ることを考えてください。

各チームマイルストーンの最初には、1つ前の開発ブランチと現在の開発ブランチの間のアップストリームの変更を比較するissueを開くと役に立ちます。

新しい開発ブランチを開いたりプルリクエストをマージできるのは承認者だけですが、新しい開発ブランチには誰でもプルリクエストを開くことができます。特別な許可は必要ありません。

フォークやリポジトリから直接行う作業についての詳しい情報は、「リポジトリをフォーク・クローンする」を読んでください。

アップストリームのコントリビューター

SIG Docsでは、英語のソースに対するアップストリームのコントリビューションや誤りの訂正を歓迎しています。

既存のローカライゼーションを助ける

コンテンツの追加や改善により既存のローカライゼーションを助けることもできます。ローカライゼーションのためのSlackチャンネルに参加して、助けとなるPRを開くことを始めましょう。

{{% /capture %}}

{{% capture whatsnext %}}

ローカライゼーションがワークフローと最小限のコンテンツの要件を満たしたら、SIG docsは次の作業を行います。

• ウェブサイト上で言語の選択を有効にする。
• Kubernetesブログを含むCloud Native Computing Foundation(CNCF)のチャンネルで、ローカライゼーションが利用できるようになったことを公表する。

{{% /capture %}}