[ja] fix drift of content/ja/docs/contributing/localization

ymotongpoo · ymotongpoo · commit 6601bc01aeba · 2025-03-11T10:30:26.000+09:00
diff --git a/content/ja/docs/contributing/localization.md b/content/ja/docs/contributing/localization.md
@@ -3,7 +3,7 @@ title: サイトのローカリゼーション
 description: 非英語ローカリゼーションのサイトページの作成と管理
 linkTitle: ローカリゼーション
 weight: 25
-default_lang_commit: b7e40731390448f604897ded62cff8abd3505430
+default_lang_commit: f2a520b85d72db706bff91d879f5bb10fd2e7367
 drifted_from_default: true
 cSpell:ignore: shortcodes
 ---
@@ -12,76 +12,105 @@ OTel のウェブサイトは、ページのローカリゼーションをサポ
 デフォルトの言語は英語であり、米国英語がデフォルト（暗黙の）ローカリゼーションとして設定されています。
 対応する言語の数は増えており、トップナビゲーションの言語ドロップダウンメニューから確認できます。
 
-## 英語メンテナーガイド {#english-language-maintainer-guidance}
+## 翻訳のガイド {#translation-guidance}
 
-### 非英語ページのリンクチェックが失敗したとき {#when-link-checking-fails-for-non-english-pages}
+ウェブサイトのページを英語から翻訳する場合は、この節のガイダンスにしたがうことをおすすめします。
 
-英語は OpenTelemetry ウェブサイトのデフォルト言語です。
-英語のドキュメントを追加、編集、再構成した後に、非英語ページのリンクチェックが失敗する可能性があります。
-そのような場合は、以下を実行してください。
+### 要約
 
-<!-- markdownlint-disable blanks-around-fences -->
+#### ✅ すべきこと {#do}
 
-- リンクを**修正しないでください**。それぞれの非英語ページは対応する英語のページの特定のコミット（フロントマターキーである `default_lang_commit` の Git コミットハッシュ）に関連づけられています。
-- 以下のフロントマター、1 つの以上のページがリンクエラーが発生している場合は最も近い祖先のファイルに非英語ページを無視するようにリンクチェッカーを設定してください。
-  ```yaml
-  htmltest:
-    # TODO: remove the IgnoreDirs once broken links are fixed
-    IgnoreDirs:
-      - path-regex/to/non-en/directory/contain/files/to/ignore
-      - path-2-etc
-  ```
-- `npm run check:links` を実行して、設定ファイル `.htmltest.yml` への変更を PR に含めてください。
+<div class="border-start border-success bg-success-subtle">
 
-<!-- markdownlint-enable blanks-around-fences -->
+- **翻訳**
+  - 以下を含むページの内容
+    - Mermaid [diagram](#images)のテキストフィールド
+    - コードスニペット内のコメント
+  - [フロントマター][front matter] 内の `title`、 `linkTitle`、 `description` のフィールド値
+  - 特別な指示がない場合、ページ内の **すべての** コンテンツとフロントマターの内容
+- 原文の _内容_、 _意味_、 _スタイル_ を **変更しないこと**
+- もしなにか疑問等があれば、以下の方法で [メンテナー][maintainers] に **質問すること**
+  - [Slack] の `#otel-docs-localization` か `#otel-comms` の各チャンネル
+  - [Discussion]やイシュー、あるいはPRコメント
 
-## 翻訳ガイダンス {#translation-guidance}
+[Discussion]:
+  https://github.com/open-telemetry/opentelemetry.io/discussions?discussions_q=is%3Aopen+label%3Ai18n
 
-ページの翻訳の際には、本セクションのガイドに従うことを推奨します。
+</div>
 
-### 見出しアンカー {#heading-anchors}
+#### ❌ すべきでないこと {#do-not}
 
-見出しを翻訳する際に、見出しアンカーのターゲットをローカリゼーション全体で統一するために、以下に従ってください。
+<div class="border-start border-warning bg-warning-subtle">
 
-- 見出しに明示的な ID がある場合は、それを保持する。[見出し ID の記法][Heading ID syntax] は `{ #some-id }` のように、見出しテキストの後に記述されます。
-- そうでない場合は、元の英語の見出しに対して自動生成された ID に対応する明示的な ID を宣言する。
+- **翻訳**
+  - このレポジトリ内のリソースの **ファイルやディレクトリ** の名前
+  - [見出しID](#headings) を含む [リンク](#links) [^*]
+  - [すべきこと](#do) で指示されていない [フロントマター][front matter] のフィールド。特に、`aliases` は翻訳しないこと。よくわからない場合はメンテナーに質問すること。
+  - ソースコード
+- [画像内のテキストを翻訳する](#images) 場合以外で **画像ファイルのコピー** をすること。
+- 新規に追加したり変更すること
+  - 原文で意図した意味と異なる **内容**
+  - 表示の **スタイル**。たとえば _フォーマット_、_レイアウト_、_デザイン_ スタイル（タイポグラフィ、文字の大文字小文字、空白など）。
 
-{{% alert title="Note" %}}
+[^*]: ありえる例外に関しては [リンク](#links) を参照のこと。
 
-翻訳ページのすべての見出しに明示的な見出し ID を追加するか、リンクチェッカーで報告された既知のサイト内見出しターゲットにのみ追加するかは、ローカリゼーションの執筆者の裁量に委ねられます。
-前者の方法は一貫性が保たれますが、作業量が増えます。
-しかし、サイト外からローカリゼーションされたページのリンクをより適切にサポートでき、新しい見出しターゲットが追加された際に、過去の翻訳ページを修正する手間を減らすことができます。
+</div>
 
-{{% /alert %}}
+### 見出しID {#headings}
+
+見出しを翻訳する際に、見出しアンカーのターゲットをローカリゼーション全体で統一するために、以下に従ってください。
+
+- 見出しに明示的な ID がある場合は、それを保持する。[見出し ID の記法][Heading ID syntax] は `{ #some-id }` のように、見出しテキストの後に記述されます。
+- そうでない場合は、元の英語の見出しに対して自動生成された ID に対応する明示的な ID を宣言する。
 
 [Heading ID syntax]: https://github.com/yuin/goldmark/blob/master/README.md#headings
 
 ### リンク {#links}
 
-ローカルパスへ参照しているリンク（外部リンクではなく）は、そのパスのままにしてください。
-これは、ウェブサイトのページへのリンクや、画像などのセクション内リソースへのリンクにも当てはまります。
+リンク参照を **翻訳しないで** ください。
+これは外部リンク、ウェブサイトのページへのパス、[画像](#images)のようなセクションローカルのリソースにも当てはまります。
+
+唯一の例外は、外部ページ（<https://en.wikipedia.org>など）へのリンクで、あなたのロケール固有のバージョンがある場合です。
+多くの場合、これはURLの`en`をあなたのロケールの言語コードに置き換えることを意味します。
 
 {{% alert title="Note" %}}
 
-OTel ウェブサイトリポジトリには、Hugo が使用する**絶対リンクのパスをドキュメントのページに変換する**カスタムレンダーリンクを持っています。
-`/docs/some-page` のようなリンクは、リンクをレンダリングする際にページの言語コードがパスの先頭に追加され、ローカリゼーションされます。
-たとえば、日本語ページからレンダリングされた際に、このサンプルのパスは `/ja/docs/some-page` になります。
+OTelウェブサイトのリポジトリには、Hugoがドキュメントページを参照する絶対リンクパスを変換するために使用するカスタムの render-link フックがあります。
+**`docs/some-page` 形式のリンク** は、リンクをレンダリングするときに、パスの先頭にページの言語コードを付けることで、 **ロケール固有になります** 。
+たとえば、先ほどのサンプルのパスは、日本語のページからレンダリングされた場合には `/ja/docs/some-page` となります。
 
 {{% /alert %}}
 
-### 画像 {#images}
+### 画像とダイアグラム {#images}
+
+画像そのもの[^shared-images]のテキストをローカライズしない限り、画像ファイルのコピーを **作成しない** でください。
+
+[Mermaid][] ダイアグラム内のテキストは **翻訳して** ください。
+
+
+[^shared-images]:
+    Hugoは、サイトのローカライゼーション間で共有される画像ファイルをレンダリングする方法についてスマートです。
+    つまり、Hugoは _単一の_ 画像ファイルを出力し、それをロケール間で共有します。
 
-Hugo は、サイトのローカリゼーション間で共有されるページ画像をレンダリングする際に、効率的な処理を行います。
-つまり、生成されたサイトフォルダ内では、Hugo は **1 つの**画像ファイルを出力し、それを各ローカリゼーションで共有します。
+[Mermaid]: https://mermaid.js.org
 
-したがって、一般的なルールとして、実際に画像を変更しない限り、ローカリゼーション用に画像のコピーを**作成しないでください**。
+### インクルードファイル {#includes}
+
+`_includes` ディレクトリの下にあるページフラグメントは、他のページコンテンツと同じように **翻訳して** ください。
 
 ### ショートコード {#shortcodes}
 
+{{% alert title="Note" %}}
+
+2025年2月現在、私たちは共有ページのコンテンツをサポートする手段として、ショートコードから[インクルードファイル](#includes)への移行を進めています。
+
+{{% /alert %}}
+
 一部の基本ショートコードには英語のテキストが含まれており、ローカリゼーションが必要になる場合があります。
 特に、[layouts/shortcodes/docs] に含まれるものについては、その傾向が強いです。
 
-ローカリゼーションしたショートコードを作成する必要がある場合は、`layouts/shortcodes/xx` に配置してください。ここで `xx` はローカリゼーション対象の言語コードを指します。
+ローカリゼーションしたショートコードを作成する必要がある場合は、`layouts/shortcodes/xx` に配置してください。
+ここで `xx` はローカリゼーション対象の言語コードを指します。
 その際、元の基本ショートコードと同じ相対パスを使用してください。
 
 [layouts/shortcodes/docs]: https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
@@ -101,7 +130,7 @@ Hugo は、サイトのローカリゼーション間で共有されるページ
 title: Your localized page title
 ...
 
-default_lang_commit: <commit-hash-of-main-for-default-language-page>
+default_lang_commit: <デフォルト言語の最新コミットハッシュ値>
 ```
 
 上述のフロントマターは `content/zh/<some-path>/page.md` です。
@@ -167,9 +196,9 @@ npm run check:i18n -- -n
 
 対応する英語のページに変更に合わせてローカリゼーションページを更新する際、`default_lang_commit` のコミットハッシュも忘れずに確認してください。
 
-{{% alert title="Tip" %}}
+{{% alert title="ヒント" %}}
 
-ローカリゼーションページが `main` の `HEAD` にある英語版と対応するようになった場合、フロントマター内のコミットハッシュの値を消去し、前のセクションであった `add` コマンドを実行して、`default_lang_commit` フィールドの値を自動的に更新してください。
+ローカリゼーションページが `main` の `HEAD` にある英語版と対応するようになった場合、フロントマター内のコミットハッシュの値を消去し、前のセクションであった **add** コマンドを実行して、`default_lang_commit` フィールドの値を自動的に更新してください。
 
 {{% /alert %}}
 
@@ -187,6 +216,11 @@ npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>
 
 {{% /alert %}}
 
+### 乖離の状況 {#drift-status}
+
+`npm run fix:i18n:status` を実行して、ローカライズ対象ページが原文から乖離した場合にフロントマターフィールド `drifted_from_default` を追加します。
+このフィールドは近いうちに、英語版のページと比較してドリフトしたページの上部にバナーを表示するために使われるようになります。
+
 ### スクリプトのヘルプ {#script-help}
 
 スクリプトの詳細は、`npm run check:i18n -- -h` を実行してください。
@@ -227,6 +261,30 @@ PR にローカリゼーションプロジェクトを開始するのに必要
 
 {{% /alert %}}
 
+## English-language maintainer guidance {#english-language-maintainer-guidance}
+
+### When link checking fails for non-English pages {#when-link-checking-fails-for-non-english-pages}
+
+英語は OpenTelemetry ウェブサイトのデフォルト言語です。 英語のドキュメントを追加、編集、再構成した後に、非英語ページのリンクチェックが失敗する可能性があります。 そのような場合は、以下を実行してください。
+
+<!-- markdownlint-disable blanks-around-fences -->
+
+- リンクを**修正しないでください**。それぞれの非英語ページは対応する英語のページの特定のコミット（フロントマターキーである `default_lang_commit` の Git コミットハッシュ）に関連づけられています。
+- 以下のフロントマター、1 つの以上のページがリンクエラーが発生している場合は最も近い祖先のファイルに非英語ページを無視するようにリンクチェッカーを設定してください。
+  ```yaml
+  htmltest:
+    # TODO: remove the IgnoreDirs once broken links are fixed
+    IgnoreDirs:
+      - path-regex/to/non-en/directory/contain/files/to/ignore
+      - path-2-etc
+  ```
+- `npm run check:links` を実行して、設定ファイル `.htmltest.yml` への変更を PR に含めてください。
+
+<!-- markdownlint-enable blanks-around-fences -->
+
+[front matter]: https://gohugo.io/content-management/front-matter/
 [main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
+[maintainers]: https://github.com/orgs/open-telemetry/teams/docs-maintainers
 [multilingual framework]: https://gohugo.io/content-management/multilingual/
 [PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files
+[slack]: https://slack.cncf.io/
