baoyu-translate
熱門當使用者要求「translate」、「翻譯」、「精翻」、「translate article」、「translate to Chinese」、「translate to English」、「改成中文」、「改成英文」、「convert to Chinese」、「localize」、「本地化」、「refined translation」、「精細翻譯」、「proofread translation」、「快速翻譯」、「快翻」、「這篇文章翻譯一下」，或提供帶有翻譯意圖的 URL／檔案時使用此 Skill。支援三種模式（快速／一般／精修），並支援自訂術語表。
當使用者要求「translate」、「翻譯」、「精翻」、「translate article」、「translate to Chinese」、「translate to English」、「改成中文」、「改成英文」、「convert to Chinese」、「localize」、「本地化」、「refined translation」、「精細翻譯」、「proofread translation」、「快速翻譯」、「快翻」、「這篇文章翻譯一下」，或提供帶有翻譯意圖的 URL／檔案時使用此 Skill。支援三種模式（快速／一般／精修），並支援自訂術語表。
Translator
具備三種模式的翻譯 Skill：quick（快速） 用於直接翻譯，normal（一般） 用於經分析後的翻譯，refined（精修） 用於包含審閱與潤飾的完整出版級工作流程。
使用者輸入工具
當此 Skill 提示使用者時，請遵循以下工具選擇規則（依優先順序）：
- 優先使用內建的使用者輸入工具（由當前 Agent 執行階段提供）— 例如
AskUserQuestion、request_user_input、clarify、ask_user或任何同等工具。 - 備用機制：若無此類工具，請發出帶有編號的純文字訊息，並要求使用者針對每個問題回覆所選的編號／答案。
- 批次處理：若工具支援單次呼叫提出多個問題，請將所有適用問題整合為單一呼叫；若僅支援單一問題，請依優先順序一次詢問一個。
下方具體的 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 支援：預設目標語言、預設模式、目標受眾、自訂術語表（內嵌或檔案路徑）、翻譯風格、分塊設定。
Schema：references/config/extend-schema.md。
首次設定（阻斷性作業）
關鍵：當未找到 EXTEND.md 時，你必須在進行任何翻譯之前執行首次設定。這是一項阻斷性作業。
完整參考：references/config/first-time-setup.md
使用 AskUserQuestion 在一次呼叫中提出所有問題（目標語言、模式、受眾、風格、儲存位置）。使用者回答後，在選擇的位置建立 EXTEND.md，確認「偏好設定已儲存至 [path]」，然後繼續。
預設值
所有可設定的值皆集中於一處。EXTEND.md 會覆寫這些值；CLI 旗標 (CLI flags) 則會覆寫 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 |
— | 每個分塊的最大字數 |
模式
| 模式 | 旗標 | 步驟 | 適用時機 |
|---|---|---|---|
| Quick | --mode quick |
Translate | 短文、非正式內容、快速任務 |
| Normal | --mode normal（預設） |
Analyze → Translate | 文章、部落格文章、一般內容 |
| Refined | --mode refined |
Analyze → Translate → Review → Polish | 出版品質、重要文件 |
預設模式：Normal（可在 EXTEND.md default_mode 設定中覆寫）。
風格預設集 — 控制翻譯的語意與風格基調（獨立於受眾）：
| 設定值 | 說明 | 效果 |
|---|---|---|
storytelling |
引人入勝的敘事流暢感（預設） | 吸引讀者、轉折平滑、用詞生動 |
formal |
專業、結構化 | 中立語氣、組織清晰、不使用口語 |
technical |
精確、技術文件風格 | 簡潔、術語密集、極少修飾 |
literal |
貼近原文結構 | 結構調整極少、保留原文句型 |
academic |
學術、嚴謹 | 正式語調、允許複雜子句、注重引用 |
business |
簡潔、結果導向 | 行動導向、適合高階主管閱讀、重點摘要邏輯 |
humorous |
保留並在地化幽默感 | 機智、風趣，在目標語言中重現喜劇效果 |
conversational |
輕鬆、口語化 | 親切、平易近人，如同向朋友解釋 |
elegant |
文雅、精雕細琢的散文 | 具美感、富節奏感，精挑細選用字 |
亦接受自訂風格描述，例如 --style "poetic and lyrical"。
自動偵測：
- 「快翻」、「quick」、「直接翻譯」→ quick 模式
- 「精翻」、「refined」、「publication quality」、「proofread」→ refined 模式
- 其他情況 → 預設模式 (normal)
升級提示：在 normal 模式完成後，顯示：
翻譯已儲存。如需進一步審閱與潤飾，請回覆「繼續潤色」或「refine」。
若使用者回應，對現有輸出繼續執行審閱 → 潤飾步驟（與 refined-workflow.md 中 refined 模式步驟 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 |
Normal, Refined | 內容分析（領域、語氣、術語） |
02-prompt.md |
Normal, Refined | 組合後的翻譯 Prompt |
03-draft.md |
Refined | 審閱前的初稿 |
04-critique.md |
Refined | 批評審閱發現（僅診斷） |
05-revision.md |
Refined | 依據審閱意見修訂後的翻譯 |
chunks/ |
Chunked | 來源分塊 + 翻譯分塊 |
步驟 3：評估內容長度
Quick 模式不進行分塊 — 無論長度如何皆直接翻譯。翻譯前先預估字數。若內容超出分塊門檻（預設 4000 字），主動警告：「這篇文章約為 ~{N} 字。Quick 模式會單次全篇翻譯而不分塊 — 對於長篇內容，使用 --mode normal 能在術語一致性上獲得更好的效果。」若使用者未切換模式，則繼續執行。
對於 normal 與 refined 模式：
| 內容 | 動作 |
|---|---|
| < 分塊門檻 | 作為單一單元進行翻譯 |
| >= 分塊門檻 | 進行分塊翻譯（參見步驟 3.1） |
3.1 長篇內容準備作業（僅限 normal/refined 模式且 >= 分塊門檻）
在翻譯分塊之前：
- 擷取術語：掃描整份文件以找出專有名詞、技術術語與重複出現的短語
- 建立工作階段術語表：將擷取的術語與已載入的術語表合併，建立一致的翻譯標準
- 拆分為區塊：使用
${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>]- 解析 Markdown 區塊（標題、段落、清單、程式碼區塊、表格等）
- 在 Markdown 區塊邊界處切分以保留結構
- 若單一區塊超出門檻，退回至按行切分，再按字切分
- 組合翻譯 Prompt：
- 主 Agent 讀取
01-analysis.md（若存在），並使用 references/subagent-prompt-template.md 的第 1 部分組合共享上下文 — 內嵌：目標風格、內容背景、合併後的術語表以及翻譯難點 - 在輸出目錄中儲存為
02-prompt.md（僅含共享上下文，不含任務指示）
- 主 Agent 讀取
- 透過子 Agent 撰寫初稿（若 Agent 工具可用）：
- 每個分塊衍生 (spawn) 一個子 Agent，全部平行處理（範本第 2 部分）
- 每個子 Agent 讀取
02-prompt.md以取得共享上下文，接收分塊位置資訊（第 N/M 個分塊 + 其在論述中所處位置的簡短上下文），翻譯其分塊，並儲存至chunks/chunk-NN-draft.md - 一致性由共享的
02-prompt.md擔保（包含術語表、比喻對映、理解難點、原文語調以及來自分析的翻譯難點） - 若無分塊（內容低於門檻）：為整個來源檔案衍生一個子 Agent
- 若 Agent 工具不可用，請在行內使用
02-prompt.md依序翻譯各個分塊
- 合併：所有子 Agent 完成後，依序合併已翻譯的分塊。若
chunks/frontmatter.md存在，請置於開頭。儲存為03-draft.md（refined 模式）或translation.md（normal 模式） - 所有中間檔案（來源分塊 + 翻譯分塊）皆保留於
chunks/中
分塊初稿合併後，將控制權交回主 Agent 進行批判性審閱、修訂與潤飾（步驟 4）。
步驟 4：翻譯與精修
翻譯原則（適用於所有模式）：
- 重寫而非直譯：將內容重寫為自然、吸引人的目標語言，宛如由精通目標語言的母語作者從頭創作。品質檢驗標準：「讀起來是否像是原本就用目標語言寫成的？」
- 準確第一：事實、資料與邏輯必須與原文完全吻合
- 自然流暢：使用地道的目標語言語序。將原文長句拆分為較短、自然的句子。依據背後涵義解讀隱喻與成語，而非逐字硬翻譯
- 術語一致：一致地使用標準譯名。專有名詞首次出現時：在括號內附註原文
- 保留格式：保留所有 Markdown 格式（標題、粗體、斜體、圖片、連結、程式碼區塊）
- 主動解讀：對於目標受眾可能缺乏背景知識的術語或概念，在粗體括號中新增簡明解釋 `（**
