サイトのローカリゼーション
OTel のウェブサイトは、ページのローカリゼーションをサポートするために、Hugo の multilingual framework をサポートしています。 デフォルトの言語は英語であり、米国英語がデフォルト（暗黙の）ローカリゼーションとして設定されています。 対応する言語の数は増えており、トップナビゲーションの言語ドロップダウンメニューから確認できます。
英語メンテナーガイド
非英語ページのリンクチェックが失敗したとき
英語は OpenTelemetry ウェブサイトのデフォルト言語です。 英語のドキュメントを追加、編集、再構成した後に、非英語ページのリンクチェックが失敗する可能性があります。 そのような場合は、以下を実行してください。
- リンクを修正しないでください。それぞれの非英語ページは対応する英語のページの特定のコミット（フロントマターキーである
default_lang_commitの Git コミットハッシュ）に関連づけられています。 - 以下のフロントマター、1 つの以上のページがリンクエラーが発生している場合は最も近い祖先のファイルに非英語ページを無視するようにリンクチェッカーを設定してください。
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 に含めてください。
翻訳ガイダンス
ページの翻訳の際には、本セクションのガイドに従うことを推奨します。
見出しアンカー
見出しを翻訳する際に、見出しアンカーのターゲットをローカリゼーション全体で統一するために、以下に従ってください。
- 見出しに明示的な ID がある場合は、それを保持する。見出し ID の記法 は
{ #some-id }のように、見出しテキストの後に記述されます。 - そうでない場合は、元の英語の見出しに対して自動生成された ID に対応する明示的な ID を宣言する。
Note
翻訳ページのすべての見出しに明示的な見出し ID を追加するか、リンクチェッカーで報告された既知のサイト内見出しターゲットにのみ追加するかは、ローカリゼーションの執筆者の裁量に委ねられます。 前者の方法は一貫性が保たれますが、作業量が増えます。 しかし、サイト外からローカリゼーションされたページのリンクをより適切にサポートでき、新しい見出しターゲットが追加された際に、過去の翻訳ページを修正する手間を減らすことができます。リンク
ローカルパスへ参照しているリンク（外部リンクではなく）は、そのパスのままにしてください。 これは、ウェブサイトのページへのリンクや、画像などのセクション内リソースへのリンクにも当てはまります。
Note
OTel ウェブサイトリポジトリには、Hugo が使用する絶対リンクのパスをドキュメントのページに変換するカスタムレンダーリンクを持っています。/docs/some-page のようなリンクは、リンクをレンダリングする際にページの言語コードがパスの先頭に追加され、ローカリゼーションされます。
たとえば、日本語ページからレンダリングされた際に、このサンプルのパスは /ja/docs/some-page になります。画像
Hugo は、サイトのローカリゼーション間で共有されるページ画像をレンダリングする際に、効率的な処理を行います。 つまり、生成されたサイトフォルダ内では、Hugo は 1 つの画像ファイルを出力し、それを各ローカリゼーションで共有します。
したがって、一般的なルールとして、実際に画像を変更しない限り、ローカリゼーション用に画像のコピーを作成しないでください。
ショートコード
一部の基本ショートコードには英語のテキストが含まれており、ローカリゼーションが必要になる場合があります。 特に、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: <commit-hash-of-main-for-default-language-page>
上述のフロントマターは 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 のコミットハッシュも忘れずに確認してください。
Tip
ローカリゼーションページがmain の HEAD にある英語版と対応するようになった場合、フロントマター内のコミットハッシュの値を消去し、前のセクションであった add コマンドを実行して、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>
重要
HEAD をハッシュ指定子として使用すると、スクリプトはローカル環境における main の HEAD のハッシュを使用します。
main を GitHub 上の HEAD に対応したい場合、必ず main のフェッチとプルをしてください。スクリプトのヘルプ
スクリプトの詳細は、npm run check:i18n -- -h を実行してください。
新しいローカリゼーション
OpenTelemetry ウェブサイトの新しい言語のローカリゼーションを始めるには、コントリビュートの興味を共有するためにイシューを起票してください。 追加したい言語において翻訳の執筆とレビューをしたい他のメンバー全員をタグ付けしてください。 最低でも 2 名の潜在的なコントリビューター（理想的には 3 名）が必要です。 また、イシューに以下のタスクリストも含めてください。
- [ ] Contributors for the new language: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
- [ ] Localize site homepage to YOUR_LANGUAGE_NAME
- [ ] Create an issue label for `lang:LANG_ID`
- [ ] Create org-level group for `LANG_ID` approvers
- [ ] Update components owners for `content/LANG_ID`
- [ ] Set up spell checking, if a cSpell dictionary is available
注意。
- 追加したい言語の
LANG_IDには公式の ISO 639-1 コード を使用してください。 - cSpell 辞書 を探し、NPM パッケージとして利用可能な @cspell/dict-LANG_ID を確認してください。 もし指標する方言や地域に適した辞書がない場合は、最も近い地域のものを選んでください。 設定方法の例については、PR #5386 を参照してください。
そのイシューを作成し、必要な人数のコントリビューターが集まったら、メンテナーがインデックスページの翻訳を含むプルリクエストを作成するように依頼します。 PR にローカリゼーションプロジェクトを開始するのに必要な追加変更を加えるために、メンテナーが PR を編集できることを確認してください。
最初の PR がマージされると、メンテナーがイシューラベル、組織レベルのグループ、およびコンポーネント所有者の設定を行います。
重要
新しいローカリゼーションを始めるのに、OpenTelemetry プロジェクトの既存のコントリビューターである必要はありません。 しかし、OpenTelemetry GitHub 組織 のメンバーまたはローカリゼーションの承認者グループに追加されることはありません。 確立されたメンバーまたは承認者になるには、メンバーシップガイドライン に記載されている要件を満たす必要があります。
ローカリゼーションプロジェクトを始める時には、メンテナーはあなたのレビューをすでに承認者であるかのように扱います。
フィードバック
このページは役に立ちましたか?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!