多语言 PDF 原格式翻译，这个需求听起来简单，实际操作起来全是坑。之前在公司内部接到一个任务，要把一批中文技术手册批量翻成英法德日四种语言，试过好几款在线翻译工具和文档处理软件，翻完基本都要重新排版，表格错位、图片乱飞、字体变方块，后期工作量比翻译本身还大。后来我干脆用 Dify 搭了一条自动化流水线，把 PDF 解析、文本切片、大模型翻译、版式还原这几个环节全部串起来，最终输出的 PDF 能保持原始版式结构，表格不错位，图片不丢失。这篇文章把我踩过的坑和完整的实施方案整理出来，给正在被 PDF 翻译折磨的朋友一个可直接参考的版本。
这篇文章适合这几类人看：企业内部有大量 PDF 文档需要多语言输出的文档工程师和技术人员；正在评估 Dify 工作流能力、想知道它能否承接真实业务场景的开发者；以及想了解“大模型 + 文档结构化处理”怎么落地的技术爱好者。我会从项目背景、方案选型、核心细节、工作流搭建、问题排查五个方面展开，全程带参数和代码，尽量让你照着就能复现。
1. 项目背景：PDF 原格式翻译到底难在哪，为什么选 Dify
1.1 先看清需求：用户口中的“原格式”到底是什么
说到“原格式翻译”，很多人第一反应是“PDF 翻完之后看起来和原来一模一样”。但我在实际项目里跟业务方对需求时发现，大家真正要的不是像素级一致，而是这几个可量化的指标：
- 段落顺序和层级关系不变。原文是标题、正文、列表、表格，翻译后仍然保持这个结构，不能变成一大坨纯文本。
- 表格不错位。表格是最容易翻坏的部分，中文翻英文后文本长度变了，单元格里文字溢出，列宽失衡，整个表格直接崩掉。
- 图片和图表位置基本稳定。图片本身不需要翻译，但图片周围的文字、图注、编号要对得上。
- 字体能正常显示。中文文档里常见宋体、黑体，翻成英文后如果字体映射不对，可能出现乱码或方块字。
说白了，“原格式”在工程实现上是一种近似还原，只要阅读体验不打折、结构不塌，就算达标。你如果一上来就追求 100% 版式复刻，那等于在做排版软件，投入产出比会非常低。
1.2 技术选型的十字路口：为什么我放弃了一堆现成工具
接手这个需求后，我第一反应是去找现成工具。市面上的 PDF 翻译软件、在线文档翻译平台、浏览器翻译插件，我几乎都过了一遍，但逐一被否掉：
- 通用在线翻译工具：对 PDF 的原格式保留能力很弱，尤其面对图文混排、分栏、表格嵌套时，输出往往是“文字流”，排版全丢。
- 传统翻译 API + PDF 库自研：需要自己处理 PDF 解析、分段、调翻译接口、再拼回 PDF，开发成本高，而且不同语言的分段策略不一样，后期维护很累。
- 通用大模型直接读 PDF：理论上 LLM 能读懂 PDF 提取后的文本，但长文档很容易爆 token，而且英文翻译成中文还好，中文翻译成德文法文时，语序变化会导致文本长度剧烈波动，没有中间层做排版控制的话，输出不可用。
最后我把目光放在 Dify 上。理由也很直接：Dify 本身是一个 LLM 应用开发平台，工作流编排能力成熟，我不用从零写调度代码，把解析、翻译、还原做成一个个节点拖拽连接就行；模型供应商统一管理，换模型只改配置不改代码；工作流还能直接 API 化嵌入业务系统。更关键的是，Dify 支持代码节点，像 PDF 解析和 PDF 生成这种非 LLM 操作，可以嵌入 Python 脚本执行，灵活性比我预想的高很多。
我搭建这套流程时使用的是 Dify 1.17.1，工作流里对于工具调用、代码节点、模型供应商管理的体验已经比较成熟。如果你用的是更新的版本，节点名称可能有细微差异，但整体思路是完全一致的。
2. 整体设计方案：四层流水线加一个兜底策略
2.1 方案总览：把厚书拆成便签，翻译完再贴回去
我最终敲定的方案，可以概括成四个字：拆、译、合、查。
“拆”是解析和切片。把 PDF 里面的文本内容提取出来，按段落切分成若干个语义完整的片段；“译”是翻译这些片段；“合”是把翻译后的文本按原顺序回填进一个版式模板里，生成新的 PDF；“查”是后置校验，检查表格是否错位、是否有乱码、图片是否丢失。
打个比方，这个过程就像把一本厚书拆成一沓便签，每张便签编号后送去翻译，翻译完再按照编号贴回原来的位置。如果只是把书直接丢给翻译，回来的很可能是一堆散落的文字，顺序和格式全都对不上。
在 Dify 里，这四个环节对应的工作流节点是：
| 环节 | 对应节点 | 作用 |
|---|---|---|
| 拆 | 文档解析节点 / 代码节点 | 提取 PDF 文本，按段落切分 |
| 译 | LLM 节点 | 调用大模型翻译切片 |
| 合 | 代码节点 | 用模板回填方式生成目标语言 PDF |
| 查 | 代码节点 / 人工抽检 | 校验乱码、表格结构、文本完整性 |
整体思路确定后，后面所有细节都是围绕这套“拆译合查”流水线来展开。
2.2 选型细节：解析、翻译模型、还原方案怎么权衡
方案里最核心的三个技术选型点分别是：PDF 解析用什么工具、翻译模型选哪个、格式还原采用什么方式。这三个选择相互约束，不能单独拍脑袋。
先看 PDF 解析。市面上常见的方案有 pdfplumber、PyMuPDF、PaddleOCR、Surya 等。我的选择依据很简单：先判断源文档是文本型还是扫描型。文本型 PDF 用 pdfplumber 或 PyMuPDF 提取文字，速度快、准确率高；扫描型 PDF 必须先走 OCR 流程，否则提取出来是空文本。如果文档里有复杂的表格和双栏排版，还需要版面分析能力，这时候 PaddleOCR 的 PP-Structure 或 Surya 这类模型会更合适。
翻译模型的选择也很关键。我在这套流程里优先考虑的是“稳定性大于惊艳”。翻译质量不追求文采飞扬，但要求术语一致、格式标记不丢、长句不截断。实测下来，通用大模型如 GPT-4o mini、Claude 系列、甚至国产的 DeepSeek 都能满足要求，关键是 temperature 要调低，控制在 0.2 以下，避免译文发散。这个我后面会详细说。
格式还原方案是最容易踩坑的地方。我曾经试过用大模型直接输出排版代码，让 PDF 渲染引擎去执行，效果非常不稳定，因为模型对坐标、行距、分页的掌控能力很弱。最终我采用的是“样式模板 + 文本回填”方案：预先用 Python 的 reportlab 或 fpdf2 写好一个版面模板，把翻译后的文本按顺序填充进去，生成 PDF。这个方案牺牲了一部分视觉还原度，但胜在稳定高效，尤其适合技术手册、白皮书这类以段落和表格为主的文档。
3. 核心细节拆解：解析、翻译、还原三块硬骨头
3.1 解析层：文本 PDF 与扫描 PDF 两条腿走路
PDF 解析是整条流水线的地基，这一步做不好，后面翻译和还原全白搭。我在这块踩过不少坑，先说文本型 PDF。
文本型 PDF 提取文字本身不难，难的是“段落重组”。PDF 文件存储的是一行行带坐标的文本对象，没有“段落”这个概念。你用 PDF 阅读器打开看到的段落，其实是渲染引擎根据坐标和间距拼出来的。所以我用 pdfplumber 提取时，不能直接拿 extract_text() 的结果去翻译，要先做坐标聚类和空行判断，把属于同一段落的行合并在一起。
我用的分段逻辑大致是这样：遍历每一页的文本行，记录每行的 y 坐标和缩进，当上下两行之间的垂直距离超过正常行距的 1.5 倍时，就认为是新段落的开始。这样处理后，段落边界会比默认的按换行符切分准确很多。
扫描型 PDF 则复杂很多。这类文档本质上是图片，必须先 OCR。我强烈建议扫描件不要直接用 pytesseract 硬扛，因为中英文混排、双栏布局会让 OCR 结果完全乱序。我试过直接用 tesseract 跑一个双栏的中英文混排技术手册，输出文本的阅读顺序是跨栏交叉的，翻译后根本没眼看。后来换了 PaddleOCR 的 PP-Structure 做版面分析和 OCR，先把页面拆成标题区、正文区、表格区，再按阅读顺序重组文本，问题就解决了。
3.2 翻译层：分段策略和 Prompt 设计决定质量的 80%
有人以为翻译质量只取决于模型强不强，实际上在文档翻译场景里，分段策略和 Prompt 设计往往比模型本身更重要。我用同一款模型做过对比测试：直接把整个 PDF 文本一次性丢给模型翻译，和按段落切片翻译，后者的术语一致率、格式保留率明显更高。
分段策略要兼顾“语义完整”和“长度可控”。语义完整要求尽量按段落边界切分，避免一句话被砍成两半；长度可控要求每个切片不超过模型的上下文窗口。我使用的经验值是：每个切片控制在 500 到 800 token 之间，大约对应 1000 到 1600 个汉字。切片太短会丢失上下文，太长则容易触发截断。
切片代码我用 Python 写在 Dify 的代码节点里，核心逻辑是正则分段加长度聚合：
import re def split_document(text, max_chars=1000): # 先按连续换行切分成段落块 blocks = re.split(r'\n\s*\n', text) chunks = [] current = "" for block in blocks: block = block.strip() if not block: continue # 合并小段落，直到达到最大字符数 if len(current) + len(block) < max_chars: current += "\n" + block else: if current: chunks.append(current) current = block if current: chunks.append(current) return chunks这里有个细节：如果某个段落本身特别长，超过了 max_chars，我会再加一层句子级切分，按句号、分号等边界断开，确保切片不会超长。目标语言是德文、法文时，句子普遍比中文长，max_chars 我会适当调小到 800，避免翻译后文本膨胀。
Prompt 设计是另一个重头戏。我的翻译节点 Prompt 长这样：
你是一个专业的文档翻译引擎。请把用户输入的文本从中文翻译成英文。 要求： 1. 保持原文的段落结构和列表层级。 2. 保留 Markdown 标记、HTML 标签、占位符、URL 和数字格式。 3. 术语严格按照术语表翻译：{term_list} 4. 只输出翻译结果，不要添加任何解释性文字。术语表是关键。比如“工作流”这个词在产品文档里统一翻成 workflow，不能一会 workflow 一会 work flow。如果项目里有术语表，直接塞进 Prompt 的 {term_list} 变量里，效果比依赖模型自觉好得多。术语多了之后，更好的做法是把术语表导入 Dify 知识库，用知识检索节点动态召回相关术语，这个我后面扩展部分会讲。
3.3 还原层：模板回填为什么比让模型直接排版靠谱
格式还原我前文已经提到了大方向——模板回填。在实际代码里，我用 reportlab 生成了带标题层级和段落样式的 PDF，关键点是字体注册，中文字体必须显式注册，否则生成出来的 PDF 会乱码。
我这里给出一段简化可用的 PDF 生成代码，放在 Dify 代码节点里执行：
from reportlab.lib.pagesizes import A4 from reportlab.pdfgen import canvas from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont def create_pdf(paragraphs, output_path, font_path="simhei.ttf"): # 注册中文字体，解决乱码问题 pdfmetrics.registerFont(TTFont("SimHei", font_path)) c = canvas.Canvas(output_path, pagesize=A4) width, height = A4 y = height - 50 c.setFont("SimHei", 11) for para in paragraphs: # 简易换行处理，超过页宽自动截断 lines = para.split("\n") for line in lines: if y < 50: c.showPage() y = height - 50 c.setFont("SimHei", 11) c.drawString(50, y, line) y -= 18 y -= 8 c.save()这段代码是简版，真实使用时我会增加对表格、图片、页眉页脚的处理。但核心思想是清晰的：先用代码定义版式，再把翻译后的文本填进去。为什么不让大模型直接输出完整 PDF？因为 PDF 是矢量布局格式，模型对坐标的控制能力非常弱，差几个像素整个版面就乱了。而模板回填是确定性的，只要文本内容不出错，版式就一定稳定。
需要特别提醒的是，Dify 社区版的代码节点运行在沙箱环境里，内置的 Python 包有限，reportlab 不一定默认安装。我在配置时是先把字体文件和 reportlab 依赖打包进容器，再在代码节点里调用。如果你用的是 Dify 云端版或受限环境，建议把 PDF 生成这一步做成独立 API 服务，通过自定义工具节点接入。
4. 工作流落地实录：在 Dify 里从零搭一条翻译流水线
4.1 环境准备：Dify 本地部署与模型接入
我采用的是 Docker Compose 方式部署 Dify，具体步骤如下。如果你已经部署好了，可以直接跳到模型配置部分。
git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d拉取镜像时如果遇到超时或拉取失败，优先检查网络状态，并给 Docker 配置可用的公共镜像加速器，这是我在国内服务器上部署时遇到的第一道坎。部署完成后，通过浏览器访问 http://localhost/install 初始化管理员账号。
登录后第一件事是配置模型供应商。我用的方案是 OpenAI Compatible 接口，因为不少主流模型服务商都兼容这个协议，配置比较灵活。具体操作路径是：设置 → 模型供应商 → 添加模型，填写 API Key、Base URL、模型名称，然后测试连通性。
几个配置细节：
- temperature 设置成 0.1 到 0.2，文档翻译不允许模型自由发挥。
- max_tokens 不要设太小。我翻译英文技术文档时设过 1024，结果长段落经常被截断，后来改成 2048，情况好很多。
- 如果你的模型服务有 QPS 限制，可以在 Dify 的模型配置里调整并发数，或者在代码节点里自行控制请求频率。
4.2 工作流节点串联与参数配置
接下来进入正题。打开 Dify 工作流编排页面，新建一个空白工作流，然后按下图思路从开始节点一步步连下去。这里不涉及 Dify 版本特有的函数，我按通用节点类型描述。
开始节点的输入参数我定义了两个：一个是 file，类型为文件，用于接收上传的 PDF；另一个是 target_lang，字符串类型，默认值为 en，用于指定目标语言。如果未来要对接 API 批量调用，这两个参数可以直接由外部系统传入。
PDF 解析节点我用的是代码节点。Dify 的代码节点支持传入文件变量，我通过 Python 读取上传的 PDF 并提取文本，然后调用 3.2 节里的 split_document 函数完成切片，最终输出一个 chunks 数组。这里要注意：代码节点的入参和出参都要按 Dify 的变量规范定义，输出变量类型要选 array，否则后续 LLM 节点没法直接引用。
翻译节点是工作流的核心，类型选择 LLM 节点。模型选择我在 2.2 节提到的那几款，技术上你可以根据实际可用模型选择。关键配置如下：
- 模型：我常用 gpt-4o-mini 作为默认，成本低、速度快，质量也够用；复杂文档（专业术语多、句式复杂）时切换到 Claude Sonnet 或 DeepSeek。
- temperature：0.2。
- max_tokens：2048。
- Prompt 模板：使用 3.2 节那段模板，其中 {term_list} 变量来自我维护的术语表。
这里有一个很实用的技巧：LLM 节点可以设置多轮对话模式吗？其实不需要。在文档翻译场景里，我用的是“一轮翻译一个切片”的最简策略，上下文依赖通过前文摘要来补充。具体做法是：在翻译当前切片之前，先用一个极简的 LLM 调用生成前文的 100 字摘要，作为 context 变量传入翻译 Prompt，让模型在翻译时知道前文提到过哪些术语和主语。这个技巧在翻译长文档时非常有用，能显著减少指代错误。
格式还原节点是最后一个关键节点，类型依然是代码节点。输入是翻译后的文本数组 chunks，我在代码节点里调用 reportlab 生成 PDF，并把生成的文件路径作为输出返回。结束节点把生成的 PDF 文件设置成输出变量，这样用户在应用前端可以直接下载。
整条工作流串起来后，我建议先用一个 2 到 3 页的小 PDF 做测试，确认每个节点的输入输出都对得上，再处理正式的批量文档。
4.3 一次完整执行：10 页中英技术手册的实测数据
为了验证整套流程的可行性，我拿了一份 10 页的中文技术手册做测试。这份手册包含标题层级、正文段落、两个表格和三张流程图，属于比较典型的文本型 PDF。
执行流程如下：
- 上传 PDF 到工作流，选择目标语言为英文。
- 代码节点完成文本提取和切片，共切出 16 个切片，每个切片约 600 到 900 字。
- 翻译节点逐个翻译切片，总耗时约 90 秒，token 消耗约 12000。
- 还原节点生成英文版 PDF，耗时约 3 秒。
最终输出的 PDF 在结构还原上表现不错：标题层级完整，正文段落顺序正确，表格内容没有错位，图片位置基本保持不变。和原版对比，唯一明显的差异是字体从宋体变成了黑体，这是因为 reportlab 默认字体风格不同，但不影响阅读。对于技术文档来说，这个还原度已经可以接受。
5. 常见问题与避坑手册
5.1 问题速查表
实际操作中，不同环节会暴露各种问题。我把高频问题整理成速查表，方便你遇到问题直接对照定位：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| PDF 提取出来是空文本 | 扫描版 PDF，没有文字层 | 先做 OCR，建议用 PaddleOCR PP-Structure |
| 翻译后中文变成方块字 | 还原时未注册中文字体 | 在 reportlab 中显式注册中文字体文件 |
| 长段落翻译被截断 | max_tokens 设置太小，或切片超长 | 调大 max_tokens，调小切片长度 |
| 译文术语前后不一致 | Prompt 没有置入术语表 | 在 Prompt 中注入术语表，或接 Dify 知识库 |
| 表格翻译后列宽错乱 | 模板未固定表格列宽，文本过长溢出 | 预设列宽比例，超长文本动态缩小字号 |
| 双栏扫描件翻译顺序混乱 | OCR 未做版面分析 | 用 PP-Structure 或 Surya 先做版面还原 |
| 代码节点运行报缺少库 | Dify 沙箱未预装依赖 | 把依赖和字体文件打包进容器，或改用外部 API |
5.2 亲手踩出来的三条经验
第一条经验：先盘文档类型，再定解析方案。我最初接到需求时，默认所有 PDF 都是文本型的，结果一份扫描版合同翻出来全是乱码。后来我每次处理新文档前，都先用 pdfplumber 快速检测是否包含文本层，没有就走 OCR 流程。这一步判断 30 秒就能完成，却能避免后面几个小时白干。
第二条经验：术语表一定要前置。文档翻译的术语一致性问题，越早处理成本越低。如果你等到翻译完再统一改术语，需要在还原后的 PDF 里逐段搜索替换，非常痛苦。我现在的做法是：对于每批新文档，先抽取高频专业术语做成术语表，放进 Prompt 里，甚至可以放到 Dify 知识库里做动态召回。
第三条经验：批量文档场景别手动上传。当你需要一次翻译几十份 PDF 时，手动在 Dify 应用界面里一个个上传是不现实的。我是通过 Dify 的 API 接口写了一个 Python 批量脚本，循环调用工作流，把每份文档的翻译结果自动保存到指定目录。脚本核心就是构造请求、上传文件、轮询执行结果，这套方式稳定跑完过几百份文档。
6. 额外值得延伸的三个方向
这套流水线跑通之后，我发现它还有很多可以扩展的空间，这里分享几个我自己在规划的方向。
第一个扩展方向是结合 Dify 的知识库做动态术语管理。现在术语表是写在 Prompt 里的，术语多了 Prompt 会变得冗长，影响模型理解和响应速度。更优的方案是把术语表导入 Dify 知识库，在翻译节点之前增加一个知识检索节点，根据当前切片自动召回相关术语，再拼接到 Prompt 里。这样术语表可以做到上千条，且不影响主 Prompt 的简洁性。
第二个扩展方向是把翻译能力嵌入 RAG 问答流程。现在很多企业用 Dify 搭建知识库问答机器人，但知识库里的文档往往是单一语言的。如果能把多语言 PDF 翻译流水线生成的译文文档同步入库，就能让问答机器人覆盖更多语言场景。我目前的思路是用工作流生成译文 PDF 后，再走一遍 Dify 的文档 ingestion 流程，把译文写入知识库。
第三个扩展方向是复杂表格和版式的高级还原。目前我的模板回填方案对普通段落和简单表格效果不错，但遇到跨页表格、合并单元格、图文混排的复杂版面时，仍然需要人工介入。后续我计划引入更细粒度的版面分析结果，把表格结构、图片占位信息都提取出来，作为模板参数传入生成节点，进一步提升还原度。
最后分享一个我个人的体会：做这套方案时，最花时间的并不是翻译模型调优，而是 PDF 解析和格式还原。翻译模型的迭代速度很快，但文档结构解析是纯粹的工程问题，需要耐心打磨。如果只让我留一条建议，那就是动手之前先把你的文档类型盘一遍，文本型、扫描型、混合型，不同文档走完全不同的处理路线。别指望一套方案通吃所有 PDF，选好切入点，这套流水线就能真正解决你的业务问题。
