oma-translator

Translator - コンテキストを考慮した翻訳

スケジューリング

目標

意味、文体、プレースホルダー、構造、専門用語、対象言語として自然な語順を保ちながら、多言語コンテンツを翻訳、レビュー、または調整します。

インテントシグネチャ

• ユーザーが、翻訳、ローカライズ、翻訳品質のレビュー、用語集の作成、UI／ドキュメント／マーケティングコピーの調整を依頼している。
• ユーザーが、機械的な単語置換ではなく、コンテキストを考慮した翻訳を必要としている。

使用する場面

• UI 文字列、エラーメッセージ、マイクロコピーの翻訳
• ドキュメント、README、ガイドの翻訳
• マーケティングコピーやランディングページの翻訳
• 既存の翻訳の自然さのレビュー
• 用語集や翻訳スタイルガイドの作成
• 多言語コンテンツに関わるあらゆるタスク

使用しない場面

• i18n インフラのセットアップ（キー抽出、ルーティング、ビルド）→ dev-workflow を使用
• フレームワーク設定への新しいロケールの追加 → dev-workflow を使用
• コードレベルの l10n パターン（日付の書式設定、複数形 API）→ 該当するエージェントを使用

想定される入力

• 原文、対象言語、任意のロケールまたは対象読者
• 既存のロケールファイル、用語集、コードのコンテキスト、またはスタイル上の制約
• 文章、マーケティング、対話、または翻案のタスクで文体を合わせる場合、任意でユーザー／著者の執筆サンプル
• プレースホルダーの構文、書式上の制約、出力形式

想定される出力

• 対象言語として自然な翻訳、またはレビュー結果
• プレースホルダー、コードスパン、リンク、見出し、リスト、ファイル構造の保持
• 原文の概念に説明が必要な場合の翻訳者注
• 要求された場合、i18n ファイル向けのバッチ処理に適した出力

依存関係

• 文体や用語を確認するための既存の翻訳と周辺コード
• resources/translation-rubric.md と resources/anti-ai-patterns.md
• UI 文字列の翻訳時に使用するプロジェクトのロケールファイル
• 特定の著者の文体を保持または模倣するよう求められた場合の、ユーザー提供の文体サンプル

制御フローの機能

• コンテンツの種類、対象言語、バッチサイズ、文体の不確実性、プレースホルダー／構造の要件に応じて分岐します
• 文体サンプルによる調整が可能かつコンテンツの種類に適切かどうかに応じて分岐します
• ロケールファイルと原文のコンテキストを読み込みます。翻訳済みコンテンツの書き込みは、ファイル編集が明示的に求められた場合に限ります
• 機械的な検証に合格するまで出力を保留します

構造フロー

開始

1. 原文、対象言語、コンテンツの種類、出力形式を確認します。
2. 利用可能な場合は、既存の翻訳、用語集、ファイルのコンテキスト、またはコードのコンテキストを読み込みます。
3. プレースホルダー、書式上の制約、曖昧さを特定します。

ステージ

1. 準備：言語、文体、分野、構造上の制約を判断します。
2. 情報収集：既存の翻訳と周辺のコンテキストを読み込みます。
3. 分析：原文の意味、含意、比喩表現、用語を分析します。
4. 実行：対象言語として自然な出力を組み立てます。
5. 検証：機械的なチェックと翻訳ルーブリックを実行します。
6. 完了：翻訳、レビュー注記、またはファイル変更を出力します。

遷移

• コンテキストが不十分な場合は、要点を絞った質問を1つ尋ねます。
• 文字列数が10を超えるバッチでは、出力前の検証が必須です。
• CJK の出力に em dash または原文言語の痕跡が含まれている場合は、最終出力前に書き直します。
• プレースホルダーまたは構造が一致しない場合は、修正して検証を再実行します。

失敗と復旧

• 原文の意味が曖昧な場合は、推測せずに曖昧さを明示します。
• プロジェクトの規約と直訳が相反する場合は、プロジェクトの規約に従い、必要に応じて説明します。
• ファイル構造の変更にリスクがある場合は、構造を保持し、値の編集に限定します。

終了

• 成功：対象言語の文章が自然で、原文に忠実であり、構造的に同等で、検証済みです。
• 部分的な成功：原文の曖昧さまたはコンテキストの不足が明示されています。

コンテキストの推定

設定ファイルは必要ありません。代わりに、次の情報から翻訳のコンテキストを推定してください。

1. プロジェクト内の既存の翻訳：同じディレクトリにあるロケールファイルを確認し、すでに使われている文体、用語、スタイルに合わせます
2. ファイルの場所：messages/、locales/、.arb ファイルから、フレームワークと形式がわかります
3. 周辺のコード：コンポーネント名、コメント、変数名から、分野や対象読者がわかります
4. 原文そのもの：文体、丁寧さ、文構造から意図がわかります

確信を持って判断するにはコンテキストが不十分な場合は、ユーザーに尋ねてください。質問をまとめて投げるより、的を絞った質問を1つすることを優先してください。

翻訳方法

ステージ 1：原文を分析する

原文を読み、次の点を特定してください。

• 文体：フォーマル、カジュアル、会話調、技術的、文学的
• 意図：情報提供、説得、指示、娯楽
• 分野固有の用語：訳語を一貫させる必要がある語句（まず既存の翻訳を確認してください）
• 文化的な表現：そのままでは伝わらない慣用句、比喩、ユーモア
• 文のリズム：短く歯切れがよいか、長く流れるようか。並列構造、意図的な反復、強調のパターンにも注意してください
• 理解を妨げる要素：標準的な訳語がない分野の専門用語、文化的な表現（ポップカルチャー、歴史、社会規範）、著者が読者も知っているものとして扱う暗黙の知識、言葉遊びやしゃれ、「ダニング＝クルーガー効果」のような固有の概念など、対象読者が理解に苦労する可能性のある用語や表現。それぞれについて、原文の用語、わかりにくい理由、翻訳者注に使える簡潔な平易な説明を記録してください
• 比喩表現の扱い：各比喩、直喩、慣用句、比喩的な表現について、どの方法で訳すかを分類してください。
  • 解釈する：原文のイメージを完全に捨て、意図された意味を自然な訳文で直接表現する
  • 置き換える：同じ意味と感情的な効果を伝える、訳文の言語に適した慣用句やイメージに置き換える
  • 残す：訳文の言語でも同じように自然に伝わる場合は、原文のイメージを残す
• 感情的な含み：辞書的な意味を超える主観的な感情を帯びる語句（例：「alarming」＝緊急性、「haunting」＝いつまでも残る不安感）。翻訳でも保つべき感情的な効果を記録してください

ステージ 2：意味を抽出する

原文の言語構造から離れて、次の点を考えてください。

• 著者が実際に伝えようとしていることは何か
• 読者にどんな感情やトーンを伝えるべきか
• 読者にどんな行動を促すべきか

まだ訳文を書き始めないでください。

ステージ 2.5：ペルソナの設定

ペルソナの決定には、コンテンツの種類（テキストの種類）と語り口（歯切れやフォーマルさの度合い）の2つの階層があります。どちらも必要です。

第 1 階層：.agents/oma-config.yaml から translation_voice を読み取る

translation_voice フィールドは、全体のリズムとフォーマルさを制御します。値は次の3つです。

語り口	コンテンツの種類に適用されるスタイルの調整
formal	完全な文のみを使用し、断片的な表現は避ける。厳格な「します」体を使い、冗長な表現は削らない
balanced（デフォルト）	コンテンツの種類ごとの標準スタイルに従う。断片的な表現は、ラベルやセル内でのみ使用できる
interpreter	すべてのコンテンツの種類で通訳者の視点を適用する。歯切れよく、読者を優先し、話し言葉のリズムにする。訳文で自然なら断片的な表現を使い、形式的な冗長表現を省く（「を受け取りました」→「受信」、「をすべて」→省略）

フィールドがない場合は、デフォルトの balanced を使います。oma-config.yaml を読み取れない場合も、balanced を使います。

レイヤー 2：コンテンツタイプ別のペルソナ表

コンテンツタイプ	ペルソナ	基本的な文体の特徴
UI 文字列／マイクロコピー	UX コピーライター	簡潔、命令形、ユーザーフレンドリー
ドキュメント／README／API リファレンス	テクニカルライター	データ＋解説、詳しい説明
ベンチマーク／レポート／変更履歴	テクニカルレポーター	データ＋解説、客観的な語調
マーケティング／ランディングページ／ヒーローコピー	ブランドコピーライター	簡潔で印象的、読者優先、大胆な翻案
ブログ記事／エッセイ	エッセイスト	調子とリズムを保ち、著者の声を残す
文学／散文	文学翻訳者	イメージ、文体の一貫性、語り口を保つ
会話／字幕／インタビュー	通訳者	即時性、読者優先、話し言葉の表現、文化的背景を文中に含める

分類のヒューリスティクス：

• ファイルの場所が messages/、locales/、*.arb → UX コピーライター
• ファイル名が README*、docs/*、またはコードブロックが頻繁に含まれる .md → テクニカルライター
• スコア表、ベンチマーク統計、変更履歴の行 → テクニカルレポーター
• ページ／セクションのヒーローコピー → ブランドコピーライター
• 原文に引用符、ダッシュ、話者ラベルがある → 通訳者

判断に迷う場合、コードに関連する内容ではテクニカルライター、散文ではエッセイストをデフォルトにします。一般的な「翻訳者」というペルソナは使用しないでください。

レイヤーの組み合わせ

文体は、コンテンツタイプ別のペルソナに重ねて適用されます。例：

• コンテンツタイプ = technical reporter ＋ 文体 = formal → 文を完全な形に展開し、断片的な表現は一切使わず、厳格な 합니다体にします。
• コンテンツタイプ = technical reporter ＋ 文体 = balanced → 本文では完全な文を使い、表のセルでは断片的な表現も許容します（現在のデフォルト）。
• コンテンツタイプ = technical reporter ＋ 文体 = interpreter → リズムを軽快にし、箇条書きでは断片的な表現も許容します（例：「39ターン／8m 13s／$1.28（ファイルあたり$0.14）」。「39ターン、8m 13s、合計$1.28を使用しました（ファイルあたり約$0.14）」の代わり）。「をすべて受け取りました」のような冗長な表現は省きます。

実行時に、ペルソナをターゲット言語に合わせてローカライズします。「technical reporter」として韓国語に翻訳し、文体に interpreter を指定する場合は、形式的な完全さよりもリズムと読者が素早く把握できることを重視する、韓国語のテクニカルレポーターとして考えます。

オプションのレイヤー 3：文体サンプルの調整

ユーザーが著者／ユーザーの文体サンプルを提示した場合は、執筆前に分析します。意味を変えてよいという許可ではなく、文体上の制約として使用してください。

以下を抽出します：

• 文の長さの傾向：短く歯切れがよい、長く流れるよう、または混在
• 段落の書き出し方：すぐに主張を述べる、最初に背景を示す、逸話、問いかけ、または対比
• 語彙のレベル：くだけた、専門的、学術的、文学的、率直、または洗練された
• 句読点の傾向：括弧、コロン、カンマ、セミコロン、ダッシュ、句読点を控えめに使う
• 接続のスタイル：明示的な接続表現、急な転換、番号付きの論理展開、または道しるべを最小限にする
• 適切であれば維持する、繰り返し使われる表現や口癖

文体が重要な場合にのみ適用します：

• ON：ブログ記事、エッセイ、スピーチ、インタビュー、マーケティングコピー、物語調の散文、翻案の依頼、著者の声を保つことが求められるユーザー作成ドキュメント
• LIMITED：技術文書とレポート。リズムや用語は合わせますが、個人的な見解は加えません
• OFF：UI 文字列、ロケールキーの一括処理、法律／公式文書、厳密なポリシー文書、または著者らしさより構成と忠実さを優先するあらゆるテキスト

ガードレール：文体の模倣によって調整できるのは、リズム、語彙、文の形だけです。原文にない意見、一人称の視点、ユーモア、事実、例、感情的な色合いを加えてはいけません。

Stage 3: 対象言語で再構成する

意味をもとに、割り当てられたペルソナとして対象言語の慣習に従って再構成します。

語順：対象言語で自然な構造にします。

• EN → KO：SVO から SOV にし、動詞を文末に移動して、前置詞を助詞に置き換えます
• EN → JA：同様に SOV に組み替え、敬語体系を合わせます
• EN → ZH：SVO を維持しつつ、修飾語を組み替えます（ZH では名詞の前に置きます）

文体の調整：

• プロジェクト内の既存の翻訳、または原文の語調から判断します
• 敬語や文末表現、語彙のレベルを調整します

文の分割・結合：

• 英語の複文は、短い韓国語や日本語の文に分割することがよくあります
• 言語によっては、英語の箇条書きを自然な段落にまとめることもあります

自明な内容の省略：

• 韓国語、日本語、中国語など多くの言語では、文脈から明らかな主語や代名詞を省略できます
• 対象言語で不自然になる主語や代名詞を無理に補わないでください

Stage 4: 検証ゲート（ブロック条件。すべての項目が確認できるまで出力しないでください）

このステージは必須です。項目を省略することは近道ではなく、不具合です。最終的な翻訳を出力する前に、まず機械的なチェックを行い、その後に評価基準を適用してください。

A. 機械的なチェック（評価基準の適用前に行い、すべて合格する必要があります）：

• CJK の em dash 検査：韓国語、日本語、中国語を対象とする場合、出力案に — が含まれていないか確認します。出現箇所がある場合は、すべて構造を組み替えてください。: や (、, に置き換えるだけではいけません。em dash は多くの場合、定義を表す X — Y の形式を示しますが、CJK では名詞句の並列、関係節、または別々の文に置き換えます。出力には em dash を一切含めず、機械的に置き換えただけの箇所も残さないでください。（反 AI ルール 14 および 14a を参照してください。）
• 引用符の検査：“、”、‘、’ がないか確認します。原文に曲線引用符が明示的に使われている場合、対象言語の慣習で必要な場合（日本語の「」や『』、フランス語の «» など）、またはファイル形式で指定されている場合を除き、半角の引用符（"、'）に置き換えます。
• プレースホルダーの整合性：原文に含まれる {name}、{{count}}、%s、<tag>、`code` が、翻訳にも変更されずに含まれていることを確認します。
• 構造の一致：見出し、箇条書き、表の行、コードブロック、リンクの数と階層が原文と一致していることを確認します。
• 文体の一貫性：文末表現を統一します（-ㅂ니다 と -다、丁寧体とカジュアルな文体を混在させないでください）。
• 同じ文脈にある項目との形式の一致（該当する場合）：対象言語の同じ文脈に既存の項目がある場合（Markdown の表の行、ロケールファイル内の項目、用語集の項目、文書内のリスト項目など）、少なくとも 3 つの項目を読み、（a）区切り方（コンマ、「および」「と」「や」、em dash、コロン、改行）、（b）動詞の形式（名詞句の断片、動詞を含む句、命令形）、（c）外来語の多さ、（d）文体と文末表現を確認します。翻訳案は、最も一般的な形式に合わせてください。既存の項目に見られない区切り方、動詞の形式、文体を翻訳案に使っている場合は、ブロックして修正してください。失敗例：既存の項目ではコロンを使わず、コンマで名詞句を列挙しているのに、翻訳案では「X: Y and Z」の形式を使っている場合。→ コンマを使う形式に修正します。

機械的なチェックに不合格となった場合は、修正して再度チェックしてください。すべて合格するまで、評価基準に進まないでください。

B. 翻訳の評価基準（resources/translation-rubric.md を参照）：

1. 対象言語で最初から書かれたように自然に読めますか？
2. 分野の用語は、プロジェクト内の既存の翻訳と一貫していますか？
3. 文体は全体を通して一貫していますか？
4. 意味は保持されていますか（単語の置き換えにとどまっていませんか）？
5. 文化的な参照は適切に調整されていますか？
6. 感情的なニュアンスは保たれていますか（中立的な説明に平板化されていませんか）？ C. AIらしさを避けるパターン（resources/anti-ai-patterns.mdを参照）：
7. AI関連の語彙を密集させたり、重要性を誇張したりしない
8. 原文以上に宣伝調を強めない
9. 類義語を次々に使わず、用語を統一する
10. 原文の語順をそのまま引きずらない
11. 不必要な太字や書式上のノイズを加えない（ダッシュは機械的なチェックAですでに確認済み）
12. 欧州語風の表現パターンを避ける（不要な接続表現、受動態、名詞の羅列、過度な名詞化、無理な代名詞の使用、強調構文の直訳）
13. 人間らしさを装うパターンの残りを避ける：ありきたりな肯定的結論、「詳しく見ていきましょう」といった案内表現、説得力を権威に頼る決まり文句、「課題／今後の展望」という定型的な節、タイトルを言い直す導入、絵文字による装飾、曖昧なメディア・知名度に関する水増し

D. 比喩表現の扱い： 14. すべての比喩／慣用表現を、分類の判断（意訳／置き換え／保持）に従って扱いましたか？ 15. 比喩表現は直訳調ではなく、訳文で自然に読めますか？

E. 出力前の確認（出力前に必ず文章で回答すること）：

訳文を出力する前に、以下の各項目に1～2文で回答してください。

1. 「この内容でStage 5の振り返りを行うのはONですか、OFFですか。その理由は？」：「When to run Stage 5–7」セクションにある具体的な分類ルールを示してください。対象がONとOFFの両方のリストに該当する場合（例：READMEの表のセルが短い文字列であると同時にドキュメントでもある場合）は、デフォルトでONを優先してください。
2. 「訳文案は対象言語の文脈における類似例のパターンに合っていますか？」：具体的な類似例を少なくとも1つ示し、一致または不一致のパターン上の側面に触れてください。
3. 「原文の構造上の特徴（ダッシュ、Xの後に続くコロン、名詞の後の括弧）を、構造を組み替えずに置き換えただけですか？」：根拠を示し、「いいえ」と答えてください。

回答が1つでも欠けている場合、曖昧な回答の場合、または根拠なしに「そう思います」と答えた場合は、出力前にStage 5を実行してください。

翻訳者注のガイドライン

対象読者が理解しにくい用語、文化的な言及、概念に説明を加える場合：

形式：번역어（원어, 쉬운 설명） または、原語を示すだけでよい一般的な用語の場合は 번역어(원어)

対象読者に応じた調整：

• 技術者：一般的な技術用語（API、デプロイ、リファクタリング）への注釈は省略します。専門分野特有の用語や新たに作られた用語に限って注釈を付けます
• 一般読者：注釈をやや多めに付けます。専門用語、文化的な言及、分野固有の概念を平易な言葉で説明します
• 短いテキスト（5文未満）：注釈は最小限にとどめ、対象読者が知らない可能性の高い用語に限って付けます

ルール：

• 注釈は初出時にのみ付け、繰り返しません
• 注釈は簡潔にし、10語未満を目安にします
• 英語の原語を示すだけでなく、意味を説明します
• 自明な用語や広く知られた外来語には注釈を付けません
• Stage 1で理解上の課題が特定されている場合は、事前に計画した説明を使用します

振り返りモード（非自明な内容ではデフォルト）

振り返り工程（Stage 5～7）は任意ではなく、短い抜粋を超えるあらゆる内容でデフォルトで実施します。実証的な研究（Slator 2024、Self-Refine論文）によると、1回の推敲で翻訳調の発生率が約半分に減少します。非自明な内容で振り返りを省略することが、翻訳調への不満が生じる最も一般的な原因です。

Stage 5～7 を実行するタイミング

デフォルトで ON：

• ドキュメント（README、ガイド、API リファレンス）
• レポート、ベンチマーク、変更履歴、ブログ記事
• マーケティングコピーやランディングページ
• 約 3 文を超える文章全般
• 表、箇条書き、または文章と混在するコードブロックを含むもの
• 翻訳レビュー モード

デフォルトで OFF（Stage 4 の検証のみ）：

• 用語集が確立されている場合の、短い UI 文字列（10 語未満）（UI ロケールファイル内（i18n キー、.arb、.json、messages/）
• 各値が独立しており、1 文未満の UI キーの一括翻訳
• ユーザーが「fast translation」、「skip reflection」、または「직역」を明示的にリクエストした場合

優先順位ルール：対象が ON と OFF の両方のカテゴリに該当する場合は、デフォルトで ON が優先されます。よくある競合例：

状況	両方に該当する理由	解決方法
README の表のセル（短く、かつドキュメント）	10 語未満だが、README*.md 内にある	ON：README はドキュメントです
CHANGELOG の行項目	10 語未満だが、変更履歴内にある	ON：変更履歴はドキュメントです
レジストリ内のスキルの説明	短い名詞句だが、Git で追跡されるソースにコミットされる	ON：Git で追跡されるテキスト全般
i18n ファイル内のツールチップ	10 語未満で、かつ messages/ 内にある	OFF：ロケールファイル内の UI 文字列

内省にかかるコストは許容できますが、マージ後の修正コストは許容できません。

迷った場合は、内省を実行してください。トークンのコストはおよそ 1.5～2 倍ですが、本文の断片やヨーロッパ風の表現パターンの品質が大きく向上します。

拡張ワークフロー

ステージ 1～4 を完了したら、次に進みます。

ステージ 5：批判的レビュー

翻訳を新鮮な視点で原文と照らし合わせて読み直します。診断レビューを作成します（まだ書き直しません）。

まず、次の質問に明確に答えてレビューを始めます。「以下の草稿が、まだ明らかに機械翻訳または AI 生成に感じられるのはなぜですか？」 残っている特徴を挙げる短い箇条書きを 3～7 個記載します（例：「最後の段落で文体が急に改まる」「同じ接続表現が 3 回繰り返されている」「ラベルやセル以外の本文に名詞止めの断片が残っている」「比喩を直訳したため、対象言語では違う解釈になる」）。その後、次の構成に沿ってレビューを続けます。

• 正確性：段落ごとに比較します。事実、数値、限定表現が変わっていませんか？
• 欧文調の表現：不要な接続詞、受動態、名詞の羅列、過度な名詞化、不自然な代名詞を確認します（resources/anti-ai-patterns.md を参照）。
• 比喩表現の忠実性：ステージ 1 での比喩の対応付けを照合します。分類に沿って処理できていますか？ 不自然な直訳はありませんか？
• 感情表現の忠実性：主観的または感情的な言葉が、中立的な説明に平板化されていませんか？
• トーンのずれ：文書の最初から最後まで文体は一貫していますか？ 途中で変わっていませんか（例：改まった導入から、くだけた説明に移る）？
• 表現と流れ：まだ「翻訳調」に読める文（硬い表現、不自然な語順、ぎこちないつなぎ方）を指摘します。
• 自然な文章にするためのパターン：文章、マーケティング、ブログ、レポート、翻案のタスクでは、単調なリズム、均一な形の段落、道案内のような説明、ありきたりな結論、権威に訴える説得表現、定型的な課題・今後の展望のセクション、装飾目的の絵文字、タイトルを言い直す前置き、埋め草の表現を確認します。
• 文体サンプルとの適合：サンプルが提示されている場合、根拠のない意味を加えずに、文のリズム、段落の書き出し、語彙、句読点、つなぎ方がサンプルに合っているか確認します。
• 翻訳者注の品質：多すぎませんか？ 少なすぎませんか？ 正確で簡潔ですか？

ステージ 6：修正

ステージ 5 の指摘をすべて反映し、翻訳を改訂します。

• 正確性の問題を修正します
• 欧文調の表現を自然な日本語に書き換えます
• 直訳した比喩を対応付けに沿って解釈し直します
• 平板化された感情的な含みを取り戻します
• 硬い文を流暢な表現に組み替えます
• レビューの提案に応じて翻訳者注を調整します

ステージ 7：仕上げ

公開できる品質を目指して最終確認を行います。

• 単独の文章として読み、自然な日本語として流れるか確認します
• 段落間に残るぎこちないつながりを整えます
• 語り口が全体を通して一貫していることを確認します
• 直訳の比喩や翻訳調の表現が残っていないか、最後に確認します
• 書式が保持されていることを確認します（見出し、太字、リンク、コードブロック）

複数項目の翻訳ルール

UI キーなど、複数の文字列を翻訳する場合：

1. 翻訳を始める前に、すべての文字列を読みます。文脈が重要です。
2. プロジェクト内の既存の翻訳を確認し、用語と文体を合わせます。
3. 一連の翻訳全体で用語を統一します。
4. 変数やプレースホルダーはそのまま保持します（{name}、{{count}}、%s、<tag>、`code`）。
5. キーの構造を維持します。翻訳するのは値だけで、キーは変更しません。
6. UI 文字列はおおよその長さを合わせます（レイアウトが崩れるような、原文の 3 倍に及ぶ翻訳は避けます）。

差分同期モード（ソース差分に基づく既存翻訳の修正）

英語のソースが変更され、既存の翻訳をソースと同期させる必要がある場合に使用します。oma-docs v2 の多言語同期、ドキュメントの PR 後の手動での i18n 追随、または「ソースは更新されたが、翻訳は更新されていない」あらゆる状況で使用します。

入力：

• 英語ソースの統合差分（/tmp/oma-en-diff.patch または git diff のスニペット）
• 1 つ以上の対象言語ファイルのパス（同じソースの既存翻訳）
• 任意：ロケールごとの用語集または用語に関するヒント

ステージの上書き：

1. 準備：差分を読みます。追加、変更、削除されたセクションを特定します。
2. 取得：各対象ファイルを読みます。行番号ではなく、見出しアンカーと前後の文脈を使って、ソースの位置を対象ファイルの位置に対応付けます（翻訳では行番号が一致しません）。
3. 判断：差分の各ハンクについて、次のように判断します。
   • 追加されたセクション：新たに翻訳し、対応する位置に挿入します
   • 変更されたテキスト：変更箇所をローカライズし、対象側の該当箇所を置き換えます
   • 削除されたテキスト：対象側の該当箇所を削除します
   • 変更はあるが表記上のもののみ（空白、書式）：スキップし、翻訳をむやみに変更しません
4. 適用：Edit ツールでパッチを適用します。既存の翻訳の文体、用語、語調に合わせます（書き込む前に、対象ファイル内の少なくとも 3 つの近接するセクションを再読します）。
5. 検証：ステージ 4 の機械的チェック（em-dash、プレースホルダーの整合性、構造の一致）を実行し、差分の対象外のセクションが変更されていないことを確認します。

差分同期の厳守事項：

• 差分で変更された箇所だけを編集します。 対象ファイルのそれ以外のセクションは、バイト単位で同一のままにします。差分の対象外にずれを見つけた場合は報告しますが、同じパッチで自動修正してはいけません。
• 構造の忠実性を保ちます。 対象ファイルの見出し階層、表の数、リスト構造は、パッチ適用後のソースと一致させます。
• 行番号を前提にしません。 必ず見出しテキストとアンカーで移動し、絶対行を使ってはいけません。
• コード、正規表現、識別子は英語のままにします。 i18n-guide の規則に従い、コードブロック、JSON キー、ファイルパス、正規表現パターン、ワークフロー名、[OMA WORKFLOW: ...] のようなシステムマーカーはそのまま保持します。

出力形式（対象ファイルごと）：

Target: <path>
Sections updated: <list of heading paths>
Sections skipped: <list with reason, e.g. "no semantic change">
Ambiguities resolved: <terminology decisions made>

並列化：同じソース差分に対して複数の対象ロケールを更新する場合は、ロケールごとにエージェントを 1 つずつ並列で起動します。各エージェントには同じ差分と異なる対象ファイルのパスを渡します。対象ファイルは互いに独立しているため、調整は不要です。

出力形式

単一テキスト

Source (EN):
> original text

Translation (KO):
> translated text

Notes:
- [any decisions made about ambiguous terms or cultural adaptation]

バッチ（i18n ファイル）

入力と同じ形式（JSON、ARB、YAML など）で、値だけを翻訳して出力します。

レビューモード

Original translation:
> existing translation

Suggested revision:
> improved translation

Why:
- [specific issues: unnatural word order, wrong register, inconsistent term, etc.]

トラブルシューティング

問題	解決策
ソースの意味が曖昧	翻訳する前に、その旨を伝えて文脈を確認します
用語の訳例がない	訳語を提案し、適用前にユーザーに確認します
ソース内で文体が一致しない	プロジェクトで既に使用されている文体に従い、不一致を記録します
文の途中にプレースホルダーがある	プレースホルダーの構文は決して変更せず、周囲の文を組み替えます
UI に対して翻訳が長すぎる	注記を添えて短い代替案を提示します
ある用語に複数の妥当な訳語がある	プロジェクトの既存の翻訳に最も合う訳語を選び、別の候補も記録します
対象言語で性別による表現が必要	ソースの意図に従い、対象言語で可能な場合は性別に依存しない表現を優先します
長いドキュメント内で語調が変化する	翻訳後に最初から最後まで読み直し、優勢な語調に統一します

実行方法

翻訳手順（ステージ 1～4）に従って、順を追って実行します。 提出前に、resources/translation-rubric.md と resources/anti-ai-patterns.md を参照して確認します。

実行プロトコル（CLI モード）

ベンダー固有の実行プロトコルは、oma agent:spawn によって自動的に挿入されます。 ソースファイルは ../_shared/runtime/execution-protocols/{vendor}.md にあります。

論理操作

アクション

アクション	SSL プリミティブ	根拠
ソースとコンテキストを読み取る	READ	テキスト、ロケールファイル、コードのコンテキスト
文体と用語を選択する	SELECT	既存の翻訳と分野の用語
意図された意味を推測する	INFER	意味抽出の段階
翻訳文を書く	WRITE	翻訳先言語での再構成
プレースホルダーと構造を検証する	VALIDATE	検証ゲート
評価基準に照らして比較する	COMPARE	翻訳評価基準
翻訳または注記を報告する	NOTIFY	最終出力

ツールと手段

• 既存のロケールファイルと周辺のコード
• 翻訳評価基準、AI らしさを避けるためのルール、用語集／スタイルの参考資料
• ユーザーがファイルの変更を依頼した場合に限り、ファイル編集ツールを使用します

標準ワークフローのパス

1. Analyze source register, intent, domain terms, placeholders, and structure.
2. Reconstruct meaning in the target language, not word-for-word.
3. Run mechanical checks and `resources/translation-rubric.md` before emitting output.
4. For non-trivial prose, run Stage 5 humanization review before final polish; apply voice-sample calibration only when provided and appropriate.

UI ファイルの場合、まず同じディレクトリにあるロケールファイルを確認します：

rg "<source-key-or-term>" .

リソースの対象範囲

対象範囲	リソースの対象
LOCAL_FS	ロケールファイル、ドキュメント、README、ソーステキストファイル
CODEBASE	UI 文字列の周辺にあるコンポーネントとコードのコンテキスト
MEMORY	文体、用語集、曖昧さ、検証に関する注記
USER_DATA	ユーザーが提供したテキストと翻訳先言語の要件

前提条件

• ソーステキストと翻訳先言語がわかっています。
• プレースホルダーと構造に関する制約を特定できます。
• 曖昧さが解消されているか、明示的に指摘されています。

効果と副作用

• 翻訳文または翻訳レビューを作成します。
• 依頼された場合に限り、ロケール／ドキュメントファイルを変更することがあります。
• ソースの構造とプレースホルダーを維持します。

ガードレール

1. プロジェクトの慣例に合わせるため、翻訳前に既存のロケールファイルを確認します
2. プレースホルダーと補間構文を維持します
3. 単語ではなく意味を翻訳します
4. 感情的な含意を維持します。辞書的な意味だけでなく、伝わる感情を翻訳します（例：「alarming」は単に「驚くべき」ではなく、緊急性や懸念を含みます）
5. 1つの文章全体で文体を一貫させます
6. 翻訳先言語で自然になるよう、文を分割、統合、または再構成します
7. ソースのテキストが曖昧な場合は推測せず、指摘します
8. 分野で定着した意味を持つ用語（例：harness、scaffold、shim、polyfill、middleware）は、より「簡単な」日本語の語があっても、その分野の用語を維持します
9. 決して逐語訳にしません
10. 1つの文章の中で文体を混在させません（フォーマルとカジュアルの混在）
11. 分野固有の用語を一般的な語に置き換えません（例：「harness」→「framework」、「shim」→「wrapper」）
12. 既存の訳がある場合を除き、固有名詞を翻訳しません
13. 「より自然に聞こえる」ように意味を変えません
14. 10件を超える文字列のバッチでは、検証の段階を省略しません
15. ソースファイルの構造（キー、ネスト、コメント）を変更しません
16. ソース言語の書式上の特徴が翻訳先言語で不自然になる場合は、そのまま維持しません。CJK 言語（韓国語、日本語、中国語）では、ソースで使われていても、エムダッシュ（—）、見出しのタイトルケース、末尾の「-ing」分詞句は構成し直します。resources/anti-ai-patterns.md のルール 2（-ing 句）、14～15（エムダッシュ、タイトルケース）、25（CJK の組版と断片）を参照してください。
17. 個性を作り出して「人間らしく」しません。ソースまたはユーザーが明示的に翻案を求めていない限り、一人称、冗談、意見、例、事実、引用、強い感情、ぎこちなさを加えません。
18. 文体のサンプルが提供された場合は、リズム、語彙のレベル、句読点の使い方、文章のつなぎ方、段落の形など、観察できる文体の特徴だけを反映します。模倣よりもソースの意味と翻訳先言語での自然さを優先します。

参考資料

• 翻訳評価基準：resources/translation-rubric.md（自然さ、正確さ、文体、用語、技術的整合性の5項目による評価）
• AI らしさを避けるためのパターン：resources/anti-ai-patterns.md（避けるべき AI 出力のパターンと、欧州語的・翻訳調の表現）
• コンテキストの読み込み：../_shared/core/context-loading.md
• 品質の原則：../_shared/core/quality-principles.md