第五章：支持的文件格式与工作流详解

DocuTranslate 的核心抽象是 Workflow（工作流）。每种文件类型对应一个工作流，工作流内部把「转换器 → 翻译器 → 导出器」编排好。理解工作流，你就能预判某种文件能翻译成什么、能导出哪些格式、需要哪些配置。本章系统梳理所有工作流。

5.1 支持的文件格式总览

DocuTranslate 目前支持的输入格式：

暂不支持老式的 doc、xls（需先另存为 docx、xlsx）。

5.2 工作流一览表

每个工作流有固定的输入格式、可用的保存 / 导出方法与主要配置项：

注意：docx 有两条路径——既可以走 MarkdownBasedWorkflow（先转 Markdown，格式会重排，但能与 PDF 统一处理并导出 html/md），也可以走 DocxWorkflow（保持原格式回填）。用 Client SDK 时会根据参数自动选择；用 Workflow API 时由你显式选择。

5.3 MarkdownBasedWorkflow（Markdown 中转工作流）

这是最核心、最常用的工作流，处理 PDF、图片以及「愿意接受格式重排」的 docx / md。

流程：

PDF/图片/docx ──[MinerU 等转换器]──> Markdown ──[翻译]──> 译文 Markdown ──[导出]──> HTML / Markdown / docx

特点：

• 依赖转换器（converter）：PDF / 图片必须经 MinerU 转成 Markdown，因此需要配置 convert_engine（mineru / mineru_deploy / identity 等）。
• 输出灵活：可导出 HTML（公式、表格显示最佳）、纯 Markdown、含图片的 Markdown zip，或再转回 docx（由 md2docx_engine 控制）。
• 缺点：丢失原始排版（版式重排）。

md2docx_engine 取值：

• python：纯 Python 转换（无需外部依赖）。
• pandoc：使用 Pandoc 转换（需系统装有 Pandoc，效果更好）。
• auto：装了 Pandoc 就用 Pandoc，否则用 Python（默认）。
• null：不生成 docx。

5.4 保持格式的工作流：DocxWorkflow / XlsxWorkflow

当你不希望丢失排版时，用专门的保持格式工作流：

• DocxWorkflow：直接在原 Word 文档的结构上替换 / 追加译文，保留样式、图片、表格。
• XlsxWorkflow：在原 Excel 上翻译单元格，保留公式引用外的内容；可用 translate_regions 指定只翻译某些区域（如 "Sheet1!A1:B10"）。

共同的关键配置 insert_mode：

• replace：译文替换原文（默认）。
• append：原文后追加译文（双语对照）。
• prepend：原文前插入译文。

separator 用于 append/prepend 模式下原文与译文之间的分隔符（默认 \n）。

5.5 纯文本与结构化：TXTWorkflow / JsonWorkflow

• TXTWorkflow：翻译纯文本。可用 segment_mode 控制分段方式：line（按行）、paragraph（按段落）、none（不分段）。同样支持 insert_mode。
• JsonWorkflow：翻译 JSON 中的部分值。核心是 json_paths——用 JSONPath（jsonpath-ng 语法）指定哪些字段要翻译，例如 ["$.*", "$.name"] 或 "$.data.*"。未匹配的字段保持原样。这对翻译 i18n 语言包、配置文件非常有用（详见第八章）。

5.6 电子书、字幕与网页

• EpubWorkflow：翻译 EPUB 电子书，保留章节和目录结构，可导出仍为 epub；支持 insert_mode（可做双语电子书）。
• SrtWorkflow / AssWorkflow：翻译字幕，保留时间轴，只翻译字幕文本。srt 导出 srt，ass 导出 ass，也都可导出 html 预览。
• HtmlWorkflow：翻译 HTML 网页，保持标签结构，只翻译可见文本，支持 insert_mode。

5.7 如何选择工作流

决策建议：

1. PDF / 扫描件 / 图片 → MarkdownBasedWorkflow（+ MinerU）。接受版式重排。
2. Word 且要保留排版 → DocxWorkflow。
3. Word 但只要内容、想导出 html/md → MarkdownBasedWorkflow。
4. Excel → XlsxWorkflow（可指定区域）。
5. 小说 / 长文本 txt → TXTWorkflow；电子书 → EpubWorkflow。
6. 字幕 → Srt / AssWorkflow。
7. 语言包 / 配置 JSON → JsonWorkflow（配 json_paths）。
8. 网页 → HtmlWorkflow。

用 Client SDK 时（第六章），你通常不用手动选工作流——Client.translate() 会根据文件类型自动检测并选择合适的工作流。只有用底层 Workflow API（第七章）时才需要显式实例化对应工作流。

5.8 小结

• DocuTranslate 用「工作流」为每种格式定制「转换 → 翻译 → 导出」流程。
• 记住核心分野：要不要保留排版决定走 MarkdownBased（重排）还是 Docx/Xlsx（保持格式）。
• 每个工作流的可导出格式不同，翻译前想清楚你要什么输出。
• 下一章开始进入编程接口：先讲最简单的 Client SDK。