translate-book

translate-book 技能概覽

translate-book 是做什麼的

translate-book 技能是一套用於 PDF、DOCX 和 EPUB 檔案的書籍翻譯流水線。它會先把原始書稿拆成 Markdown 分段，再透過多個平行子代理翻譯這些分段，最後重建成 HTML、DOCX、EPUB 和 PDF。如果你需要 translate-book 來處理長篇內容的翻譯工作，當單一提示詞對整本書來說太脆弱或效期太短時，這套流程就特別有用。

適合誰安裝

如果你經常翻譯書籍、手冊或書長文件，而且在意可重現的輸出、分段續跑與格式重建，就很適合安裝 translate-book。它對想要有引導式工作流程、而不是從零手寫一次性翻譯提示詞的使用者，特別合適。如果你只需要短段摘譯或快速摘要，這個技能就沒那麼有價值。

它和其他方案有什麼不同

translate-book 技能最關鍵的差異在於它的流水線設計：轉換、分段、平行翻譯、雜湊驗證與重建，都是明確拆開的步驟。這種結構能降低上下文遺失的風險，也能在最後組裝前提早抓出缺漏或過期的分段。它也讓你的安裝判斷比一般「把這個檔案翻譯一下」的提示詞更清楚，因為這個 repo 對工具鏈與輸出成品都有明確主張。

如何使用 translate-book 技能

安裝並確認先決條件

先依照專案提供的安裝流程安裝，接著確認流水線需要的外部工具都已可用：python3、pandoc，以及 Calibre 的 ebook-convert 或 calibre。如果缺少 ebook-convert，translate-book install 這一步可能會成功，但實際工作流程會在轉換時失敗，所以一定要先確認執行環境。

一開始就提供完整輸入提示

這個技能最適合在一次請求中就給它檔案路徑、目標語言，以及任何風格限制。好的提示詞像這樣：Translate /path/to/book.epub into Japanese, keep technical terms consistent, preserve chapter structure, and use a formal tone. 這樣 translate-book usage 才有足夠上下文去選擇參數，避免來回補資料。如果你沒有提供檔案路徑，技能應該會停止並要求你補上。

先讀對的檔案

如果你是從安裝決策的角度評估，先讀 SKILL.md，再看 README.md、AGENTS.md 和 CLAUDE.md，就能了解實作與測試說明。這個 repo 裡，腳本比只掃過 README 更重要：scripts/convert.py、scripts/manifest.py、scripts/glossary.py、scripts/merge_and_build.py 會說明分段如何建立、如何追蹤、如何維持一致，以及如何重新組裝。這是最快判斷 translate-book 是否符合你工作流程的方法。

用分段感知的工作流程

不要把它想成一次性的翻譯呼叫。預期流程應該是：輸入檔案 → Markdown 分段 → 翻譯後的分段輸出 → 合併成完整書稿。下提示詞時，務必提到任何會影響分段品質的因素：註腳、表格或程式碼區塊是否必須保留；人名或專有名詞是否要維持原文；以及你是否需要整本書的詞彙表一致性。這些細節能幫助子代理少做那些日後彼此衝突的局部判斷。

translate-book 技能 FAQ

translate-book 適合初學者嗎？

可以，只要你能提供檔案路徑和目標語言。這個技能把多步驟流水線包起來了，但你仍然需要理解書籍層級的限制，例如格式忠實度與術語一致性。初學者通常先從較短的 EPUB 或 DOCX 開始，會比直接處理大型掃描 PDF 更容易得到好結果。

什麼情況下不該用 translate-book？

短段落、日常聊天式翻譯，或你只想要大意時，不建議使用它。對於 OCR 品質很差、掃描痕跡很重的 PDF，它也不是理想選擇，因為來源轉換品質會直接限制後續翻譯品質。如果輸入檔案無法乾淨轉換，再好的提示詞也無法完全補回結構。

它和一般翻譯提示詞有什麼不同？

一般提示詞通常是在單一上下文視窗內完成翻譯，容易遇到截斷、語意漂移和術語不一致的問題。translate-book 則是圍繞分段、驗證與重建來設計，所以更適合重視連貫性的長文檔。代價是前置設定更多，依賴項也要多確認。

translate-book 適用於任何語言組合嗎？

這個 repo 是為多種目標語言設計的，但品質仍取決於來源複雜度與術語密度。最好的結果通常來自明確指定目標語言代碼，並為領域術語提供詞彙表指引。對翻譯密集型專案來說，這種一致性指引的重要性，幾乎和語言選擇本身一樣高。

如何改進 translate-book 技能

提供更好的來源限制

translate-book 最大的品質提升，來自你清楚告訴它哪些內容不能變。請提供要保留的章節標題、要維持英文的術語、偏好的音譯方式、表格或程式碼區塊的格式規則，以及受眾層級，例如學術語氣或一般讀者語氣。比如：Keep API names unchanged, translate prose formally, and preserve Markdown headings exactly.

盡早降低詞彙表漂移

因為這條流水線會使用平行子代理，如果你沒有先定義關鍵術語，術語就可能在不同分段之間漂移。在處理大型書籍前，先準備一份簡短詞彙表，列出名稱、產品術語與重複出現的技術片語。這對 translate-book for Translation 專案尤其重要，因為一個不一致的術語很容易沿著多個分段擴散開來。

留意轉換與分段失敗

常見失敗模式包括 OCR 破損、原始格式不完整，以及分段邊界把表格或清單切得很尷尬。若第一版輸出看起來不平均，先檢查中間產物的分段檔與 manifest，再來怪翻譯品質。最實用的 translate-book guide 習慣，是先把來源流水線修正好，再用乾淨的分段重新跑翻譯。

針對第一版輸出反覆調整

第一次跑完後，先檢視幾個具有代表性的分段，不要只看最後合併好的整本書。檢查章節開頭、詞彙表術語、標題，以及原文格式密度很高的地方。如果需要，比起手動整本修，重新跑一次並加強指令通常更快；這也是改善下一次 translate-book skill 執行結果最快的方法。