18 KiB
| title | content_type | card | ||||||
|---|---|---|---|---|---|---|---|---|
| Kubernetesのドキュメントを翻訳する | concept |
|
このページでは、ドキュメントを異なる言語に翻訳する方法について紹介します。
はじめる
コントリビューターが自分自身のプルリクエストを承認することはできないため、翻訳を始めるには、最低でも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 >}}の英語のファイルをベースにしなければなりません。
最新のリリースのソースファイルを見つけるには、次のように探してください。
- Kubernetesのウェブサイトのリポジトリ https://github.com/kubernetes/website に移動する。
- 最新バージョンの
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..."
サイト文字列を翻訳することで、サイト全体で使われるテキストや機能をカスタマイズできます。たとえば、各ページのフッターにある著作権のテキストなどです。
言語固有のスタイルガイドと用語集
一部の言語チームでは、言語固有のスタイルガイドや用語集を持っています。たとえば、韓国語の翻訳ガイドを見てください。
ブランチの戦略
翻訳プロジェクトは協力が非常に重要な活動のため、チームごとに共有の開発ブランチで作業することを推奨します。
開発ブランチ上で共同作業するためには、以下の手順を行います。
-
@kubernetes/website-maintainersのチームメンバーが https://github.com/kubernetes/website のソースブランチから開発ブランチを作る。
kubernetes/orgリポジトリに翻訳チームを追加したとき、チームの承認者は@kubernetes/website-maintainersチームに参加します。次のようなブランチの命名規則に従うことを推奨します。
dev-<ソースのバージョン>-<言語コード>.<チームのマイルストーン>たとえば、ドイツ語の翻訳チームの承認者は、Kubernetes v1.12のソースブランチをベースに、k/websiteリポジトリから直接開発ブランチ
dev-1.12-de.1を作ります。 -
各コントリビューターが、開発ブランチをベースにフィーチャーブランチを作る。
たとえば、ドイツ語のコントリビューターは、
username:local-branch-nameからkubernetes:dev-1.12-de.1に対して、変更を含むプルリクエストを開きます。 -
承認者がフィーチャーブランチをレビューして、開発ブランチにマージする。
-
定期的に新しいプルリクエストを開いて承認することで、承認者が開発ブランチをソースブランチにマージする。プルリクエストを承認する前にコミットをsquashするようにしてください。
翻訳が完了するまで、1-4のステップを必要なだけ繰り返します。たとえば、ドイツ語のブランチは、dev-1.12-de.2、dev-1.12-de.3と続きます。
チームは、翻訳したコンテンツを元となったリリースブランチにマージする必要があります。たとえば、{{< release-branch >}}から作られた開発ブランチは、必ず{{< release-branch >}}にマージしなければなりません。
承認者は、ソースブランチを最新の状態に保ち、マージのコンフリクトを解決することで、開発ブランチをメンテナンスしなければなりません。開発ブランチが長く開いたままであるほど、一般により多くのメンテナンスが必要になります。そのため、非常に長い期間に渡って開発ブランチを維持するよりは、定期的に開発ブランチをマージして、新しいブランチを作ることを考えてください。
各チームマイルストーンの最初には、1つ前の開発ブランチと現在の開発ブランチの間のアップストリームの変更を比較するissueを開くと役に立ちます。
新しい開発ブランチを開いたりプルリクエストをマージできるのは承認者だけですが、新しい開発ブランチには誰でもプルリクエストを開くことができます。特別な許可は必要ありません。
フォークやリポジトリから直接行う作業についての詳しい情報は、「リポジトリをフォーク・クローンする」を読んでください。
アップストリームのコントリビューター
SIG Docsでは、英語のソースに対するアップストリームへのコントリビュートや誤りの訂正を歓迎しています。
既存の翻訳を助ける
コンテンツの追加や改善により既存の翻訳を助けることもできます。翻訳のためのSlackチャンネルに参加して、助けとなるPRを開くことを始めましょう。
{{% heading "whatsnext" %}}
翻訳がワークフローと最小限のコンテンツの要件を満たしたら、SIG docsは次の作業を行います。
- ウェブサイト上で言語の選択を有効にする。
- Kubernetesブログを含むCloud Native Computing Foundation(CNCF)のチャンネルで、翻訳が利用できるようになったことを公表する。