Helm ドキュメントの国際化
このガイドでは Helm ドキュメントをどのように国際化するかを説明します。
はじめに
翻訳への貢献にはドキュメントへの貢献と同様のプロセスを用います。翻訳は helm-www git リポジトリへの プルリクエストによって供給され、プルリクエストはウェブサイトの管理チームによってレビューされます。
2文字言語コード
ドキュメントは
ISO 639-1
標準 言語コードによって管理されます。例えば、韓国語の2文字コードは ko です。
コンテンツや設定でこの言語コードが使われます。3つ例を示します。
contentディレクトリ内で言語コードがサブディレクトリとして存在し、国際化されたコンテンツがそれぞれのディレクトリに入っています。i18nディレクトリはそれぞれの言語について、ウェブサイトで使用されるフレーズについての設定ファイルを保有しています。それらのファイルは[LANG]がその言語の2文字コードとなるような[LANG].tomlというパターンで命名されています。- トップレベルの
config.tomlファイルではナビゲーションやその他の詳細が言語コードごとに管理されています。
言語コード en を持つ英語が、デフォルトの言語および翻訳元として用いられます。
フォーク、ブランチ、変更、プルリクエスト
翻訳に貢献するために、まずは Github の helm-www リポジトリの フォークを作ることから始めましょう。あなたはまずあなたのフォークに変更をコミットすることから始めるでしょう。
初期状態であなたのフォークは main として知られるデフォルトブランチに設定されているでしょう。あなたの変更を開発するあるいはプルリクエストを作成するためにブランチを使用してください。もしブランチについて不慣れなら
それらについて Github ドキュメントで読むことができます。
ブランチを作成出来たら、翻訳を追加したり、コンテンツを国際化したりしましょう。
注：helm は
Developers Certificate of
Origin を利用しています。すべてのコミットは署名されている必要があります。コミットを作成する際に -s か --signoff フラグを用いることで、あなたの Git に設定されている名前とメールアドレスを用いてコミットに署名することができます。詳細については
CONTRIBUTING.md をご覧ください。
準備ができたら、 プルリクエスト を作成し、helm-www リポジトリに反映しましょう。
作成されたプルリクエストは管理者によってレビューされます。その過程についての詳細は CONTRIBUTING.md を参照してください。
コンテンツの翻訳
全ての Helm コンテンツを国際化するのは大きな仕事です。小さなことから初めて大丈夫です。時間をかけて翻訳を拡大することができます。
新たな言語を開始する
新たな言語を開始するには以下の最低要件が必要です。
_index.mdファイルを含むcontent/[LANG]/docsディレクトリを追加する。これはドキュメントランディングページの最上位です。i18nディレクトリに[LANG].tomlファイルを作成する。まずは開始地点としてen.tomlファイルをコピーすることができます。- 新たな言語を公開するため、
config.tomlファイルにその言語のセクションを追加する。既に存在する言語のセクションを開始地点とすることができます。
翻訳
翻訳されたコンテンツは content/[LANG]/docs ディレクトリ内に存在する必要があります。それらは英語ソースと同じURLを持ちます。例えば、イントロダクションを韓国語に翻訳するなら以下のように英語ソースをコピーすると便利です。
mkdir -p content/ko/docs/intro
cp content/en/docs/intro/install.md content/ko/docs/intro/install.md
新しいファイルの内容を別の言語に翻訳することができます。
翻訳されていない英語ファイルのコピーを content/[LANG]/ に追加しないでください。言語がその場所に存在する場合、未翻訳のページは自動的に英語にリダイレクトされます。翻訳には時間がかかるので、常に古いフォークではなく最新のドキュメントを翻訳するようにしてください。
全ての aliases 行をヘッダーセクションから削除するよう気をつけてください。aliases: ["/docs/using_helm/"] のような行は翻訳では持ちません。それらは新たなページには存在しない古いリンクへのリダイレクトです。
注：翻訳ツールが助けになるかもしれません。それには機械翻訳が含まれています。機械翻訳は公開前に編集される、またはネイティブ話者によって文法や意味をレビューされる必要があります。
言語間のナビゲーション
サイトグローバルな config.toml ファイルで言語ナビゲーションが設定されています。
新たな言語を追加するには、上で定義した新たな 2文字言語コードを追加する必要があります。例：
# Korean
[languages.ko]
title = "Helm"
description = "Helm - The Kubernetes Package Manager."
contentDir = "content/ko"
languageName = "한국어 Korean"
weight = 1
内部リンクの解決
翻訳されたコンテンツは時々別言語にしか存在しないページへのリンクを含んでいるでしょう。これによって ビルドエラーが発生します。例：
12:45:31 PM: htmltest started at 12:45:30 on app
12:45:31 PM: ========================================================================
12:45:31 PM: ko/docs/chart_template_guide/accessing_files/index.html
12:45:31 PM: hash does not exist --- ko/docs/chart_template_guide/accessing_files/index.html --> #basic-example
12:45:31 PM: ✘✘✘ failed in 197.566561ms
12:45:31 PM: 1 error in 212 documents
これを解決するために、あなたのコンテンツの内部リンクを確認する必要があります。
- アンカーリンクは翻訳された
idの値を反映する必要があります。 - 内部リンクを修正する必要があります。
存在しない （もしくはまだ翻訳されていない） 内部ページについては、修正がされるまでサイトがビルドされません。代わりに、下記のようにコンテンツが 存在する 別の言語にURLを向けることができます。
< relref path="/docs/topics/library_charts.md" lang="en" >
詳細については 言語間相互リファレンスについての Hugo ドキュメント をご覧ください。
