深入TranslateBooksWithLLMs的EPUB翻译管线标签、样式与元数据如何被完美保留【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMsTranslateBooksWithLLMs 是一款基于大语言模型的EPUB 全书翻译工具支持 Ollama、OpenAI 兼容接口、Gemini、Mistral、DeepSeek、Poe、OpenRouter 等多种 LLM。它的 EPUB 翻译管线核心位于 src/core/epub/最打动人的地方在于翻译完的电子书格式、样式、目录、元数据几乎原样保留还能断点续翻。这篇文章带你拆解这条管线是如何做到完美保留的。 为什么 EPUB 翻译这么难EPUB 本质是一个 ZIP 包正文是一堆 XHTML 文件外加content.opf元数据清单、NCX/nav目录、CSS 样式和封面图。直接用 LLM 翻译会踩三大坑标签被破坏模型可能吞掉p、改错span甚至把标签当文本翻译超长文档一本书几万字远超模型的上下文窗口包装层不翻译读者书架、书籍信息面板读的是 OPF 里的dc:title正文翻完了书名还挂在旧语言上。TranslateBooksWithLLMs 的解法是一条8 步流水线入口在 translate_epub_file()。 管线总览8 步走完一本书步骤做什么关键模块1安全解压 EPUB 到临时目录translator.py2解析content.opf清单找出所有正文文件translator.py2.5断点恢复续翻时先还原已完成的文件xhtml_translation_state.py3逐文件翻译占位符保护标签 智能分块epub_translation_adapter.py4保存译文同步更新 NCX / nav 目录标题translator.py5更新元数据lang属性、署名页attribution_page.py5.5翻译 OPF 书名与简介同步 NCX 标题metadata_translator.py6RTL/LTR 排版修正 目标语言lang属性 CJK 排版清理rtl_support.py、cjk_typography.py7重新打包 EPUB中断时输出[partial]文件translator.py️ 核心魔法一标签占位符Tag Preservation这是整条管线最精妙的设计。翻译前TagPreserver 会把所有 HTML 标签替换成[id0]、[id1]这样的占位符p classbodyspanHello world/span/p ↓ [id0]Hello world[id1]标签本体被存进一张标签地图tag mapLLM 只看到纯文本 占位符几乎不可能破坏结构。两个细节值得点赞相邻标签自动合并连着的/ppspan会合并成一个占位符既省 token 又降低模型困惑不可翻译内容也一起打包空白、章节编号如 1.、III会和标签合并避免模型去翻译编号。翻译完成后restore_tags()按地图把标签原位恢复。配套的 placeholder_validator.py 会严格校验占位符完整性——如果模型偷偷改写了占位符管线会检测并自动纠正而不是默默产出坏文件。✂️ 核心魔法二按元素边界智能分块分块在 html_chunker.py 完成。它不是按字数硬切而是沿 HTML 元素边界切分带占位符的正文保证每个 chunk 都是结构完整的片段。每个 chunk 独立送 LLM 翻译天然适配任意大小的书——这也是官方宣称无文件大小限制的原因。如果你不想保留行内格式加粗、斜体还可以开启Plain Text Modeplain_extractor.py 会把正文抽成纯段落翻译图片锚定在原段落之后块级标签保留产出更干净的排版。⏸️ 断点续翻中断不丢进度翻译一本长书可能需要数小时。管线为每个 XHTML 文件维护chunk 级检查点xhtml_translation_state.py中途断电、限速、手动暂停重启后从第一个未翻译的 chunk 继续已完成的文件直接恢复。中断产生的输出文件会被自动标记为[partial]与完成版一眼区分续翻时还能中途切换模型而不丢进度 样式与排版翻译后的整形工序正文翻完只是半成品。管线还有三步整形让译文读起来像原生排版RTL/LTR 布局修正rtl_support.py阿拉伯语、希伯来语目标会自动注入direction: rtl样式并修正 OPF 翻页方向从 RTL 源语言翻译回 LTR 则自动清理方向 CSSlang属性全面更新lang_support.py每个 XHTML 根节点重写为目标语言阅读器才能正确应用连字符、词典和 TTSCJK 排版清理cjk_typography.py把源语言样式里残留的中文字体栈、首行缩进、行距、书写模式等中式排版中和掉避免英文译文带着中文的视觉习惯。️ 元数据翻译书架上的书名也要换语言很多翻译工具忽略 OPF 包装层metadata_translator.py 专门补上这块一次 LLM 调用同时翻译dc:title书名和dc:description简介把译出的书名同步到所有 NCX 目录文件的docTitle绝不翻译作者名——dc:creator保持原样永不失败原则模型回答不合格跑题、超长、仍含原文字符就保留原值。元数据翻译是锦上添花任何异常都只记日志绝不拖累正文翻译成功正文里的目录标题translator.py 的 4.5/4.6 步也会从译文标题回填到 NCX 和 EPUB3 的nav.xhtml保证阅读器侧边栏目录与正文一致。 最后一步安全重打包所有文件修改完成后管线把临时目录重新压缩为 EPUB。整个过程通过 safe_extract_zip 等安全函数解压并追加 署名页 标注翻译工具来源——对开源生态很友好。 想深入源码从这里开始管线总控src/core/epub/translator.py标签保护src/core/epub/tag_preservation.py元数据本地化src/core/epub/metadata_translator.py分块逻辑src/core/epub/html_chunker.py断点状态src/core/epub/xhtml_translation_state.py使用文档docs/CLI.md、docs/EPUB_SCRIPT_NORMALIZATION.md相关测试tests/unit/epub/✅ 小结TranslateBooksWithLLMs 的 EPUB 翻译管线用占位符保护标签、按元素分块、检查点续翻、OPF 元数据本地化、排版整形五板斧把LLM 翻译书籍这件高风险的事做成了可信赖的工程流程。如果你需要批量翻译技术文档或小说又在意输出质量与格式保真这套管线值得作为参考范本。【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入TranslateBooksWithLLMs的EPUB翻译管线：标签、样式与元数据如何被完美保留
深入TranslateBooksWithLLMs的EPUB翻译管线标签、样式与元数据如何被完美保留【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMsTranslateBooksWithLLMs 是一款基于大语言模型的EPUB 全书翻译工具支持 Ollama、OpenAI 兼容接口、Gemini、Mistral、DeepSeek、Poe、OpenRouter 等多种 LLM。它的 EPUB 翻译管线核心位于 src/core/epub/最打动人的地方在于翻译完的电子书格式、样式、目录、元数据几乎原样保留还能断点续翻。这篇文章带你拆解这条管线是如何做到完美保留的。 为什么 EPUB 翻译这么难EPUB 本质是一个 ZIP 包正文是一堆 XHTML 文件外加content.opf元数据清单、NCX/nav目录、CSS 样式和封面图。直接用 LLM 翻译会踩三大坑标签被破坏模型可能吞掉p、改错span甚至把标签当文本翻译超长文档一本书几万字远超模型的上下文窗口包装层不翻译读者书架、书籍信息面板读的是 OPF 里的dc:title正文翻完了书名还挂在旧语言上。TranslateBooksWithLLMs 的解法是一条8 步流水线入口在 translate_epub_file()。 管线总览8 步走完一本书步骤做什么关键模块1安全解压 EPUB 到临时目录translator.py2解析content.opf清单找出所有正文文件translator.py2.5断点恢复续翻时先还原已完成的文件xhtml_translation_state.py3逐文件翻译占位符保护标签 智能分块epub_translation_adapter.py4保存译文同步更新 NCX / nav 目录标题translator.py5更新元数据lang属性、署名页attribution_page.py5.5翻译 OPF 书名与简介同步 NCX 标题metadata_translator.py6RTL/LTR 排版修正 目标语言lang属性 CJK 排版清理rtl_support.py、cjk_typography.py7重新打包 EPUB中断时输出[partial]文件translator.py️ 核心魔法一标签占位符Tag Preservation这是整条管线最精妙的设计。翻译前TagPreserver 会把所有 HTML 标签替换成[id0]、[id1]这样的占位符p classbodyspanHello world/span/p ↓ [id0]Hello world[id1]标签本体被存进一张标签地图tag mapLLM 只看到纯文本 占位符几乎不可能破坏结构。两个细节值得点赞相邻标签自动合并连着的/ppspan会合并成一个占位符既省 token 又降低模型困惑不可翻译内容也一起打包空白、章节编号如 1.、III会和标签合并避免模型去翻译编号。翻译完成后restore_tags()按地图把标签原位恢复。配套的 placeholder_validator.py 会严格校验占位符完整性——如果模型偷偷改写了占位符管线会检测并自动纠正而不是默默产出坏文件。✂️ 核心魔法二按元素边界智能分块分块在 html_chunker.py 完成。它不是按字数硬切而是沿 HTML 元素边界切分带占位符的正文保证每个 chunk 都是结构完整的片段。每个 chunk 独立送 LLM 翻译天然适配任意大小的书——这也是官方宣称无文件大小限制的原因。如果你不想保留行内格式加粗、斜体还可以开启Plain Text Modeplain_extractor.py 会把正文抽成纯段落翻译图片锚定在原段落之后块级标签保留产出更干净的排版。⏸️ 断点续翻中断不丢进度翻译一本长书可能需要数小时。管线为每个 XHTML 文件维护chunk 级检查点xhtml_translation_state.py中途断电、限速、手动暂停重启后从第一个未翻译的 chunk 继续已完成的文件直接恢复。中断产生的输出文件会被自动标记为[partial]与完成版一眼区分续翻时还能中途切换模型而不丢进度 样式与排版翻译后的整形工序正文翻完只是半成品。管线还有三步整形让译文读起来像原生排版RTL/LTR 布局修正rtl_support.py阿拉伯语、希伯来语目标会自动注入direction: rtl样式并修正 OPF 翻页方向从 RTL 源语言翻译回 LTR 则自动清理方向 CSSlang属性全面更新lang_support.py每个 XHTML 根节点重写为目标语言阅读器才能正确应用连字符、词典和 TTSCJK 排版清理cjk_typography.py把源语言样式里残留的中文字体栈、首行缩进、行距、书写模式等中式排版中和掉避免英文译文带着中文的视觉习惯。️ 元数据翻译书架上的书名也要换语言很多翻译工具忽略 OPF 包装层metadata_translator.py 专门补上这块一次 LLM 调用同时翻译dc:title书名和dc:description简介把译出的书名同步到所有 NCX 目录文件的docTitle绝不翻译作者名——dc:creator保持原样永不失败原则模型回答不合格跑题、超长、仍含原文字符就保留原值。元数据翻译是锦上添花任何异常都只记日志绝不拖累正文翻译成功正文里的目录标题translator.py 的 4.5/4.6 步也会从译文标题回填到 NCX 和 EPUB3 的nav.xhtml保证阅读器侧边栏目录与正文一致。 最后一步安全重打包所有文件修改完成后管线把临时目录重新压缩为 EPUB。整个过程通过 safe_extract_zip 等安全函数解压并追加 署名页 标注翻译工具来源——对开源生态很友好。 想深入源码从这里开始管线总控src/core/epub/translator.py标签保护src/core/epub/tag_preservation.py元数据本地化src/core/epub/metadata_translator.py分块逻辑src/core/epub/html_chunker.py断点状态src/core/epub/xhtml_translation_state.py使用文档docs/CLI.md、docs/EPUB_SCRIPT_NORMALIZATION.md相关测试tests/unit/epub/✅ 小结TranslateBooksWithLLMs 的 EPUB 翻译管线用占位符保护标签、按元素分块、检查点续翻、OPF 元数据本地化、排版整形五板斧把LLM 翻译书籍这件高风险的事做成了可信赖的工程流程。如果你需要批量翻译技术文档或小说又在意输出质量与格式保真这套管线值得作为参考范本。【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考