DocuTranslate：把 LLM 翻译塞进本地文件流水线

它要解决的不是翻译质量，是文件格式的碎片化

把一段文字丢给大模型翻译，是几行代码的事。真正烦人的是文件：docx 里段落和样式绑在一起，xlsx 里文本散在单元格中，srt 带时间轴和序号，epub 是压缩包里的 XHTML 集合，pdf 更极端，它根本没有「段落」这个概念。每接一种格式，都要写一遍解析、切分、回填。DocuTranslate 的定位就是把这层重复工作收拢成一个命令行工具和一套 HTTP 接口，翻译本身交给用户自己配置的模型端点。README 把它描述为一个「lightweight local file translation tool based on Large Language Models」，重点落在 local 和 file 上，而不是模型本身。目标读者是需要在本地或局域网内批量处理文档的人：翻译论文的研究者、处理字幕的译者、要把产品文档本地化的开发者。它不是给终端用户准备的 SaaS，虽然提供了 Web UI，但你要自己填 API Key、自己起服务。

格式支持背后的实际解析路径

README 列出的格式清单是 pdf、docx、xlsx、md、txt、json、epub、srt、ass。这些格式的处理难度差别很大，工具对它们的支持深度也不一样。docx 和 xlsx 走的是保留原格式的路线，README 明确写了「maintaining original formatting」，同时注明不支持 doc 和 xls 这两个旧二进制格式，也就是说你手上的老文件必须先另存为新格式。json 的处理方式比较特别：不是整文件翻译，而是用 jsonpath-ng 语法指定要翻译的值所在的路径，其余结构原样保留。这一点对配置文件和 i18n 资源文件很实用，对嵌套极深的 json 则需要你自己写对路径表达式。srt 和 ass 是字幕格式，翻译时要处理时间轴与文本的对应关系，README 没有展开细节。pdf 是唯一一条走转换的路径：先转成 markdown，再翻译。README 用加粗提示了这一步会 lose the original layout，并直接点名「Users with strict layout requirements should take note」。这不是可以绕过的实现细节，而是这条流水线的固有代价。

PDF 路径上的 MinerU 依赖与表格公式识别

PDF 转换环节交给 mineru，README 说它支持在线或本地部署两种方式。这是整个项目里最重的一个外部依赖，也是决定 PDF 翻译能不能用的关键。普通 PDF 提取文本不难，难的是识别表格结构、数学公式和代码块，这三样恰好是学术论文里最密集的内容。README 把「PDF Table, Formula, Code Recognition」列为一项特性，并说明解析由 mineru 完成。这意味着两件事：第一，PDF 翻译的效果上限由 MinerU 的解析质量决定，DocuTranslate 本身在这一环没有太多可调空间；第二，如果选择本地部署 MinerU，你需要额外的机器资源和部署工作，这部分成本不在 DocuTranslate 的安装命令里体现。环境变量表里单独列了 DOCUTRANSLATE_MINERU_TOKEN，说明在线方式需要申请 token。表格转成 markdown 后能否还原成表，取决于解析器，而不是翻译器。用之前拿一篇带合并单元格的论文试一次，比读任何说明都直接。

安装与启动：四条路径，同一套环境变量

README 给了 pip、uv、git、docker 四种获取方式。pip 路径是 pip install docutranslate，需要 MCP 扩展时加 pip install docutranslate[mcp]，然后用 docutranslate -i 进入交互界面。uv 路径是先 uv init，再 uv add docutranslate，运行时用 uv run --no-dev docutranslate -i。git 路径是克隆仓库后 uv sync --no-dev，需要 MCP 时加 --extra mcp，或 --all-extras 装全部。docker 最省事：docker run -d -p 8010:8010 xunbu/docutranslate:latest，README 还给出了带版本号的写法 docker run -it -p 8010:8010 xunbu/docutranslate:v1.5.4，说明镜像按版本打标签。服务启动后默认监听 8010，浏览器访问 http://127.0.0.1:8010，Swagger 文档在 /docs。命令行开关有几个值得注意：--host 0.0.0.0 允许局域网内其他设备访问，-p 改端口，--cors 开启默认跨域设置，--with-mcp 会在同一个端口上额外挂出 MCP 的 SSE 端点并共享任务队列。Python 版本要求是 3.11 及以上，这是 README 徽章里写明的。

MCP 模式的两种接法与环境变量清单

DocuTranslate 可以作为 MCP 服务器被其他客户端调用，README 给了 uvx 免安装和 SSE 两种配置。uvx 方式在客户端配置里写 command 为 uvx，args 为 ["--from", "docutranslate[mcp]", "docutranslate", "--mcp"]，模型信息通过 env 传入。SSE 方式需要先起服务：docutranslate --mcp --transport sse --mcp-host 127.0.0.1 --mcp-port 8000，然后在客户端里填 http://127.0.0.1:8000/mcp/sse。还有 streamable-http 传输模式。环境变量一共七个：DOCUTRANSLATE_API_KEY、DOCUTRANSLATE_BASE_URL、DOCUTRANSLATE_MODEL_ID 三个必填，分别对应密钥、端点地址、模型 ID；DOCUTRANSLATE_TO_LANG 默认 Chinese；DOCUTRANSLATE_CONCURRENT 默认 10，控制并发请求数；DOCUTRANSLATE_CONVERT_ENGINE 指定 PDF 转换引擎；DOCUTRANSLATE_MINERU_TOKEN 是 MinerU 的 token。这套变量名带 DOCUTRANSLATE_ 前缀，说明设计上考虑了与同机其他服务共存。并发默认 10 是个需要按端点限流能力调整的值，本地跑小模型时这个数字可能直接打满显存。

局域网多用户与并发是它的设计前提，不是附加功能

README 把「LAN & Multi-user Support」和「Async Support」都列在特性里，并且强调是为高性能场景设计的，提供完整的异步支持和并行多任务接口。这解释了几个设计选择：为什么默认要起一个 Web 服务而不是纯 CLI，为什么 --host 0.0.0.0 和 --cors 是两个独立开关，为什么 MCP 的 SSE 端点可以和 GUI 共享端口与队列。它假设的使用场景是几个人或一个小组共用一个翻译服务，各自提交文件，服务端按 DOCUTRANSLATE_CONCURRENT 控制对模型端点的压力。这个假设也带来约束：单机部署，没有提到任何任务持久化、断点续传或失败重试的机制，README 里也没有出现数据库或队列中间件的字样。翻译一个几百页的 epub 期间如果进程被杀，能恢复成什么样，材料里没有说明。批量任务前先想清楚这一点。

什么时候它不合适：版式、扫描件与旧格式

最明确的排除条件 README 已经写了：对版式有严格要求的 PDF 不要用。转换到 markdown 会丢掉原始布局，双栏排版、页边注、图注与正文的相对位置都无法保证。第二类不适合的情况是扫描件和图片型 PDF，材料里没有提到 OCR 能力，MinerU 的解析范围在 README 中没有展开，所以无法确认这类文件能否处理。第三类是旧版 Office 二进制格式，doc 和 xls 明确不在支持列表内，需要先转换。第四类是需要术语一致性的专业领域：工具提供了自动生成术语表的功能，README 说它「ensure term alignment」，但术语表如何注入提示、生成后能否人工修订、修订结果如何复用，材料里都没有说明，只凭这一句无法判断它在术语密集场景下的实际表现。如果你的文档属于以上任何一类，先解决格式或流程问题，再考虑这个工具。

与直接调用模型 API 或专业翻译平台的差别

一个直接的替代方案是自己写脚本调模型 API。两者在翻译质量上没有本质差别，因为用的是同一个模型；差别在于你要自己实现 docx 的段落切分与样式回填、xlsx 的单元格遍历、srt 的时间轴对齐、epub 的压缩包读写，以及 json 的路径定位。DocuTranslate 把这些做成了现成的接口，代价是你要接受它对这些格式的处理约定。另一个方向是 DeepL、Google Translate 这类翻译平台：它们的优势是无需自备模型端点、延迟稳定、按字符计费可预测，劣势是术语和风格的可控性弱，且文档需要上传到第三方。DocuTranslate 走的是相反的路：模型端点由你指定，内容流向由你决定，翻译风格通过自定义提示控制，但你要自己承担模型成本、并发调优和端点可用性。README 提到「Multi-AI Platform Support」和「custom prompts」，这两项是它相对封闭平台的主要差异点。选哪边，取决于你的文档能不能离开自己的网络。

许可证与版本节奏

项目采用 MPL-2.0。这是一个文件级的弱 copyleft 许可证：你修改过的源文件需要以同样许可证公开，但把它作为依赖集成进更大的作品时，通常不会波及整个作品。具体的合规判断需要你的法务来看，这里只说明许可证标识本身。版本方面，材料显示最近的三个发布是 v1.7.9、v1.7.8、v1.7.7，时间跨度从 2026 年 6 月到 9 月，节奏大约每月一版，属于活跃维护但不算高频。docker 镜像按版本打标签，README 里同时给了 latest 和具体版本号两种写法，生产环境用固定版本号更稳妥。升级成本取决于你用的是哪条路径：pip 和 uv 安装的升级就是重装依赖，docker 是换镜像标签，git 克隆的需要自己合并。MCP 相关功能是可选依赖，装在 docutranslate[mcp] 这个 extra 里，不装不影响主功能，这意味着升级时 MCP 部分的接口变动可能不会影响你的基础翻译流程。

编辑结论

如果你的输入是 docx、xlsx、epub、srt 这类结构化文件，且能接受把内容发往自选的 OpenAI 兼容端点，DocuTranslate 的格式覆盖和 MCP 接入值得先跑一遍真实样本再决定是否纳入流程。如果你的交付物是排版精确的 PDF（合同、版式敏感的宣传物料、需要保留双栏与图注位置的论文清样），这个工具在 README 里就明确写了会丢版式，不要用它。上手前先确认三件事：docutranslate -i 起服务后 /docs 的接口是否满足你的批处理方式；DOCUTRANSLATE_CONVERT_ENGINE 设为 mineru 时 MinerU 是走在线 API 还是本地部署，以及本地部署的机器成本；最后用一个含表格和公式的真实 PDF 跑一次，检查转换后的 markdown 里表格是否还成表。

官方来源

1. Issues
2. License: MPL-2.0
3. README
4. Releases
5. xunbu/docutranslate on GitHub