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

非英語ローカリゼーションのサイトページの作成と管理

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

翻訳のガイド

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

要約

✅ すべきこと

翻訳
- 以下を含むページの内容
  - Mermaid diagramのテキストフィールド
  - コードスニペット内のコメント（オプション）
- フロントマター内の title、 linkTitle、 description のフィールド値
- 特別な指示がない場合、ページ内の すべての コンテンツとフロントマターの内容
原文の内容、意味、 スタイル を 変更しないこと
小さなプルリクエストで 段階的に作業を提出すること
もしなにか疑問等があれば、以下の方法でメンテナーに 質問すること
- Slack の #otel-docs-localization か #otel-comms の各チャンネル
- Discussion やイシュー、あるいは PR コメント

❌ すべきでないこと

翻訳
- TIP、WARNING などのアラートタイプ。これは MARKDOWN linter ルールによって強制されます。
- コードブロックとインラインコード（この inline code example のようなもの）を含むコード
- このレポジトリ内のリソースの ファイルやディレクトリ の名前
- すべきことで指示されていないフロントマターのフィールド。特に、aliases は翻訳しないこと。よくわからない場合はメンテナーに質問すること。
- リンク。これには見出し ID ¹ が含まれます
- notranslate（通常は CSS クラスとして）でマークされた Markdown の要素、特に見出しに対して
アセット内のテキストをローカライズする場合以外で 画像やその他のアセットのコピー をすること。
新規に追加したり変更すること
- 原文で意図した意味と異なる内容
- 表示の スタイル。たとえば フォーマット、レイアウト、デザイン スタイル（タイポグラフィ、文字の大文字小文字、空白など）。

AI ツールの使用

翻訳を支援するために生成 AI ツール（ChatGPT、Gemini など）を使用する場合は、OpenTelemetry Generative AI Contribution Policy と Linux Foundation Generative AI Policy にしたがう必要があります。特に、次の点に注意してください。

プルリクエストテンプレートの該当するチェックボックスをオンにして、AI を使用したことを開示する。
すべての AI 生成翻訳の正確性をレビューして検証する。提出するコンテンツにはあなたが責任を負います。
自分でレビューおよび検証できない AI 生成翻訳（たとえば、自分が十分に習熟していない言語での提出）は提出しない。これは大きなレビューボトルネックを生み出すため、メンテナーの負担を抑えるために PR がクローズされる可能性があります。

見出しID

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

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

リンク

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

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

注記

OTel ウェブサイトのリポジトリには、Hugo がドキュメントページを参照する絶対リンクパスを変換するために使用するカスタムの render-link フックがあります。 /docs/some-page 形式のリンク は、リンクをレンダリングするときに、パスの先頭にページの言語コードを付けることで、ロケール固有になります。たとえば、先ほどのサンプルのパスは、日本語のページからレンダリングされた場合には /ja/docs/some-page となります。

リンク定義ラベル

ロケールの著者は、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

画像とその他のアセット

ファイル自体のテキストをローカライズする場合を除き、画像、動画、その他のコンテンツ以外のアセットファイルのコピーを 作成しない でください。
- Hugo は、サイトのローカリゼーション間で共有される画像ファイルをレンダリングする方法についてスマートです。つまり、Hugo は 単一の 画像ファイルを出力し、それをロケール間で共有します。詳細は Page bundles を参照してください。
- これは LOCALIZATION guidelines チェックによって強制されます。
Mermaid ダイアグラム内のテキストは 翻訳して ください。

インクルードファイル

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

ショートコード

注記

2025 年 2 月現在、私たちは共有ページのコンテンツをサポートする手段として、ショートコードからインクルードファイルへの移行を進めています。

一部の基本ショートコードには英語のテキストが含まれており、ローカリゼーションが必要になる場合があります。特に、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
> Drifted file: content/zh/docs/platforms/kubernetes/_index.md
...
DRIFTED files: 361 out of 990

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

npm run check:i18n -- content/zh

変更の詳細をみる

更新が必要なローカリゼーションページについて、diff サブコマンドとローカリゼーションページへのパスを指定して差分を見ることができます。たとえば、以下のようになります。

$ npm run check:i18n -- diff content/zh/docs/platforms/kubernetes
# content/zh/docs/platforms/kubernetes/_index.md: drifted from 1ca30b4d
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 -- commit 1ca30b4d --new content/ja
npm run check:i18n -- commit HEAD --new content/zh/docs/concepts

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

npm run check:i18n -- --new

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

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

ヒント

ローカリゼーションページが main の HEAD にある英語版と対応するようになった場合、npm run check:i18n -- commit HEAD <PATH-TO-YOUR-PAGE> を実行してください。 default_lang_commit のハッシュが更新され、ページの乖離の状況も同時にクリアされます。

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

npm run check:i18n -- commit <HASH> <PATH-TO-YOUR-UPDATED-FILES>
npm run check:i18n -- commit HEAD <PATH-TO-YOUR-UPDATED-FILES>

重要

HEAD をハッシュ指定子として使用すると、スクリプトはローカル環境における main の HEAD のハッシュを使用します。 main を GitHub 上の HEAD に対応したい場合、必ず main のフェッチとプルをしてください。

ローカリゼーションページへのパッチ適用

ビルドの修正では、ローカリゼーションページを英語の対応ページと同期せずに編集する必要がある場合があります。たとえば、共有のショートコードが変更された後にショートコードの呼び出しを修正する場合です。修正がロケールをまたぐかどうかにかかわらず、この方法で修正されたローカリゼーションページはパッチ済みとしてマークしてください。

修正に必要な編集のみを行い、ページに他の変更を加えないでください。
ページの default_lang_commit 行の末尾に # patched YAML コメントを追加してください。
```
default_lang_commit: abc4567... # patched
```

このマーカーはこのような機械的な修正に限定されており、意味的な変更では使用しません。このマーカーは、ページが同期されずに修正されたことをそのページのロケールチームに伝えます。ハッシュ値は最後の同期ポイントを記録したままです。マーカーは、ページのハッシュが次に更新された際に削除されます。

乖離の状況

フロントマターフィールド drifted_from_default は、ローカリゼーションページが乖離していることを示します。このフィールドが設定されたページの上部には「outdated」バナーが表示され、リンクチェッカーがそのページをスキップするため、乖離したページの古いリンクが CI を失敗させることがなくなります。リンクチェッカーはこのフィールドを待たずに、最後のツリー全体のステータス同期以降に変更された英語ページのロケールコピーも乖離保留としてスキップします。

毎日の Housekeeping 実行がツリー全体でこのフィールドを同期します。 PR は変更しないページの乖離状況を更新しません。 PR が変更する各ページは、I18N check が要求するとおり、正確な乖離状態で PR から出る必要があります。ページを英語の対応ページと同期してピンを更新するか（ステータスは同じ書き込みでクリアされます）、残りの乖離を npm run fix:i18n:status -- <PATHS> で記録してください。ピンは main 上のコミットのみを指すことができるため、同じ PR で行われた英語の変更に同期したページは、それらの変更がマージされるまで残りの乖離を記録します。

スクリプトのヘルプ

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

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

OTel ウェブサイトの新しいローカリゼーションを始めることに興味がありますか？メンテナーにあなたの興味を伝えましょう。たとえば、GitHub ディスカッションや Slack の #otel-docs-localization チャンネルを経由することが挙げられます。このセクションでは、新しいローカリゼーションを開始する際の手順について説明します。

注記

新しいローカリゼーションを開始するために、OpenTelemetry プロジェクトの既存のコントリビューターである必要はありません。しかし、OpenTelemetry GitHub organization のメンバーまたはローカリゼーションの承認者グループのメンバーとして追加されるには、メンバーシップガイドラインに概説されている確立されたメンバーおよび承認者になるための要件を満たす必要があります。

承認者ステータスを獲得する前は、ローカリゼーション PR への承認を「LGTM」（Looks Good To Me）コメントを追加することで示すことができます。この立ち上げ段階では、メンテナーはあなたがすでに承認者であるかのようにあなたのレビューを扱います。

1. ローカリゼーションチームを結成する

ローカリゼーションの作成は、活発で支援的なコミュニティを育てることです。 OpenTelemetryウェブサイトの新しいローカリゼーションを始めるには、以下が必要です。

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

2. ローカリゼーションのキックオフ：イシューを作成する

ローカリゼーションチームが配置されているか結成されている場合は、以下のタスクリストを使用してイシューを作成します。

追加したい言語の公式ISO 639-1 コードを調べてください。このセクションの残りの部分では、この言語コードをLANG_IDと呼びます。特にサブリージョンの選択に関して、使用するタグについて疑問がある場合は、メンテナーに尋ねてください。
メンターと潜在的なコントリビューターのGitHubのハンドルネームを特定してください。

冒頭コメントに以下のタスクリストを含む新しいイシューを作成してください。

- [ ] 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 (only) to YOUR_LANGUAGE_NAME and submit a PR.
      For details, see
      [Localize the homepage](https://opentelemetry.io/docs/contributing/localization/#homepage).
- [ ] OTel maintainers:
  - [ ] Update Hugo config for `LANG_ID`
  - [ ] 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`
- [ ] Create an issue to track the localization of the **glossary**. Add the
      issue number here. For details, see
      [Localize the glossary](https://opentelemetry.io/docs/contributing/localization/#glossary).

3. ホームページをローカライズする

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

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

4. 用語集をローカライズする

ローカライズする2番目のページは用語集です。これは、特にオブザーバビリティとOpenTelemetryで使用される主要な用語を定義するため、ローカライズされた読者にとって重要なページです。これは、あなたの言語にそのような用語が存在しない場合は特に重要です。

ガイダンスについては、Write the Docs 2024でのAli DowairのトークThe art of translation: How to localize technical contentの動画を参照してください。

5. 残りのサイトページを小さな増分でローカライズする

用語が確立されたら、残りのサイトページをローカライズできます。

小さな PR を提出する

ローカリゼーションチームは、小さな増分で作業を提出する必要があります。つまり、PR は小さく保ち、できれば 1 つまたは少数の小さなファイルに限定してください。小さな PR はレビューが簡単で、通常はより早くマージされます。

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

Hugo

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

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

スペルチェック

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

辞書が利用できる場合:
- 開発依存関係として NPM パッケージを追加します。例: npm install --save-dev @cspell/dict-bn
- .cspell.yml で、パッケージの cspell-ext.json を import: の下に追加し、辞書の ID（たとえば bn、es-es、pl_pl）を dictionaries: の下に追加します。
その言語の辞書が利用できない場合は、その言語の import を追加しないでください。 cSpell がそのロケールの Markdown を英語としてスペルチェックしようとしないように、.cspell.yml の ignorePaths リストに content/LANG_ID を追加します。

単語リスト

スペルチェックで追加する自然言語辞書がない場合でも、新しいロケールごとに .cspell/LANG_ID-words.txt を作成します（最初は空で構いません）。

.cspell.yml で、このファイルを登録して有効化します。
- dictionaryDefinitions の下に、name（たとえば LANG_ID-words）と path（たとえば .cspell/LANG_ID-words.txt）を持つエントリを追加します。
- dictionaries の下に、上記のステップと同じ name の値を追加します（ファイルパスではありません）。

その他のツールサポート

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

承認者およびメンテナー向けガイダンス

ロケール限定の PR で自動マージを有効にする

ロケールのメンテナーチームのメンバーは、ロケール限定の PR に対して /auto-merge（または /auto-merge:enable、無効にするには /auto-merge:disable）とコメントすることで GitHub の自動マージを有効にできます。このディレクティブは、先頭にテキストや空白がない独立した行に記述し、コメントの最初または最後の非空白行として配置する必要があります。指定は最大 1 回までです。たとえば、次のように記述できます。

LGTM
/auto-merge

これにより、確立されたローカリゼーションチームがドキュメントメンテナーを待つことなく自分たちの PR をマージできるようになります。 GitHub、ブランチ保護、CODEOWNERS ルールは引き続きマージを制御しており、PR はすべての必要なレビューが完了しチェックが通った場合にのみマージされます。

自動マージコメントは、変更されたすべてのファイルがあなたがメンテナンスしているロケールに属している場合にのみ受け入れられます。そのため、共有コンテンツや英語コンテンツの変更には使用できません。適用条件とコマンドの詳細は、ヘルパー README を参照してください。

PR は複数のロケールにまたがるべきではない

一般的な原則として、PR は複数のロケールにまたがるべきではありません。つまり、変更するページは最大で 1 つのロケールに限定すべきです。唯一の例外はこのセクションで説明します。

意味的な変更

承認者は、ドキュメントページに意味的な変更を加えるPRが複数のロケールにまたがらないようにする必要があります。意味的な変更とは、ページコンテンツの意味、つまり読者が理解し行動する内容に影響を与える変更です。コードブロック、コマンド、設定サンプルもそのコンテンツの一部です。これらは翻訳しませんが、それらへの編集は同様に意味的な変更です。私たちのドキュメントのローカリゼーションプロセスにより、ロケールの承認者は、時期を見て、英語の編集内容を確認し、その変更がそのロケールに適切かどうか、およびそのロケールにどのように組み込むのが最善かを判断します。変更が必要な場合、ロケールの承認者は独自のロケール固有のPRを通じて変更を行います。

コンテンツに影響しないメンテナンス

ロケールをまたぐルールはページのコンテンツを対象としています。メンテナーは、サイト全体のツール、設定、フロントマター、マークアップの更新を含む、ロケールをまたがざるを得ない、コンテンツに影響しない変更を提出することがあります。これには乖離状況の記録管理（自動化された PR と手動のステータスのみの編集の両方）も含まれます。このような変更はローカリゼーションページの意味を変更しません。

ビルドをグリーンに保つ

ローカリゼーションページのコンテンツを変更する PR が複数のロケールにまたがることが許されるのは、サイトのビルドをグリーンに保つために厳密に必要な場合のみです。このようなビルドの修正は、共有のショートコード、インクルードファイル、データソースの変更後などに、ローカリゼーションページのサイトビルドの破損を修復します。ページの乖離状況はリンクチェックからのみ保護し、Hugo のビルドからは保護しません。修正したすべてのローカリゼーションページをパッチ済みとしてマークしてください。

ローカリゼーションページでのリンクチェックの失敗はこれに該当しません。解決方法についてはリンクの修正とリソースの更新を参照してください。

乖離状況の記録管理にも同じ最小限の修正ルールが適用されます。失敗するチェックが drifted_from_default の更新を要求している場合、そのチェックが報告するページのみを更新してください。毎日の Housekeeping 実行が残りを完了させます。ステータスのみの編集はコンテンツに影響しないメンテナンスです。

ローカリゼーションページのコンテンツへのその他の変更は、そのロケールにとっての意味的な変更として扱ってください。これには、乖離したページへの対象を絞ったコンテンツの追加（新しい用語集の用語の追加など）も含まれます。

リンクの修正とリソースの更新

英語のドキュメントへの変更により、非英語のロケールでリンクチェックの失敗が発生することがあります。これはドキュメントページやそのセクションが移動または削除された場合に発生します。移動した外部リソースへのリンクも同様に失敗する可能性があります。このような失敗は英語のページでのみ修正してください。 リンクを修正するためにローカリゼーションページのコンテンツを編集しないでください。乖離の追跡が古くなったローカリゼーションのコピーをロケールチームにフラグを立て、リンクの修正を含む調整は各チームに委ねられます。

まず、英語側で失敗しているリンクを修正して影響を封じ込めてください。リンクターゲットの状況によっては追加の緩和策があります。

ページが移動された場合：移動された英語ページが古いパスの alias を宣言していることを確認してください。 alias は以前公開されたリンクを機能させ続けますが、サイト訪問者に対してのみです。 alias はサーバーサイドリダイレクトとして公開され、リンクチェッカーはビルドされたサイトの正規ページパスに対してリンクを解決します。そのため、古いパスへのリンクは英語のページでも修正が必要です。
セクションがページ内で移動された場合：セクションへのリンクが機能し続けるよう見出し ID を保持してください。 alias はページパスをリダイレクトするため、フラグメントには対応できません。

その他の状況（セクションが別のページに移動された場合、外部リソースが移動された場合、ターゲットが削除された場合）には、このような緩和策はありません。英語のリンクを修正することが英語側の修正のすべてです。削除されたターゲットの場合、リンクしている各ページで代替のターゲットを選択するかリファレンスを削除することを意味します。

次に、乖離の処理にローカリゼーションページを任せてください。英語のページを修正するとそのローカリゼーションされたコピーが乖離し、リンクチェッカーは乖離したコピーをスキップします。ローカリゼーションページのリンクチェックがまだ失敗する場合は、乖離状況を直接更新してください。

npm run fix:i18n:status -- PATHS_TO_FAILING_LOCALIZED_PAGES

まれに、ローカリゼーションページにのみ存在する失敗リンクがある場合は、報告してそのロケールチームと連携して修正してください。

最後に、npm run check:links を再実行して、リンクの失敗が残っていないことを確認してください。

ありえる例外に関してはリンクを参照のこと。 ↩︎

フィードバック

このページは役に立ちましたか?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最終更新 August 12, 2026: [ja] update translation of content/en/docs/contributing/localization.md (#11273) (c9b84167)