サイトのローカリゼーション

OTel のウェブサイトは、ページのローカリゼーションをサポートするために、Hugo の multilingual framework をサポートしています。 デフォルトの言語は英語であり、米国英語がデフォルト（暗黙の）ローカリゼーションとして設定されています。 対応する言語の数は増えており、トップナビゲーションの言語ドロップダウンメニューから確認できます。

翻訳のガイド

ウェブサイトのページを英語から翻訳する場合は、この節のガイダンスにしたがうことをおすすめします。

要約

✅ すべきこと

❌ すべきでないこと

見出しID

見出しを翻訳する際に、見出しアンカーのターゲットをローカリゼーション全体で統一するために、以下に従ってください。

• 見出しに明示的な ID がある場合は、それを保持する。見出し ID の記法 は { #some-id } のように、見出しテキストの後に記述されます。
• そうでない場合は、元の英語の見出しに対して自動生成された ID に対応する明示的な ID を宣言する。

リンク

リンク参照を 翻訳しないで ください。 これは外部リンク、ウェブサイトのページへのパス、画像のようなセクションローカルのリソースにも当てはまります。

唯一の例外は、外部ページ（https://en.wikipedia.orgなど）へのリンクで、あなたのロケール固有のバージョンがある場合です。 多くの場合、これはURLのenをあなたのロケールの言語コードに置き換えることを意味します。

リンク定義ラベル

Markdown のリンク定義のラベルは翻訳しないでください。 かわりに、翻訳されたリンクテキストとしてラベルを書き直してください。たとえば、次の Markdown を考えてみます。

[Hello], world! Welcome to the [OTel website][].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

これをフランス語に翻訳すると次のようになります。

[Bonjour][hello], le monde! Bienvenue sur le [site OTel][OTel website].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

画像とダイアグラム

画像そのもの²のテキストをローカライズしない限り、画像ファイルのコピーを 作成しない でください。

Mermaid ダイアグラム内のテキストは 翻訳して ください。

インクルードファイル

_includes ディレクトリの下にあるページフラグメントは、他のページコンテンツと同じように 翻訳して ください。

ショートコード

一部の基本ショートコードには英語のテキストが含まれており、ローカリゼーションが必要になる場合があります。 特に、layouts/shortcodes/docs に含まれるものについては、その傾向が強いです。

ローカリゼーションしたショートコードを作成する必要がある場合は、layouts/shortcodes/xx に配置してください。 ここで xx はローカリゼーション対象の言語コードを指します。 その際、元の基本ショートコードと同じ相対パスを使用してください。

ローカリゼーションページの乖離を追跡する

ローカリゼーションページを維持する上で主な課題の 1 つは、対応する英語のページが更新されたタイミングを特定することです。 本セクションでは、どのように対処するのかを説明します。

default_lang_commit フロントマターフィールド

content/zh/<some-path>/page.md のようなローカリゼーションページが書かれた際に、この翻訳は content/en/<some-path>/page.md にある対応する英語版のページの特定の main ブランチのコミット に基づいています。 このリポジトリでは、それぞれのローカリゼーションページが対応する英語ページのコミットを以下のようにローカリゼーションページのフロントマターで識別します。

---
title: Your localized page title
...

default_lang_commit: <デフォルト言語の最新コミットハッシュ値>

上述のフロントマターは content/zh/<some-path>/page.md です。 このコミットは、main における content/en/<some-path>/page.md の最新コミットに対応します。

英語ページの変更を追跡する

英語ページの更新が作成されると、以下のコマンドを実行することで、対応するローカリゼーションページの更新が必要か追跡ができます。

$ npm run check:i18n
1       1       content/en/docs/platforms/kubernetes/_index.md - content/zh/docs/platforms/kubernetes/_index.md
...

以下のようにパスを追加することで、1 つまたはそれ以上のローカライゼーションするページに対象を絞れます。

npm run check:i18n -- content/zh

変更の詳細をみる

更新が必要なローカリゼーションページについて、-d フラグとローカリゼーションページへのパスを追加して差分を見るか、パスを省略して対応するページのすべての差分を見ることができます。 たとえば、以下のようになります。

$ npm run check:i18n -- -d content/zh/docs/platforms/kubernetes
diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
index 3592df5d..c7980653 100644
--- a/content/en/docs/platforms/kubernetes/_index.md
+++ b/content/en/docs/platforms/kubernetes/_index.md
@@ -1,7 +1,7 @@
 ---
 title: OpenTelemetry with Kubernetes
 linkTitle: Kubernetes
-weight: 11
+weight: 350
 description: Using OpenTelemetry with Kubernetes
 ---

default_lang_commit を新しいページに追加する

ローカリゼーションのページを作成する際は、default_lang_commit をページのフロントマターに追加し、main ブランチの適切なコミットハッシュを指定することを忘れないでください。

翻訳ページがmain における <hash> 時点の英語ページに基づいている場合、以下のコマンドを実行すると、default_lang_commit をコミット <hash> の値で自動的にページのフロントマターに追加できます。 ページが main の HEAD に同期している場合、引数として Head を指定できます。 たとえば、以下のように実行します。

npm run check:i18n -- -n -c 1ca30b4d content/ja
npm run check:i18n -- -n -c HEAD content/zh/docs/concepts

ハッシュキーを欠落しているローカリゼーションしたページのファイル一覧にするには、次を実行してください。

npm run check:i18n -- -n

既存のページの default_lang_commit を更新する

対応する英語のページに変更に合わせてローカリゼーションページを更新する際、default_lang_commit のコミットハッシュも忘れずに確認してください。

乖離したローカリゼーションページをまとめて更新した場合、-c フラグに続いてコミットハッシュまたは ‘HEAD’ を指定することで、それらのファイルのコミットハッシュを main@HEAD に更新できます。

npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>

乖離の状況

npm run fix:i18n:status を実行して、ローカライズ対象ページが原文から乖離した場合にフロントマターフィールド drifted_from_default を追加します。 このフィールドは近いうちに、英語版のページと比較してドリフトしたページの上部にバナーを表示するために使われるようになります。

スクリプトのヘルプ

スクリプトの詳細は、npm run check:i18n -- -h を実行してください。

新しいローカリゼーション

新しいローカリゼーションチーム

OpenTelemetry ウェブサイトの新しい言語のローカリゼーションを始めるには、以下が必要です。

1. あなたの言語に精通したローカリゼーションメンター。たとえば、CNCF Glossaryのアクティブな承認者やKubernetes ウェブサイトなどです。
2. 少なくとも2名の潜在的なコントリビューター。

準備ができたら、以下を実施してください。

1. コントリビュートの興味を共有するために新しいイシューを作成してください。

2. メンターと潜在的なコントリビューターのGitHubハンドルを追加してください。

3. 追加したい言語の公式ISO 639-1 コードを調べてください。このセクションの残りの部分では、この言語コードをLANG_IDと呼びます。

4. イシューの冒頭コメントに以下のタスクリストを追加してください。

   - [ ] Language info:
     - ISO 639-1 language code: `LANG_ID`
     - Language name: ADD_NAME_HERE
   - [ ] Locale team info:
     - [ ] Locale mentor: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
     - [ ] Contributors: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
   - [ ] Read through
         [Localization](https://opentelemetry.io/docs/contributing/localization/)
         and all other pages in the Contributing section
   - [ ] Localize site homepage to YOUR_LANGUAGE_NAME
   - [ ] OTel maintainers:
     - [ ] Update `hugo.yaml`
     - [ ] Configure cSpell and other tooling support
     - [ ] Create an issue label for `lang:LANG_ID`
     - [ ] Create org-level group for `LANG_ID` approvers
     - [ ] Update components owners for `content/LANG_ID`
   

5. ウェブサイトのホームページの翻訳を含むプルリクエストを送信してください。翻訳するのはcontent/LANG_ID/_index.mdファイルだけにしてください。メンテナーがPRを編集するために必要な権限があることを確認してください。彼らはローカリゼーションプロジェクトを開始するために必要な追加変更をPRに加えます。

最初のPRがマージされた後、メンテナーはイシューラベル、組織レベルのグループ、およびコンポーネント所有者を設定します。

OTelメンテナーチェックリスト

Hugo

hugo.yamlを更新します。LANG_IDの適切なエントリを以下に追加します。

• languages
• module.mounts。最低限、content用の単一のsource-targetエントリを追加します。ロケールに十分なコンテンツがある場合にのみ、enフォールバックページのエントリの追加を検討してください。

スペルチェック

NPMパッケージ@cspell/dict-LANG_IDとして利用可能なcSpell辞書を探します。 方言や地域に辞書がない場合は、最も近い地域のものを選んでください。

辞書が利用できない場合は、このサブセクションの残りをスキップします。 それ以外の場合は以下を実施してください。

• 開発依存関係としてNPMパッケージを追加します。例：npm install --save-dev @cspell/dict-bn
• .cspell/LANG_ID-words.txtを作成して、LANG_ID用のサイトローカル辞書単語を保存します。
• .cspell.ymlに以下のエントリを追加します。
  • import
  • dictionaryDefinitions
  • dictionaries：ここに2つのエントリを追加します。1つはLANG_ID、もう1つはLANG_ID-words.txtです

その他のツールサポート

• Prettierサポート：LANG_IDがPrettierで十分にサポートされていない場合は、.prettierignoreに無視ルールを追加します

英語メンテナーガイド

ロケールをまたぐドキュメント変更のPRを避ける

コントリビューターは、ロケールをまたぐドキュメント変更のPRを提出することを避けるべきです。 唯一の例外は次のセクションで説明されています。

非英語ページのリンクチェックが失敗したとき

英語のドキュメントへの変更により、非英語のロケールでリンクチェックの失敗が発生することがあります。 これはドキュメントページが移動または削除された場合に発生します。

このような状況では、リンクチェックに失敗するパスを持つ各非英語ページに対して以下の更新を行います。

• 新しいページパスへのリンク参照を更新します。
• default_lang_commitフロントマター行の末尾に# patchedというYAMLコメントを追加します。
• ファイルに他の変更を加えないでください。
• npm run check:linksを再実行して、リンクの失敗が残っていないことを確認します。