dsh-translate-docs

DeepSeek-Harness ドキュメントの翻訳

呼び出しの境界

この拡張ワークフローは、ユーザーが dsh-translate-docs を名前で明示的に呼び出した場合にのみ実行してください。通常のドキュメント作業や別のスキルから、あるいは翻訳の必要性を推測して、このワークフローを選択したり読み込んだりしてはいけません。通常の翻訳では、docs/AGENTS.md に記載された、1回限りの一括処理ルールに従ってください。

このスキルについて

このスキルはガイダンスであり、翻訳メモリではありません。 foo.md ↔ foo.zh.md のペアで両言語の一貫性と自然さを保つためのワークフローを示します。両言語は同等の権威を持ちます。変更はどちらか一方の言語で作成され、その言語がその更新の原文となります。あなたの役割は翻訳者です。以下のルールが定めるのは満たすべき条件であり、個々の文の表現方法ではありません。表現の判断はあなたに任されていますが、用語は変えてはいけません。

変更の種類による振り分け — これがほかのすべてを決定します

• 更新（ペアが存在し、片方が編集されている場合）：更新パスに従ってください。これはブリーフィング主導で、意図的にコストを抑えた手順です。ガイダンスコーパスを読んだり、Git の履歴を調査したりせず、対応する側を最小限だけ編集します。更新を反映するためにドキュメント全体を再翻訳してはいけません。最小限の更新なら、変更のない箇所のレビュー済み表現を保てますが、再翻訳するとそのレビューが無駄になります。
• 新規ペア（対応するドキュメントがまだない場合）：ドキュメント全体のパスに従ってください。
• ドキュメントの削除または名前変更：対応するドキュメントと、その隣にある .i18n.yaml も削除または名前変更してください。そうしないと、ゲートでペアの不完全が報告されます。

.agents/notes/archived/ にある凍結済みの Agent Notes は翻訳対象ではありません。完全な3点セットはアーカイブ検証ツールによって封印されています。アーカイブ後にどちらか一方を更新、再記録、修復してはいけません。

更新パス（ブリーフィング駆動）

ブリーフィング駆動のパスは、ガイダンスコーパスと同等の品質を、わずかなコストで実現します。ベンチマークの根拠は、アーカイブされたbriefed-updates Agent Noteに記録されています。

1. ブリーフィングを生成する：pnpm run gen-translation-brief <any file of the pair>（引数を指定しない場合、同期していないすべてのペアについてブリーフィングを生成します）。ブリーフィングでは、変更内容を安全に対応付けられる最小単位（変更されたMarkdownの単位（段落、表の行、リスト項目、見出し）、次に見出しセクション全体、最後にドキュメント全体）で対応付けます。また、前回整合性が確認された状態からの原文側の差分、変更された各単位について最後に確認された原文・現在の原文・現在の対訳テキスト（行番号付き）、変更に関係する用語集の項目、初出位置の移動に関する注記、および更新を拘束するルールの概要が含まれます。
2. 差分が機械的な変更のみの場合は、--applyを使います。 ペアでバイト単位まで同一のコードフェンス内にすべての変更が収まっている場合、ブリーフィングにその旨が記載されます。pnpm run gen-translation-brief --apply <pair>を実行すると、編集されたコードフェンスを対訳に差し込み、構造を検証してから書き込みます。サブエージェントも手作業での編集も不要です。
3. 散文に差分がある場合は、ブリーフィング（またはブリーフィングを生成するコマンド）を渡してサブエージェントに委任します。 ブリーフィングが翻訳者の作業に必要な情報のすべてです。サブエージェントはガイダンスコーパスを再読せず（ルールの概要、用語集の項目、変更された各単位の三者間の文脈がインラインで示されます）、差分を再導出することもありません。ブリーフィングだけでは具体的な判断がどうしてもできない場合に限り、ドキュメント全体のパスにおける信頼できる情報源を参照します。該当するのは、周辺テキストに前例がない未掲載用語、またはドキュメント全体のブリーフィング（BOTH sides changed、あるいは単位もセクションも対応付けられない場合）です。後者は常にtranslation-rules.mdに従って手作業で調整する必要があります。
4. 差分を網羅する最小限の編集を行います。 差分に触れない部分のレビュー済みの表現は維持し、変更箇所を原文と節ごとに照合して確認します。追加や欠落がないこと、インラインの用語集項目に従っていること、コードスパンが原文どおりであることを確認します。
5. 対象を絞って記録し、検証します：pnpm run verify-translation-pairing --write <pair>を実行してから、pnpm run verify-translation-pairing <pair>を実行します。--writeでは確認済みのペアを正確に指定します。引数なしでの実行は拒否されるため、一括で再記録する場合は明示的に--allを指定する必要があります。コーパス全体のチェックは引き続きdoc-sync／CIで実行されます。更新ごとに実行しないでください。

ドキュメント全体のパス（新しいペア）

翻訳を一から作成する場合、オーケストレーターのエージェントは翻訳しません。翻訳作業を行うサブエージェントを起動します。翻訳者はまず以下の信頼できる情報源を確認してから、もう一方の言語にファイル全体を翻訳します。長いドキュメントはセクションごとに翻訳し、最後に構造を修正するのではなく、作業を進めながら各セクションの構造を原文と一致させます。

信頼できる情報源（読み、要約しないでください）

• docs/i18n/README.md — 対応付けの契約です。3 ファイルの組（foo.md、foo.zh.md、foo.i18n.yaml）、整合性記録のセクションごとのハッシュ、言語切り替え行、対象範囲、除外項目について説明しています。
• docs/i18n/translation-rules.md — 翻訳方法について説明しています。忠実さ、構造の保持、用語の統一、表記上の規則（MUST／SHOULD のレベル）を確認してください。
• docs/i18n/terminology.md — 双方向で適用される用語集です。翻訳前に読み込んでください。用語に迷ったときではなく、その前に確認してください。表記が揺れるのは、気づかない用語です。
• docs/i18n/translation-prompt.md — 自動化パイプラインが使用する、調整済みの機械処理用テンプレートです。このスキルを使うエージェントはこれを出力しません。自動レンダラーが挿入するリポジトリ内ファイルは用語集のみですが、このスキルと translation-rules.md は、エージェントが作成する翻訳に引き続き適用されます。
• dsh-prose-standard — 必須の文章範囲と編集上の判断基準です。原文の命題を追加または削除せず、原文と訳文の両方に適用してください。

翻訳する

• パス 1 — 書き直し、逐語的に移し替えない。 意味のまとまりを読み、最も近い文体サンプルの文体で、技術文書の書き手として自然に書き直します。文ごとの対応を無理に求めず、必要な構成は保ってください。
• パス 2 — 原文と節ごとに照合する。 忠実さはここで確認するものであり、ここで書き込むものではありません。何も追加・削除されていないこと、すべての用語が用語集に従っていること、各コードスパンが原文どおりに保持されていることを確認してください。修正するときは、単語を継ぎ足すのではなく、文全体を自然な表現に書き直してください。
• 完成した訳文だけを読む。 原文との照合後、原文を横に置かずに翻訳ファイルを読み、単独で読んだときにだけ不自然さが分かる表現を書き直してください。
• ファイルには最終稿のみを書き、下書きやメモは残さないでください。
• terminology.md にあるすべての用語は、指定どおりに表記してください。中国語を訳文とする場合は、中国語列と初出時の列を使用してください。記載のない用語は、出典を示せる中国語の OSS／ベンダー用例がなければ、英語のまま「保留用語」として扱います。英語を訳文とする場合は、英語列と定着した英語の技術用語を使用してください。原文の曖昧な用語は短い補足を添えて保持し、保留用語として記載してください。訳語をその場で作らないでください。
• コードブロックは、コメントも含め、対応するファイル間でバイト単位に一致させてください。リポジトリ相対の文書リンクは、意味上のリンク先とクエリ／フラグメントの接尾辞を完全に同一に保ちます。現在のバイリンガル対象範囲内にあるリンク先は、英語側では .md、中国語側では .zh.md を使用してください。対象範囲内の対応ファイルが存在しない場合はエラーです。対象範囲外のリンク先は、記述済みのパスを維持してください。言語切り替えリンクのみ例外として扱います。
• 対応付けゲートでは、見出しレベル、フェンス付きブロック、表の行数と列数、リストの種類、番号付きリストの開始番号、リスト項目数、リンクの言語、意味上のリンク先を検証します。パス 2 では、リストと表の順序、標準的でないリスト番号、インラインコード、強調、意味、用語、語調を手動で確認してください。

作業を見つける

• 引数なしで pnpm run verify-translation-pairing --list を実行すると、対象範囲内のすべての文書が missing／out-of-sync／ok のいずれかとして表示されます。missing と out-of-sync の行は契約違反であり、通常のチェックでは拒否されます。
• 引数なしで pnpm run gen-translation-brief を実行すると、同期されていないすべてのペアのブリーフィングが表示されます。
• 対応する文書を編集する PR では、作業リストは差分そのものです。ペアの片側を変更した場合は、同じ PR で対応する側も更新し、ペアの記録を更新する必要があります。忘れるとゲートが失敗します。

ペアを完成させる

1. 切り替えリンク：中国語ファイルの H1 の直後に [English](foo.md) | 中文、英語ファイルの H1 の直後に English | [中文](foo.zh.md) を追加します。新しいペアの場合は両方を追加します。ただし、ジェネレーターが管理する英語のソースはジェネレーターの出力とバイト単位で一致させ、切り替えリンクを省略します。中国語側には英語へのリンクを残します。
2. 記録の整合性：pnpm run verify-translation-pairing --write <pair> を実行すると、セクションごとのハッシュが再計算され、foo.i18n.yaml に記録されます。PR の YAML 差分は、「この 2 つの内容が一致していることを確認しました」という、レビュー可能な表明です。実際に確認してからのみ実行してください。
3. 通常のドキュメントにマニフェストのエントリーは不要です。対象となるすべてのソースにペアが必要です。scripts/translation-pairing.manifest.json を変更するのは、所有するポリシーで、生成物、説明用の資料、または構成上バイリンガルであることを理由に除外する場合に限ります。
4. PR の前に：変更したペアがスコープを絞ったチェックに合格していることを確認します。dsh-pre-push-checks に従い、pnpm run doc-sync（コーパス全体のペアリングチェックと verify-md-wrap／verify-md-links を含む）は PR の段階で一度実行し、翻訳タスクごとには実行しません。
5. PR をレビューしやすく保つため、新規ペアと最小限の更新を加えたペアを明記し、「待定术语」を目立つように列挙します。

翻訳レビューへの対応方法

コードレビューの報告ガイドラインに従い、各コメントの妥当性を評価します。用語に関するコメントでは、用語表が基準であることを忘れず、レビュアーが決めた表記を 1 つのファイルだけでなく terminology.md に反映してください。