baoyu-translate

翻訳ツール

3 つのモードを備えた翻訳スキルです。直接翻訳する quick、分析に基づいて翻訳する normal、レビューと推敲を含む出版品質のワークフローを実行する refined があります。

ユーザー入力ツール

このスキルがユーザーに質問するときは、次のツール選択ルールに従ってください（優先順位順）。

1. 組み込みのユーザー入力ツールを優先する — 現在のエージェントランタイムが公開している AskUserQuestion、request_user_input、clarify、ask_user など、または同等のツールを使用します。
2. フォールバック：そのようなツールがない場合は、番号付きのプレーンテキストメッセージを出力し、各質問に対する番号または回答をユーザーに返信してもらいます。
3. まとめて質問する：ツールが 1 回の呼び出しで複数の質問に対応している場合は、該当する質問をすべてまとめて呼び出します。1 回に 1 つの質問しかできない場合は、優先順位に従って 1 つずつ質問します。

以下の AskUserQuestion の具体例は参考例です。他のランタイムでは、ローカル環境に相当するツールに置き換えてください。

スクリプトディレクトリ

スクリプトは scripts/ サブディレクトリにあります。{baseDir} はこの SKILL.md のディレクトリパスです。${BUN_X} ランタイムは次のように解決します。bun がインストールされている場合は bun、npx が利用できる場合は npx -y bun を使用し、どちらも利用できない場合は bun のインストールを案内します。{baseDir} と ${BUN_X} は実際の値に置き換えてください。

スクリプト	用途
scripts/main.ts	CLI エントリーポイントです。デフォルトのアクションでは Markdown をチャンクに分割します。また、明示的な chunk サブコマンドにも対応しています
scripts/chunk.ts	main.ts が使用する Markdown チャンク分割の実装です。直接呼び出す場合との互換性も維持されています

設定（EXTEND.md）

次の優先順位で EXTEND.md を確認してください。最初に見つかったファイルを使用します。

優先順位	パス	適用範囲
1	.baoyu-skills/baoyu-translate/EXTEND.md	プロジェクト
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-translate/EXTEND.md	ユーザーホーム

結果	アクション
見つかった	読み込み、解析し、適用します。セッションで初めて使用するときに、「[path] の設定を使用しています。用語集や対象読者などは EXTEND.md を編集してカスタマイズできます。」と簡潔に伝えます。
見つからない	初回セットアップを必ず実行してください（以下を参照） — デフォルト設定を黙って使用してはいけません

EXTEND.md がサポートする項目：既定の翻訳先言語、既定のモード、対象読者、カスタム用語集（インラインまたはファイルパス）、翻訳スタイル、チャンク設定。

スキーマ：references/config/extend-schema.md。

初回セットアップ（必須）

重要：EXTEND.md が見つからない場合、翻訳を始める前に必ず初回セットアップを実行してください。この処理は必須です。

詳細：references/config/first-time-setup.md

AskUserQuestion を使い、翻訳先言語、モード、対象読者、スタイル、保存場所に関するすべての質問を1 回の呼び出しで行います。ユーザーの回答後、選択された場所に EXTEND.md を作成し、「設定を [path] に保存しました」と確認してから続行します。

デフォルト設定

設定可能な値を以下にまとめています。EXTEND.md の設定はこれらを上書きし、CLI フラグは EXTEND.md の設定を上書きします。

設定	デフォルト	EXTEND.md キー	CLI フラグ	説明
翻訳先言語	zh-CN	target_language	--to	翻訳先の言語
モード	normal	default_mode	--mode	翻訳モード
対象読者	general	audience	--audience	対象となる読者層
スタイル	storytelling	style	--style	翻訳スタイルの設定
チャンク分割のしきい値	4000	chunk_threshold	—	チャンク分割翻訳を開始する単語数
チャンクあたりの最大単語数	5000	chunk_max_words	—	チャンクあたりの最大単語数

モード

モード	フラグ	手順	使用する場面
クイック	--mode quick	翻訳	短い文章、くだけた内容、手早く済ませたい作業
通常	--mode normal（デフォルト）	分析 → 翻訳	記事、ブログ投稿、一般的なコンテンツ
洗練	--mode refined	分析 → 翻訳 → レビュー → 推敲	公開品質を求める文書、重要な文書

デフォルトモード：通常（EXTEND.md の default_mode 設定で変更できます）。

スタイルプリセット — 対象読者とは独立して、翻訳の語り口とトーンを制御します。

値	説明	効果
storytelling	読み手を引き込む物語調の流れ（デフォルト）	読み手を引き込み、自然につなぎ、鮮やかな表現を用います
formal	専門的で構成の整った文体	中立的なトーン、明確な構成、口語表現なし
technical	正確でドキュメント向けの文体	簡潔で専門用語を多用し、装飾は最小限にします
literal	原文の構成に忠実	再構成を最小限に抑え、原文の文型を保ちます
academic	学術的で厳密	格式の高い文体、複雑な節も可、引用に配慮します
business	簡潔で成果を重視	行動を促し、経営層にも伝わりやすく、箇条書きを意識します
humorous	ユーモアを保ち、適応	機知に富み、遊び心があり、対象言語で笑いの効果を再現します
conversational	カジュアルで話し言葉に近い	親しみやすく、友人に説明するような文体です
elegant	文学的で洗練された文章	美的に磨かれ、リズムがあり、言葉選びにも細心の注意を払います

カスタムのスタイル説明も指定できます。例：--style "poetic and lyrical"。

自動検出：

• 「快翻」、「quick」、「直接翻译」 → クイックモード
• 「精翻」、「refined」、「publication quality」、「proofread」 → 洗練モード
• それ以外 → デフォルトモード（通常）

アップグレードの案内：通常モードの完了後、次の内容を表示します。

翻訳を保存しました。さらにレビューと推敲を行うには、「继续润色」または「refine」と返信してください。

ユーザーが返信した場合は、既存の出力に対してレビュー → 推敲の手順を続行します（refined-workflow.md の洗練モードの手順 4～6 と同じ）。

対象読者プリセット：

値	説明	効果
general	一般読者（デフォルト）	平易な言葉を使い、専門用語には翻訳者注を多めに付けます
technical	開発者／エンジニア	一般的な技術用語への注釈を減らします
academic	研究者／学者	格式の高い文体で、正確な用語を使います
business	ビジネスパーソン	ビジネスに適したトーンで、技術的な概念を説明します

カスタムの対象読者の説明も指定できます。例：--audience "AI感兴趣的普通读者"。

ワークフロー

ステップ 1：設定の読み込み

1.1 EXTEND.md を確認します（上記の設定セクションを参照）。

1.2 言語ペアに対応する組み込み用語集があれば読み込みます：

• EN→ZH：references/glossary-en-zh.md

1.3 用語集を統合します：EXTEND.md の glossary（インライン）＋ EXTEND.md の glossary_files（外部ファイル、パスは EXTEND.md の場所からの相対パス）＋ 組み込み用語集 ＋ --glossary ファイル（CLI ですべてを上書き）

ステップ 2：ソースの実体化と出力ディレクトリの作成

ソースを実体化し（ファイルはそのまま、インラインテキスト／URL は translate/{slug}.md に保存）、その後、出力ディレクトリを作成します：{source-dir}/{source-basename}-{target-lang}/。--from が指定されていない場合は、ソース言語を検出します。

詳細：references/workflow-mechanics.md

出力ディレクトリの内容（中間ファイルと最終ファイルはすべてここに保存します）：

ファイル	モード	説明
translation.md	すべて	最終翻訳（常にこの名前）
01-analysis.md	通常、洗練	内容分析（分野、トーン、用語）
02-prompt.md	通常、洗練	組み立て済みの翻訳プロンプト
03-draft.md	洗練	レビュー前の初稿
04-critique.md	洗練	批判的レビューの指摘事項（診断のみ）
05-revision.md	洗練	指摘事項に基づいて修正した翻訳
chunks/	分割	ソースの分割単位＋翻訳済みの分割単位

ステップ 3：コンテンツの長さを評価する

クイックモードでは分割せず、長さにかかわらず直接翻訳します。翻訳前に単語数を見積もります。コンテンツが分割のしきい値（デフォルトは 4000 語）を超える場合は、事前に次のように警告します。「この記事は約 {N} 語です。クイックモードでは分割せずに一度で翻訳します。長いコンテンツの場合、--mode normal を使うと用語の一貫性が向上します。」ユーザーが切り替えない場合は、そのまま続行します。

ノーマルモードとリファインドモードの場合：

コンテンツ	アクション
< 分割のしきい値	ひとまとまりとして翻訳
>= 分割のしきい値	分割して翻訳（ステップ 3.1 を参照）

3.1 長いコンテンツの準備（ノーマル／リファインドモードで、分割のしきい値以上の場合のみ）

チャンクを翻訳する前に、次の手順を行います。

1. 用語を抽出する：ドキュメント全体から固有名詞、技術用語、繰り返し使われる表現を探します
2. セッション用語集を作成する：抽出した用語を読み込んだ用語集と統合し、一貫した訳語を確立します
3. チャンクに分割する：${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>] を使用します
   • Markdown のブロック（見出し、段落、リスト、コードブロック、表など）を解析します
   • 構造を保つため、Markdown ブロックの境界で分割します
   • 単一のブロックがしきい値を超える場合は、行単位の分割に切り替え、それでも収まらなければ単語単位で分割します
4. 翻訳プロンプトを組み立てる：
   • メインエージェントは 01-analysis.md（存在する場合）を読み込み、references/subagent-prompt-template.md のパート 1 を使って、対象のスタイル、コンテンツの背景、統合した用語集、翻訳上の課題をインライン化した共通コンテキストを組み立てます
   • 共通コンテキストのみを含め、タスク指示は含めずに、出力ディレクトリに 02-prompt.md として保存します
5. サブエージェントで翻訳の草稿を作成する（Agent ツールが利用可能な場合）：
   • チャンクごとに 1 つのサブエージェントを起動し、すべて並行して実行します（テンプレートのパート 2）
   • 各サブエージェントは共通コンテキストとして 02-prompt.md を読み込み、チャンクの位置情報（全 M チャンク中の N 番目、および議論の中での位置を示す簡単なコンテキスト）を受け取り、自身のチャンクを翻訳して chunks/chunk-NN-draft.md に保存します
   • 共通の 02-prompt.md（用語集、比喩表現の対応、理解上の課題、原文の文体、分析から得られた翻訳上の課題）によって一貫性を保ちます
   • チャンクがない場合（コンテンツがしきい値未満の場合）は、原文ファイル全体に対してサブエージェントを 1 つ起動します
   • Agent ツールが利用できない場合は、02-prompt.md を使ってチャンクを順番にインラインで翻訳します
6. 統合する：すべてのサブエージェントの処理が完了したら、翻訳済みのチャンクを順番に結合します。chunks/frontmatter.md が存在する場合は、先頭に付加します。リファインドモードでは 03-draft.md、ノーマルモードでは translation.md として保存します
7. 中間ファイル（原文のチャンクと翻訳済みのチャンク）はすべて chunks/ に保持されます

チャンクに分割した草稿の統合後、メインエージェントに制御を戻し、重要なレビュー、修正、推敲を行います（ステップ 4）。

ステップ 4：翻訳と推敲

翻訳の原則（すべてのモードに適用）：

• 翻訳ではなく、書き直す：熟練したネイティブの書き手が最初から書いたかのように、自然で魅力的な対象言語の文章に書き直します。品質の判断基準は、「対象言語で最初から書かれたように読めるか」です。
• 正確さを最優先する：事実、データ、論理は原文と完全に一致させます。
• 自然な流れにする：対象言語として自然な語順を使います。原文の長い文は、短く自然な文に分けます。比喩や慣用句は、一語一句置き換えるのではなく、意図された意味をくみ取って訳します。
• 用語：標準的な訳語を一貫して使います。専門用語は初出時に、原語を括弧内に添えます。
• 書式を維持する：見出し、太字、斜体、画像、リンク、コードブロックなど、すべての Markdown 書式を保持します。
• 積極的に解釈する：対象読者にとって背景知識が不足している可能性のある専門用語や概念には、簡潔な説明を太字の括弧書き （**解释**） で加えます。注釈は、本当に理解に必要な場合に限り、少数にとどめます。
• フロントマター：原文に YAML フロントマターがある場合は、source メタデータのフィールド名に source 接頭辞を付けてキャメルケースに変更します（例：url→sourceUrl、title→sourceTitle）。翻訳後の値は新しいトップレベルフィールドとして追加します（本文に H1 がある場合は title を省略します）。その他のフィールドはそのままにします。

クイックモード

直接翻訳し、translation.md に保存します。上記の翻訳原則をすべて適用します。

通常モード

1. 分析 → 01-analysis.md（分野、文体、用語、翻訳上の課題）
2. プロンプトの作成 → 02-prompt.md（背景情報、用語集、課題を含む翻訳指示）
3. 翻訳（02-prompt.md に従う）→ translation.md

完了後、ユーザーに次のように促します：「翻訳を保存しました。さらにレビューして推敲するには、继续润色 または refine と返信してください。」

ユーザーが続行した場合は、改めて批評レビュー → 修正 → 推敲を行います（以下の改良モードのステップ 4～6 と同じ）。03-draft.md（現在の translation.md の名前を変更したもの）、04-critique.md、05-revision.md、更新後の translation.md を保存します。

改良モード

公開品質の翻訳を目指すための完全なワークフローです。各ステップの詳しいガイドラインは references/refined-workflow.md を参照してください。

サブエージェント（ステップ 3.1 で使用した場合）は初稿の作成のみを担当します。その後のステップ（批評レビュー、修正、推敲）はすべてメインエージェントが担当し、必要に応じてサブエージェントに委任できます。

手順と保存ファイル（すべて出力ディレクトリ内）：

1. 分析 → 01-analysis.md（分野、文体、用語、翻訳上の課題）
2. プロンプトの作成 → 02-prompt.md（背景情報を含めた翻訳指示）
3. 初稿 → 03-draft.md（翻訳者の注釈付き初稿。分割翻訳の場合はサブエージェントが作成）
4. 批評レビュー → 04-critique.md（診断のみ：正確さ、欧州語的な表現、方針の実行状況、表現上の問題）
5. 修正 → 05-revision.md（批評で見つかった問題をすべて反映した改訂版を作成）
6. 推敲 → translation.md（公開品質の最終翻訳）

各ステップでは、前のステップで作成したファイルを読み込み、その内容を基に作業します。

ステップ 5：出力

最終的な翻訳は、出力ディレクトリ内の translation.md に常に保存されます。

最終的な翻訳を書き込んだ後、画像内の言語について簡単に確認します。

1. 翻訳した記事から画像参照を収集します
2. 表紙、スクリーンショット、図、グラフ、フレームワーク、インフォグラフィックなど、テキストが多く含まれている可能性のある画像を特定します
3. 画像内の主要なテキストの言語が、翻訳後の記事の言語と異なる可能性がある場合は、ユーザーに事前に知らせます
4. 注意喚起はリストのみとします。ユーザーから依頼がない限り、画像のローカライズは自動で行いません

注意喚起の形式（記事で使用されている画像構文に合わせて、標準の Markdown または wikilink を使用します）：

Possible image localization needed:
- ![example cover](attachments/example-cover.png): likely still contains source-language text while the article is now in target language
- ![example diagram](attachments/example-diagram.png): likely text-heavy framework graphic, check whether labels need translation

表示の概要：

**Translation complete** ({mode} mode)

Source: {source-path}
Languages: {from} → {to}
Output dir: {output-dir}/
Final: {output-dir}/translation.md
Glossary terms applied: {count}

画像内の言語が一致しない可能性のある候補が見つかった場合は、概要の後に、埋め込み画像の一部で画像内テキストのローカライズが必要な可能性があることを伝える短い注記と、候補のリストを追加します。

拡張機能のサポート

EXTEND.md を使用してカスタム設定ができます。パスとサポートされているオプションについては、設定セクションを参照してください。