OpenTelemetryの 公式ドキュメント日本語化プロジェクトにコミットする一連の流れ

概要

本記事では、OpenTelemetry 日本語化プロジェクトにより気軽に参加するために、より具体的な手順について解説していきます。
自身が、OpenTelemetry 日本語化プロジェクトに参加して、コントリビューション関連のページの翻訳と DRIFTED files（後述）の更新を一通り終えた後の経験をもとに作成しました。
より多くの人に関わってもらいたので記事を作成しました。

本記事の内容は、この記事を公開（更新）した時のものです。
翻訳の状況や方法（特にスクリプト周り）は常に更新されている可能性があります。
差異があった場合は、open-telemetry/opentelemetry.io のコントリビューションに従ってください。

先に読んでおいた方が良いコンテンツ

先に次の 2 のコンテンツを読みましょう。

• コントリビューション
  • OpenTelemetry 公式ドキュメントが公開している、ドキュメントにコントリビュートするガイドラインが一通り記載されています
  • 特にサイトのローカリゼーションを読みましょう
  • ほかのページもすべて翻訳済みまたは翻訳中です。
• OpenTelemetry の公式ドキュメント日本語化プロジェクトのメンバーを募集しています
  • @ymotongpoo さんのブログです
  • 翻訳プロジェクトに加えて、参加しておくと何かと便利な CNCF の Slack と Observability Japan の Discord のリンクが貼られているので、ぜひ参加してください

この 2 つのドキュメントが理解できれば、開始するのに十分です。
本記事では、心理的なハードルを下げるために、より具体的かつ簡易的な手順や詰まりがちなポイントについて記載します。

簡易的な翻訳手順

リポジトリを fork して clone

一般的な OSS へコミットする方法と同様です。
open-telemetry/opentelemetry.io を fork して clone して、作業ブランチを作成しましょう。
公式ドキュメントでは、コンテンツの提出のローカルで作業するにより詳細が記述されています。

翻訳（更新）ページを見つける

翻訳プロジェクトには、未翻訳のページか、DRIFTED file を見つけます。
DRIFTED file とは、翻訳が原文のバージョンよりも古く、更新が必要なページのことを指します。
以下はそれぞれの探し方です。
どちらの方法で探すとしても、PR がまだ作成されていないことを確認しましょう。

対象ページ	見つけ方
未翻訳のページ	リポジトリの content/en にあって、content/ja に存在しないファイルを探すか、日本語の OTel のドキュメントでヘッダに You are viewing the English version of this page because it has not yet been fully translated. のページを見つける
DRIFTED file	npm run check:i18n -- content/ja を実行して、表示されたファイルのパスが Drifted file のパスです

Drifted file が存在する場合、npm run check:i18n -- content/ja の実行結果は次のようになります。

実行結果例

> npm run check:i18n -- content/ja

> check:i18n
> scripts/check-i18n.sh content/ja

Processing paths: content/ja
> Drifted file: content/ja/docs/what-is-opentelemetry.md
> Drifted file: content/ja/docs/collector/deployment/agent.md
> Drifted file: content/ja/docs/collector/deployment/gateway/index.md
> Drifted file: content/ja/blog/2025/ai-agent-observability/index.md
DRIFTED files: 4 out of 63

Drifted file のパス（$FILE_PATH）に対して、npm run check:i18n -- -d $FILE_PATH を実行すると、差分を確認できます。
また、delta コマンドにパイプでつなぐこともできます。
delta の side-by-side を有効化して、の npm run check:i18n -- -d $FILE_PATH | delta と差分が見やすいです。
以下の画像は一例です。

翻訳

対象ページを決めたら、翻訳にとりかかります。
日本語化プロジェクトのお作法的な事をここで紹介します。
こちらの内容は、筆者が観測したものをもとに記載しているので、あくまで非公式です。
docs-ja-approvers（日本語化プロジェクトの PR をアプルーブする方々）の指示に従ってください。

漢字をひらく

一部の漢字は漢字ではなくひらがなで書きます（「漢字をひらく」と呼ばれる）。
以下は一例です。
ほかの翻訳ページを参考にしつつ、実践してください。

• 例えば -> たとえば
• 全て -> すべて

参考: 漢字をひらく（開く）とは？わかりやすい文章を書くために必須な表記ルールの基本。

見出し ID の付与

見出し ID は見出しごとに、{#header-id} といった形式で付与するものです。
該当の見出しをクリックすると、見出し ID がアンカーリンクになります。
ほかのサイトから参照する際のリンクや、対象の言語では未翻訳の場合に、原文ページの該当する見出しに対して遷移するためのアンカーリンクになります。

具体的には、日本語のコントリビューションページでは次にような見出し ID（{#jump-right-in}）が付与されています。

「コントリビューション」ページの見出し ID の一例

OpenTelemetry のドキュメントと Web サイトのコントリビューションに興味を持っていただきありがとうございます。

## 今すぐ飛び込んでみよう! {#jump-right-in}

何がしたいですか?

原文の Markdown に記載されていたら、そのまま利用します。
存在しなかったら、下図のように原文の見出しを選択した際に、 URL に表示されるアンカーリンクを利用してください。

:（コロン）

英語では文末に:（コロン）が多用されますが、日本語にはない表現ですのですので、ほかの記号や単語で書き換えてください。
例外として、文中の:は許可されます。具体的には example: が 例: となったりします。

default_lang_commit

翻訳ページは、原文との差分を検知するために、Markdown の Front Matter に default_lang_commit を付与します。

default_lang_commit の一例

default_lang_commit: COMMIT_ID

まずは、フォークしたローカルの main ブランチを upstrem の main ブランチの最新の状態にしてください。
そして、翻訳を新規作成した場合はそのままの状態で、Drifted file を修正した場合は既存の default_lang_commit を削除してから以下のコマンドを実行してください。
$FILE_PATH は翻訳対象のファイルを指定してください。

default_lang_commitを付与するコマンド

npm run check:i18n -- -n -c HEAD $FILE_PATH

Front Matter には cSpell が存在する場合があります。
cSpell より後に書くと lint が落ちるので、cSpell がある場合は default_lang_commit を cSpell の前に書いてください。

default_lang_commit を書く順番

default_lang_commit: COMMIT_ID # cSpell より先に書く
cSpell:ignore: IGNORE_WRODS

Drifted file の差分をコマンドで確認しながら、更新をしている場合はすべての更新を終えた後に default_lang_commit を更新することを推奨します。
理由は、npm run check:i18n -- -d コマンドは、ページの default_lang_commit とローカルの main ブランチのコミット ID を比較しているためです。
先に更新してしまうと npm run check:i18n -- -d $FILE_PATH で差分が見られなくなってしまいます。

PR の作成

CLA の署名（初回のみ）

初めて PR を作成すると PR のメッセージに EASY CLA への署名が求められます。
EASY CLA とは OpenTelemetry の公式ドキュメントにコミットするための署名です。
合わせてリンク（ボタン）も表示されるので、画面遷移して手順に従って登録してください。
この作業は最初の PR だけ必要です。

レビュー、承認、マージ

日本語ページを翻訳すると labels に lang:ja が自動付与されて、docs-ja-approvers と docs-approvers にレビューの通知が飛びます。
docs-ja-approvers のアプルーブを得てから、docs-approvers のアプルーブを得るといった流れですので、レビューコメントをもらったら都度対応していきましょう。
docs-approvers から承認したらマージも docs-approvers がします。

まとめ

以上が OpenTelemetry の公式ドキュメント日本語化プロジェクトの一連の流れになります。
本記事を作成した時点で、OpenTelemetry のドキュメントやブログの翻訳済または進行中のページは 60 ページ程度ですが、原文のページは 500 ページ近くあります。
まだまだ翻訳対象のページが残っているので、興味がある方はぜひ参加してみてください。