第一章：DocuTranslate 项目概览与核心特性

DocuTranslate 是一个基于大语言模型（LLM）的轻量级本地文件翻译工具。它的官方仓库位于 xunbu/docutranslate，在 PyPI 上以 docutranslate 发布，要求 Python 3.11 及以上版本，使用 MPL-2.0 开源许可协议。

与在线翻译网站、传统翻译软件不同，DocuTranslate 把「文件解析」「大模型翻译」「格式还原」串成了一条可编排的流水线（Workflow），既提供开箱即用的 Web 界面和整合包，又提供 Client SDK、Workflow API、REST API 与 MCP 服务，能覆盖「个人偶尔翻译一篇论文」到「团队在服务端批量集成翻译能力」的各种场景。

1.1 一句话理解

DocuTranslate 可以理解为：一个自带文件解析与格式还原能力、模型无关（model-agnostic）、可本地部署的大模型文档翻译引擎。

你只要准备好一个兼容 OpenAI 接口的大模型（云端或本地都行），把文件交给它，它就能：

1. 把 PDF、Word、Excel、EPUB、字幕等各种格式的文件解析成可翻译的中间表示；
2. 把内容分块后并发调用大模型进行翻译；
3. 再把译文还原回原始格式（或导出成 Markdown / HTML 等）。

整个过程运行在你自己的机器 / 服务器上，文件不必上传到第三方翻译平台（PDF 在线解析除外，详见第四章）。

1.2 它解决什么问题

大模型翻译效果虽好，但直接把文件丢给 ChatGPT 之类的对话框会遇到很多现实问题：

• 格式无法保持：复制粘贴会丢掉表格、公式、样式，Word / Excel 的排版全乱。
• 长文档超长：一篇论文、一本小说远超单次上下文，需要人工切分、逐段翻译再拼接。
• PDF 难以处理：扫描件、双栏排版、公式、代码块无法直接提取文字。
• 术语不统一：同一个专有名词在不同段落被翻译成不同词，缺乏术语对齐。
• 难以自动化：想批量翻译、想接进自己的系统或 AI 助手，缺少现成接口。

DocuTranslate 针对这些痛点给出的方案是：

• 多格式解析 + 格式还原：docx、xlsx 保持原格式翻译；PDF 通过 MinerU 解析出表格、公式、代码。
• 自动分块与并发：内置分块（chunk_size）与并发（concurrent）机制，长文档也能高效翻译。
• 自动术语表：可自动生成术语表并在全篇对齐，也支持手动传入术语字典。
• 多种集成方式：Web UI、Client SDK、Workflow API、REST API、MCP，一处能力多处复用。
• 本地优先：可搭配本地大模型（Ollama / LM Studio）和本地部署的 MinerU，实现完全离线 / 内网翻译。

1.3 核心特性速览

官方 README 列出的核心特性如下：

• ✅ 支持多种格式：能翻译 pdf、docx、xlsx、md、txt、json、epub、srt、ass 等多种文件。
• ✅ 自动生成术语表：支持自动生成术语表实现术语对齐。
• ✅ PDF 表格、公式、代码识别：使用 mineru（在线或本地部署）进行 PDF 解析，支持识别并翻译学术论文中常见的表格、公式与代码。
• ✅ JSON 翻译：支持通过 JSONPath（jsonpath-ng 语法）指定 JSON 中需要翻译的值。
• ✅ Word/Excel 保持格式翻译：支持 docx、xlsx 文件保持原格式翻译（暂不支持老的 doc、xls）。
• ✅ 多 AI 平台支持：支持绝大部分兼容 OpenAI 接口的 AI 平台，可自定义提示词并发高性能翻译。
• ✅ 异步支持：为高性能场景设计，提供完整异步支持与可多任务并行的服务接口。
• ✅ 局域网、多人使用支持：支持在局域网中多人同时使用。
• ✅ 交互式 Web 界面：提供开箱即用的 Web UI 和 RESTful API，方便集成与使用。
• ✅ 小体积、多平台整合包：不到 40MB 的 Windows、Mac 整合包（懒人包）。

⚠️ 注意：翻译 pdf 时会先转换为 Markdown，这会丢失原先的排版。对排版有严格要求的用户请留意——PDF 翻译得到的是「内容忠实、版式重排」的结果，而不是「原版式覆盖翻译」。

1.4 五种使用形态

DocuTranslate 的能力可以通过五种方式使用，核心翻译引擎是同一套：

1. 整合包（懒人包）：从 GitHub Releases 下载解压即用，填入 API-Key 就能翻译，最适合非技术用户。
2. Web UI：docutranslate -i 启动本地网页界面，浏览器访问即可，支持局域网多人共享。
3. Client SDK：from docutranslate.sdk import Client，几行 Python 代码完成翻译，最适合脚本 / 自动化。
4. Workflow API：更底层、更精细的编排接口，可自定义转换器、翻译器、导出器，适合深度集成。
5. REST API / MCP 服务：把 DocuTranslate 作为服务跑起来，供其他系统或 AI 助手（Claude Desktop、Cherry Studio 等）调用。

本教程会依次覆盖这五种形态。你可以只看自己需要的部分：只想翻文件看第二、三、四章；要写代码集成看第六、七、八章；要做服务 / 助手集成看第九、十章。

1.5 整体架构与工作流水线

理解 DocuTranslate 的关键是理解它的流水线（pipeline）模型。一次翻译通常经历三个阶段：

原始文件 ──[Converter 转换器]──> 中间表示(通常是 Markdown/文本) ──[Translator 翻译器]──> 译文 ──[Exporter 导出器]──> 目标格式文件

• Converter（转换器）：负责把输入文件解析成可翻译的中间表示。例如 PDF 通过 MinerU 转成 Markdown；identity 引擎则表示「不额外转换」。
• Translator（翻译器）：负责调用大模型翻译，内部处理分块、并发、重试、限速、术语表、思考模式等。
• Exporter（导出器）：负责把译文还原 / 导出为目标格式，例如 HTML、Markdown、DOCX、原格式回填等。

不同文件类型对应不同 Workflow（工作流），它把上面三个阶段按该格式的特点组合好。第五章会详细讲解每种工作流及其输入 / 输出格式。

从仓库目录结构也能看出这套设计（docutranslate/ 包内）：

• converter/：各种文档转换器（如 x2md 下的 MinerU 转换器）。
• translator/：AI 翻译器（如 ai_translator/md_translator）。
• exporter/：各种导出器（如 md/md2html_exporter）。
• workflow/：把上述组件编排起来的工作流（md_based_workflow、txt_workflow、docx_workflow 等）。
• glossary/：术语表生成与管理。
• sdk.py：面向使用者的高层 Client SDK。
• cli.py / app.py / server/：命令行入口与 Web / API 服务。
• mcp/：MCP 服务器实现。
• config.py：读取环境变量、组织默认配置。

1.6 与其他翻译方案的区别

DocuTranslate 的定位非常清晰：把「文件级翻译」这件事做成可自托管、可编程、模型无关的工具链，特别适合注重隐私、需要批量或自动化、且希望自由选择模型的个人与团队。

1.7 本教程的学习路线

本教程共 12 章：

1. 第 1 章：项目概览与核心特性（本章）。
2. 第 2 章：安装、部署与快速上手（pip / uv / git / docker / 整合包）。
3. 第 3 章：Web UI 界面操作详解。
4. 第 4 章：大模型与 PDF 解析引擎配置（API Key、MinerU）。
5. 第 5 章：支持的文件格式与工作流详解。
6. 第 6 章：Client SDK 编程使用。
7. 第 7 章：Workflow 高级 API 开发。
8. 第 8 章：术语表、自定义提示词与 JSON 翻译。
9. 第 9 章：REST API 与服务集成。
10. 第 10 章：MCP 集成与 AI 助手接入。
11. 第 11 章：环境变量与部署配置。
12. 第 12 章：最佳实践与常见问题排障。

建议先读完第 1、2 章建立整体认知并跑通第一个翻译，再根据自己的角色（普通用户 / 开发者 / 运维）选择后续章节深入。