输入与输出格式

本页集中说明书籍输入、导出选择、保留范围及原文依赖。 流程选择见翻译指南，命令和设置见 CLI 指南与配置参考。

输入输出矩阵

输入	CLI 默认输出	其他可导出格式	主要保留边界
EPUB	EPUB	TXT、HTML、Markdown、DOCX	回填原 XHTML 和资源，不保证原分页
FB2	EPUB	TXT、HTML、Markdown、DOCX	重建章节，不导出 FB2 或回填原 FB2 模板
TXT	EPUB	TXT、HTML、Markdown、DOCX	段落和可识别标题，不保留富排版
Markdown	EPUB	TXT、HTML、Markdown、DOCX	标题层级和段落，不是完整 Markdown 语法往返
HTML / XHTML	HTML	EPUB、TXT、Markdown、DOCX	回填静态原文件，不执行浏览器逻辑
DOCX	DOCX	EPUB、TXT、HTML、Markdown	重建受支持的段落、表格、列表与样式
PDF，经 MinerU	EPUB	TXT、HTML、Markdown、DOCX	重排转换后的 HTML，不恢复原 PDF 页面
PDF，经 BabelDOC	PDF	EPUB、TXT、HTML、Markdown、DOCX	将译文回填至外部 bridge 已保存的会话

CLI 的 --format epub|txt|html|markdown|pdf|docx 覆盖默认选择。 CLI、Web 和 Desktop 均仅允许保存为 BabelDOC 状态的项目导出 PDF。 改变当前 pdf_backend 设置不会转换已有项目，也不会改变其已保存后端。 Web/Desktop 使用各自的导出选择界面；表格中的自动默认值描述 CLI 命令。

文件命名与双语输出

CLI 默认在原文件旁的 output/ 目录输出：

版本	默认文件名	英语目标示例
单语	<source-stem>.<target-language>.<ext>	output/book.en.epub
双语	<source-stem>.<target-language>-bi.<ext>	output/book.en-bi.epub

目标语言默认为 zh；Markdown 扩展名为 .md。 显式 --out editions/book.epub 保留该单语路径，双语版派生为 editions/book-bi.epub，不额外插入语言后缀。 即使只请求双语，也使用相同的 -bi 派生规则。 请让文件扩展名与所选格式一致。

默认只启用单语版。--bilingual 开启双语输出； --no-mono --bilingual 只请求双语版。 EPUB、HTML、TXT、Markdown 和 DOCX 可按段配对原文与译文。 PDF 将原文页与对应译文页并排拼成一张更宽的页面，见 BabelDOC。

• output.bilingual_order 选择译文在前（默认）或原文在前。 按段配对的格式先显示所选版本；PDF 将“在前”的版本放在左侧。
• EPUB/HTML 原文默认淡化；设置 output.bilingual_preserve_source_style: true 后继承正常书籍样式。
• DOCX 原文默认使用正常正文样式，不强制灰字、高亮或缩小字号。 同一保留选项可恢复已记录的原文字符样式，包括段落和表格中的混合跨度。
• EPUB 未译段落只显示一份原文，保留链接和 ruby；双语顺序不会复制原文回退内容。

原文样式与顺序独立，只需重新导出，不需重译。 Web 下载和 Desktop 保存位置由各自平台界面决定，不采用 CLI 的原文件旁目录规则。

EPUB

EPUB 导出 EPUB 时尽量回填原 XHTML 模板，保留样式、图片、目录、锚点和内部链接。 超长段续段先合并回原逻辑段落；双语原文保留自己的标记，不复制锚点 ID。

高置信度脚注／尾注引用会将原语言注释正文提供给翻译作为上下文； 普通导航、回链和外部链接不作为注释借用。 位于 spine 的注释资源仍是正常待译正文；借用的上下文不会追加到引用段落中。

译后注释对齐在固定 target 上定位链接。覆盖全部原文的范围可直接映射，无需模型； 局部范围和点注释可能需要额外请求。 无法使用或互相冲突的位置降级为段末可点击标记，不删除译文或链接。 关闭对齐可避免这些请求，但可能失去行内位置。 完整翻译流程可以重试降级注释，单独导出不会。

导航遵循已保存章节边界。某资源仅由一个目录项指向时，即使片段锚点缺失， 仍可在该资源起点建立边界。生成的 EPUB 保留已存标题层级； 没有 EPUB 模板的输入会重建，而非获得原书版式。

EPUB 默认增加可选的“关于此翻译”页，其他格式不增加。 简体中文目标使用中文页面，其他目标目前使用英文回退。 可设置 output.about_page: false 关闭。

HTML 与 XHTML

HTML 将连续行内正文整组翻译，包括布局容器、列表、表格及控件中的直接文本。 块边界、媒体、<br> 和受保护子树分隔翻译区域。 链接和带样式跨度用原文范围表示；模型不改写 URL 或结构属性。

alt、title、placeholder 和描述性 ARIA 标签等文案属性使用独立纯文本片段， 回填到相应 DOM 位置，不追加为 TXT、Markdown 或 DOCX 正文。 脚本、样式、模板、代码、公式、隐藏／禁译子树和可编辑内容不翻译； 输入框草稿不视为正文。

HTML 导出 HTML 时回填完整原文件，保留 doctype、头部元数据、全局 CSS、 外壳属性和布局，保存的章节分组不能替代源文档。 替换输出前需要匹配原始内容和片段原文；不会改写原文件或已付费翻译状态。

行内范围使用校验后的注释位置，交叉／重叠兄弟范围会被拒绝，不猜测套用。 样式定位失败不删正文；普通链接无法对齐时，以原文标签保留在段末。 局部跨度可能增加对齐请求，覆盖全部原文的包装不需要。

HTML 导出为单个 .html 文件：

• 已有 data URI 保持内嵌。
• HTML 原文中可读取的本地图片／媒体转换为 data URI 内嵌。
• EPUB 导出 HTML 只从 EPUB 容器内读取媒体； 缺失引用不会回退读取 EPUB 旁边或工作目录中的文件。
• 不下载远程资源。外链样式表和 CSS url(...) 资源仍保留引用，即使它们指向本地文件。

这是静态文件适配，不是实时网页翻译，也不是通用离线网页打包器。 文译不执行 JavaScript、不计算外部样式表可见性、不检查实时 shadow DOM 或抓取远程资源。 保留的活动内容不会被净化为安全文档，应像对待原文件一样对待导出的 HTML。

Markdown、文本与 FB2

Markdown ATX 标题（# 到 ######，后接空白与标题文本）划分章节并记录层级。 空行分隔正文段落，可识别的日文章节标签也作为边界； 没有可识别标题时使用单章。带页码的纯文本目录行仍是正文。

保存的标题层级用于生成 EPUB 标题／导航和 DOCX 大纲。 导航将标题放在此前最近的较低层级标题之下，跳级不会补造条目。 TXT/Markdown 输出重建标题和段落，不保留精确空白或完整 Markdown AST。 不要假设任意围栏代码、行内语法、表格或内嵌 HTML 都受到专用 HTML 导入器的保护。

FB2 读取嵌套 section、标题、正文及受支持的诗歌／引用内容，保留图片引用供重建。 专门的 notes body 会跳过。导出生成新书，而非回填 FB2 模板；没有 FB2 writer。

DOCX

DOCX 与其他书籍共享准备、术语、润色、Review 和续跑流程。 它按支持的结构重建文档，不是 Word 文件包的完全无损往返。

• 记录标题／大纲层级，一级标题划分章节。
• 简单表格按单元格重建，不支持合并单元格和嵌套表格。
• 自动列表按编号／项目符号分组重建，以原列表身份决定重新计数； 正文已有可见序号时不重复添加。
• 在支持范围内保留记录的加粗、斜体、下划线、颜色、字号、段落对齐与底纹。
• 整段统一样式不增加定位调用。有意义的混合样式跨度可能需要模型对齐； 失败跨度按比例回退，不丢弃整段。仅字体／字号差异不触发该请求。
• 目标语言字体策略仅用于译文，不用于未译原文或双语原文副本。 中文译文使用内置宋体策略；实际显示仍取决于字体是否可用。

标题层级支持 Word 导航窗格。不应假定复杂表格布局、动态 Word 字段或精确分页会被保留。 对版式敏感的文档，先检查有代表性的导出样本。

PDF：先选择后端

	MinerU	BabelDOC
默认使用	是	需开启
主要目标	经 HTML 提取、重排文本	尽可能保留原页面布局
服务边界	外部转换服务	外部 AGPL bridge，独立仓库／进程，仅 HTTP
纯扫描图片输入	使用此路径或先 OCR	需要可提取文本层
CLI 默认输出	EPUB	PDF
PDF 导出	不支持	需要保存的 bridge 会话

MinerU

CLI 首次转换要求环境变量 MINERU_API_KEY。 转换后的 HTML 缓存在 state/<book>/targets/<target-language>/source/<source-sha256>/converted.html。 匹配的重试复用转换结果，不会因文件名相同就复用另一份 PDF。 开始长篇翻译前先检查提取质量；OCR／转换质量会限制后续全部阶段。

MinerU 状态支持重排导出，不支持重建 PDF。 部分解析单元允许有意保存空译文，不自动视为待译。 之后改为 BabelDOC 配置，也不能补出缺失的版面会话。

BabelDOC

另行运行 wenyi-babeldoc-bridge 服务，选择 pipeline.pdf_backend: babeldoc。 默认地址为 http://127.0.0.1:8765， pipeline.babeldoc_pages 可选择从 1 起计的页码。 文译不 import BabelDOC，也不在 Core/CLI 中包含其 AGPL 运行时； 提取和回填仅经 HTTP。外部服务的部署及许可证要求需另行核对。

调用 bridge 前，文译会检查所选页面是否只有图像。 没有可提取文本层时应使用 MinerU 或先 OCR。 章节按 PDF 书签组织，无目录时退为单章。

翻译连贯性方面，只有正文单元提供前后正文上下文。 显式标题限定区间；装饰、表格、图注和未知版面角色不混入上下文。 非正文批次不带正文概览／梗概上下文，但仍参与翻译。 版面误分类可能损失有用上下文；这不等于重建表格行列关系。

PDF 重新导出将保存文本发送到 bridge。 缺失、空字符串或纯空白译文在本次导出中回退到原段落，不修改保存译文。 默认不绘制版面框或角色标签。字体、文本扩张及外部引擎仍会限制版式保真度。

使用支持标注的 bridge 时，文译复用现有对齐器，在已完成的译文中定位 PDF 公式、 上下标／引用角标、混合样式和链接文字。bridge 恢复原公式／角标对象及样式， 并根据排版后的字形重建网址和内部页码链接，也支持文献引用中常见的已解析命名目标。 目标页不在导出范围内的内部链接会被省略； 其他 PDF 动作类型不予重建。公式识别效果仍取决于 BabelDOC。

开启 pipeline.annotation_alignment 可定位译文中的 PDF 标注。 导出逐项处理：同段中正常对齐的链接、样式、公式和角标仍然显示， 仅忽略位置缺失、无效、过期或处于回退状态的项。 不会猜位置、阻止导出或将已译正文替换为原文。 公式重叠或不同样式冲突时，仅忽略参与冲突的项。

导出本身不调用模型。修改已保存译文后，续跑翻译可刷新缺失／过期的对齐， 但修复阶段不会自动重试译文未变的 PDF 回退项。 CLI 日志记录各类标注的位置校验通过率、应用率、跳过数量和原因； bridge 会话目录的 annotation_stats.json 包含逐项 ID。 这些比率只衡量校验及应用结果，不代表已证明语义位置正确； 译文与原文恒等位置分开统计。逐项忽略策略需要更新并重启 bridge。 旧的纯文本项目需要重新导入 PDF 才能补齐标注元数据。

同时保留文译状态和 bridge 会话。 长任务应在 bridge 侧用 WENYI_BABELDOC_STATE_DIR 指定持久目录。 只有会话目录仍在，且使用相同 Python/BabelDOC 版本时， 冻结的提取会话才能在重启后恢复。 系统临时目录可能在重启后消失；仅凭文译章节译文无法重建该 PDF 版面会话。

双语 PDF 将原文页与 bridge 生成的对应译文页横向拼接，每对页面形成一张更宽的 PDF 页面。 双语顺序选择“在前”的版本放在左侧，另一版放在右侧。 两侧保留原始物理尺寸、可见裁切范围与方向，高度不同时顶部对齐；文字和矢量内容不转成图片。 原文样式选项不影响此布局。 内部跳转目标会重映射到输出拼页中对应的左／右半页，也支持不连续的页码选择。

除 bridge 会话外，还需保留原始 PDF。配对使用导入时保存的页码选择，而不是当前配置。 原文已变、PDF 无法读取或两侧页数不匹配时会报错，不猜测配对，也不以不完整文件覆盖 已有导出。单语 PDF 导出保持不变。

原文快照

原文快照记录 AI 准备前解析的章节和原文段落， 绑定原文哈希与解析设置，支持只读章节预览，只在这些输入匹配时复用。 它不包含已初始化的翻译 manifest，也不允许编辑尚未提交的暂存译文。

请同时保留原始输入和保存状态。 EPUB、HTML 回填依赖原模板／资源；HTML 导出还校验提取片段原文和记录哈希。 保存的原文预览不能替代全部原始资源。 文件名相同但内容不同的新输入需要独立翻译状态。

一致导出快照

独立 assemble 一致读取已保存的书籍，再渲染该快照。 它可与其他翻译流程并行，之后的新批次只会出现在下一次导出。

重新导出不调用翻译模型，不重新执行准备、Review、润色或注释修复； BabelDOC PDF 导出仍会请求外部 bridge。 简体中文目标的导出标点规范化只修改内存副本，不改保存译文，并保留注释和样式的位置； 其他目标跳过该机械规范化。

仅改变导出格式、双语顺序、原文样式或导出字体／标点策略时， 重新导出即可，无需再次付费翻译。