大模型翻译技术文档：术语表、代码保护与批量流水线实战

说实话刚拿到这套英文的 SigmaPlot 和 MATLAB 帮助文档时我第一反应是找在线翻译跑一遍就完事。真做起来才发现软件帮助文档跟普通文章完全是两回事里面全是函数名、参数说明、路径变量、示例代码甚至还有一段只能在特定软件环境里运行的脚本。普通机器翻译上去函数名被翻译成中文代码直接废掉参数解释错一半反而比不翻译更坑人。我当时手里这份文档是某个跨软件流程的 help 文档牵扯到 SigmaPlot 的绘图操作又牵扯到 MATLAB 的数据处理和批量调用。团队里有人想快速上手英文水平又参差不齐于是“把帮助文档汉化一份”这个事就被丢给了我。我当时选定的方案是用 DeepSeek 做翻译主力因为它既能理解整段技术语境又能按指定术语表输出远比传统机翻可控。整个项目跑下来完整产出了一份中英对照、可检索的离线文档。这篇就把我踩过的坑、验证过的方法和可以直接抄走的流程写清楚。1. 这项目到底在干什么1.1 一个软件用户被英文文档折磨的真实场景先交代下需求来源。科学软件圈子有个很普遍的情况工具很强大但官方文档只有英文。SigmaPlot 和 MATLAB 都是这种典型软件前者负责统计绘图和曲线拟合后者负责数值计算和脚本批处理。很多流程看起来很简单比如在 MATLAB 里算完数据再导出到 SigmaPlot 里生成发表级图表但具体怎么调用接口、怎么设置坐标系属性、怎么批量出图全得从 help 文档里翻。问题来了help 文档动辄几百页按函数引用、属性说明、示例代码分类组织。一个核心函数页面可能包含输入参数、输出参数、注意事项、底层调用关系、示例图片。你用在线翻译整页翻译排版全乱代码块被翻译成乱码你人工逐条翻时间成本又太高。尤其当这个文档还要给团队其他人复用的时候一份统一术语、格式整洁、方便搜索的中文手册就变得非常有价值。我当时的目标很明确不是简单把英文变成中文而是产出一份保留代码可运行性、统一专业术语、保留原始格式结构的离线参考手册。这个目标决定了后面所有技术选型。1.2 为什么选大模型而不是传统机翻很多人会问现在在线翻译不是挺强了吗为什么还要单独搞一套流程我试过传统机翻对日常语句确实不错但对技术文档有两个致命问题一是术语不稳定。同一篇文档里“Axis”一会儿翻译成“轴”一会儿翻译成“坐标轴”一会儿又变成“轴线”。软件文档里这类同义词一旦不一致读者会误以为在讲不同概念。二是代码和文本混排识别差。文档里大量出现set(gca, XLim, [0 100])这样的代码片段机翻经常把变量名或函数名也翻译了或者把代码里的引号、括号改成全角字符导致代码根本没法复制运行。大模型翻译则完全不同。你可以事先给一份术语表让它严格按术语表翻译你可以明确告诉它哪些内容必须保留原样你还可以把整个章节的上下文一起喂进去让它理解前文后文而不是逐句孤立翻译。这些特性对齐了技术文档翻译的核心需求。1.3 这个项目最终交付了什么做完之后我手里多了以下几样东西一份按原始章节结构整理的中英对照 Markdown 文档英文原文和中文译文一一对应一份独立的中文术语表收录了 SigmaPlot 和 MATLAB 文档里出现的高频词汇及统一译法一份可以本地离线打开的 HTML 版帮助手册支持目录跳转和全文搜索一整套可复用的批量翻译脚本以后拿到新版英文文档改一下路径就能直接跑。这套流程不挑具体软件名称只要你的文档是英文技术文档都可以套用。下面我把每一步的细节拆开讲。2. 开工前必须搞清楚的文档结构与拆解策略2.1 help 文档的常见形态和整理方式技术文档的原始格式直接决定翻译前要做什么预处理。我遇到的帮助文档主要有四种形态处理方式各有不同。第一种是 CHM 格式编译好的 HTML 帮助文件。这种最省事目录是现成的每个主题对应一个 HTML 页面。用解压工具把 CHM 解开之后就能得到一堆 HTML 文件和目录索引直接用脚本批量提取正文即可。第二种是 PDF 格式。最麻烦因为 PDF 里可能有页眉页脚、多栏布局、代码缩进丢失等问题直接转出来的文本经常是乱的。我建议优先用能够识别布局的工具把 PDF 转成 HTML 或 Markdown再进入翻译流程不要在 PDF 文本上直接翻译。第三种是纯 HTML / Markdown 格式多见于开源项目或在线文档站。这种最好处理只需要去除导航栏、版权页等无关区块然后按标题层级切分。第四种是 Doxygen 生成的函数参考文档。这类文档结构高度模板化每个函数有固定的“说明、参数、返回值、示例、参见”字段反倒适合做批量翻译因为可以把每个字段作为独立小单元喂给模型。无论哪种格式第一步都是先把所有文件归拢成一个干净的、纯文本的、带章节标记的中间格式。我统一转成 Markdown因为 Markdown 保留了标题层级、代码块、表格结构模型最容易理解后续也最好二次排版。2.2 按什么粒度切分文档最合理第一次做这个项目的时候我犯过一个错误把整个章节十几页内容一次性丢给模型翻译。看上去效率高实际效果很差。原因有三点。第一模型有单次输入的上下文长度限制超出上限时最常见的表现不是报错而是静默丢掉中段内容。第二超长输入会让模型在长距离依赖上表现不稳定前面章节的术语约定到后面可能就忘了。第三单次输出过长时格式一致性会明显下降表格和代码缩进经常出错。所以我在大量试错后把切分粒度定为“单个主题页面”或“单个完整小节”大约 500 到 1500 字。原则是每个分块必须有完整语义不要在句子中间硬切每个分块尽量只讲一个主题分块之间保留顺序关系带上章节编号方便后续合并如果一个分块本身就是由多个独立片段组成比如一个函数下的多个参数说明可以进一步拆成更小的参数块。这个粒度对模型最友好翻译质量最稳定而且就算某一小块出错了重跑成本也很低不用整个大章节重新来一遍。2.3 术语表先行比提示词更重要技术文档翻译里术语一致性比文笔重要得多。文笔差一点读者能忍同一个概念三个译法读者会崩溃。所以我在正式翻译前先用全文扫描把高频术语挑出来做了个初始术语表。建术语表有几个来源文档目录、索引页、函数名说明、图片标题。这些位置往往浓缩了文档的核心术语。把英文术语对应中文译法整理成表格例如英文术语统一中文译法备注Axis坐标轴不译作“轴”Legend图例Plot Area绘图区Workspace工作区Command Window命令行窗口Script脚本Handle句柄不译作“手柄”术语表建好之后每次调用翻译模型时都把术语表附在提示词里。这一步看起来笨但极大地保证了前后一致性。而且术语表还可以反过来用于翻译后的检查后面我会细讲。3. 基于 DeepSeek 的翻译流水线实操3.1 让模型进入角色一套可复用的提示词模板大模型翻译质量的关键不是模型本身有多聪明而是你有没有把规则说清楚。我最终固定下来的提示词模板长这样你是一名有十年经验的软件技术文档翻译专家熟悉科学绘图和数值计算软件。 请把下面提供的英文技术文档翻译成简体中文。 翻译要求 1. 保留所有英文变量名、函数名、类名、命令名、路径名、菜单项不得翻译。 2. 保留代码块、公式、表格结构、缩进和符号只翻译代码中的注释。 3. 术语必须严格按术语表翻译。术语表未覆盖的术语要结合上下文选择最符合软件行业习惯的译法。 4. 输出格式与原文结构一致使用 Markdown 格式。 5. 译文要准确、简洁不要添加原文没有的解释或注释。 6. 如果原文中有“见第 X 页”“see also”这类引用保留原文表达并翻译为“参见”或“另请参阅”。 术语表 Axis - 坐标轴 Legend - 图例 Script - 脚本 Handle - 句柄 ... 待翻译内容 [此处粘贴分块后的英文原文]这套模板的核心是“约束前置”。翻译要求写在开头术语表紧跟其后最后才是正文。模型对开头的指令权重感知最强越靠前的规则越容易被遵守。3.2 批量调用模型脚本怎么写才能稳手动一段段复制粘贴肯定不行几百个分块会累死人。我用 Python 写了一个批量翻译脚本核心思路是按顺序读取 Markdown 文件切分成块逐块调用模型接口把译文写入输出文件。伪代码如下import requests import time API_URL https://api.your_model_provider.com/v1/chat/completions API_KEY your_api_key def translate_block(block, term_table, context_tail): system_prompt f你是软件技术文档翻译专家。请按术语表和翻译要求将英文翻译成中文。\n术语表\n{term_table}\n翻译要求...同上 user_content if context_tail: user_content f上一段的译文结尾如下注意保持术语一致\n{context_tail}\n\n user_content f待翻译内容\n{block} payload { model: your_model, messages: [ {role: system, content: system_prompt}, {role: user, content: user_content} ], temperature: 0.3, max_tokens: 4096, top_p: 0.9 } resp requests.post(API_URL, jsonpayload, headers{Authorization: fBearer {API_KEY}}) resp.raise_for_status() return resp.json()[choices][0][message][content]实际操作中我在循环里加了三样东西失败重试遇到网络超时或返回异常时间隔几秒重试最多重试三次请求间隔每个请求之间 sleep 0.5 到 1 秒避免触发频率限制断点续跑每翻译完一个分块就把结果追加写入磁盘并记录当前进度。中途断网或者接口报错时重跑不需要从头再来。3.3 上下文衔接相邻分块之间怎么保持一致分块翻译最大的风险就是上下文割裂。前一个分块里把某个命令说明翻完了后一个分块开头又是一个新函数如果模型不知道前后逻辑关系很容易把相关术语翻译成不同说法。我的解决办法很简单翻译下一个分块之前把上一个分块的译文末尾“尾巴”拼接进本次请求的输入。这个尾巴不需要很长保留最后 200 到 400 字就够。它的作用是向模型传递上一段的语气、用词风格和术语取向让模型潜意识里朝着一致的风格继续。另外对于有“参数说明”和“示例代码”的文档最佳做法是参数说明部分和示例代码部分分开处理。先翻译参数说明再翻译示例代码里的注释。因为示例代码里的文字非常短如果和参数说明混在一起模型容易把代码逻辑和说明混着翻译导致代码块被改坏。3.4 代码块和公式的保护机制这是整个项目里最值得说的一部分。软件文档翻译代码就是命根子。如果你翻译完之后代码没法直接运行那这份帮助文档基本等于废纸。我采用的方法是“占位符替换法”。在把文本送入模型之前先通过正则把文档里的所有代码块和行内代码提取出来替换成类似CODE_BLOCK_1的占位符。模型看到的文本里没有代码只有一段被占位的普通说明文字。模型翻译完返回后脚本再把原来提取的代码原封不动地塞回占位符位置。import re def protect_code_blocks(text): placeholders {} def repl(match): idx len(placeholders) 1 placeholders[fCODE_BLOCK_{idx}] match.group(0) return fCODE_BLOCK_{idx} text re.sub(r.*?, repl, text, flagsre.S) text re.sub(r[^]*, repl, text) return text, placeholders def restore_code_blocks(text, placeholders): for k, v in placeholders.items(): text text.replace(k, v) return text这个方案的原理很简单代码本身不需要翻译让模型看到反而容易误伤不如干脆藏起来。文本里只留下一个标记模型翻译时不会动它翻译完了直接替换回来代码保证一字不变。公式的处理同理。如果文档里包含 LaTeX 公式同样先把$...$或$$...$$提取成占位符。SigmaPlot 和 MATLAB 文档里公式不多但遇到一定不能漏公式符号一旦被改成全角或者中文标点后面渲染出来全是错误。4. 翻译现场最容易踩的坑4.1 高频问题速查表直接对着排查项目跑完后我把实际操作中遇到的问题归纳成了一张表。新来的同学遇到问题可以先对照这里查。问题现象根本原因解决办法函数名被翻译成中文提示词对“保留函数名”的约束不够强强化提示词第1条并把函数名加入术语表统一不翻译代码块里的引号变成中文全角引号模型把代码当普通文本处理使用占位符替换代码块翻译后原样恢复同一术语前后译法不一致上下文信息不足每次请求携带上一段译文尾巴并强制挂载术语表表格结构丢失单元格错乱输入分块过大模型思维链过长缩小分块粒度表格单独作为独立分块翻译长文输出被截断单次输出超过模型上限减小 max_tokens 之外还要把分块切得更小译文出现编造内容温度设置过高模型发挥过度把 temperature 调到 0.3 以下翻译结果和原文顺序错位输入中包含了过多导航菜单等无关内容预处理阶段清除无关区块只留正文英文专有名词如软件名被奇怪翻译术语表里没收录把 SigmaPlot、MATLAB、Workspace 等全部加入术语表4.2 我亲手修过的几个典型案例第一个典型问题是函数名被翻译。第一次跑完批量翻译时我打开输出文件发现xlabel被翻译成了“x标签”ylabel变成“y标签”gca被翻译成“当前坐标轴句柄”。这个在人类看来好像没什么问题但问题在于读者把文档里的代码复制到 MATLAB 里直接就会报未定义变量因为 MATLAB 里根本没有叫“x标签”的函数。后来我把所有函数名全部加进术语表并且在提示词里明确“任何紧跟括号的英文单词都可能是函数名必须保留原样”才算解决。第二个典型问题是表格错乱。MATLAB 帮助文档里经常有参数对照表一列参数名一列描述。模型默认输出 Markdown 表格时如果某个单元格里包含|符号表格就会断列。后来我在提示词里加了“如果原文表格单元格内包含竖线请保留该竖线并转义为\\|”。这个问题直接让我意识到技术文档翻译的很多“坑”不是语言问题而是格式问题。第三个典型问题是分块间的术语漂移。前面章节翻译“坐标轴”译得很好翻到样例代码章节时模型又把“axis”翻译成“轴线”。原因就是样例代码章节里的上下文太短我在请求里没带上一段译文。把上一分块的译文尾巴拼接进去之后这个问题基本消失。说明这个“尾巴”不是可有可无而是质量稳定的关键参数。5. 译文质量校验与离线知识库落地5.1 自动化检查脚本不靠肉眼硬看整批文档翻译完光靠抽查不够我得对所有页面做一次程序化检查。检查包括三个层面第一层是代码完整性检查。脚本扫描译文里所有的反引号代码块、行内代码和原文比对确保代码块在翻译后被原样还原没有增删字符。这一步我在恢复占位符时就已经保证了但多个模型版本混用了不同的翻译流程时还是需要代码级校验。第二层是术语一致性检查。拿术语表里的英文术语去原文中扫描找到所有出现位置再检查译文中对应位置的翻译是否和术语表一致。不一致的地方标出来人工确认。第三层是结构完整性检查。对比原文和译文的标题层级确保每个二级标题、三级标题都在译文中出现没有漏翻。def check_terms(original, translated, terminology): issues [] for term, expected in terminology.items(): occurrences original.count(term) # 简化逻辑统计译文中是否出现预期译法 actual translated.count(expected) if occurrences 0 and actual occurrences * 0.8: issues.append(f{term}: 期望出现 {occurrences} 次译文实际匹配 {actual} 次) return issues这个检查不能做到 100% 精确但能快速筛出明显问题把人工审校的范围缩小到真正有争议的句子。5.2 打包成可检索 HTML 帮助文档翻译完成后的 Markdown 文件我统一用脚本构建成带左侧目录的 HTML 页面。每个 Markdown 文件对应一个 HTML 页面目录结构按原始章节层级生成。这样团队使用时可以像翻原版 help 文档一样左侧点目录右侧看内容浏览器里直接搜索关键词。如果你想要更接近软件内置帮助的体验还可以再进一步编译成 CHM 格式。用开源工具把 HTML 目录和一整套页面打包成 CHM 文件就行。我当时直接提供了 HTML 版因为跨平台打开方便Mac 和 Windows 都能用不需要额外装 CHM 阅读器。5.3 后续文档版本更新不需要重头翻软件厂商发布新版本帮助文档时最忌讳的是拿到新文档从头重新翻译一遍。旧版已经翻译过的内容占了百分之八九十新版通常只改了一小部分。我的做法是先做差分。用文本比较工具对比旧版和新版英文文档把变化的部分单独摘出来只翻译增量内容。没有改动的段落直接沿用旧译文。这个思路能让二次维护的成本降到最初的十分之一以下。做差分的时候要注意一个坑新版文档可能只是调整了目录结构文字没变但整个文档的行号全都变了。这时候不要按行号对比要按段落标题和函数名做匹配对比否则你看到的“变更”全是假阳性。最后再分享一点个人体会这套流程跑完之后我最深的感受是大模型翻译本身并不值钱真正值钱的是你给模型设定的框架。一份软件帮助文档能不能翻得好决定因素按优先级排是这样的前期的术语表中期的代码保护机制后期的自动化校验。提示词模板虽然重要但它在三者里反而是最容易被模仿的。你哪怕把提示词原封不动给另一个人他拿到的文档格式不同、术语表没建、代码没有保护照样翻出垃圾结果。另外还有一点很现实像我这次的目标是 SigmaPlot 和 MATLAB 交叉场景的帮助文档翻译的时候不仅要求语言能力还要求对两个软件的基本概念有认知。模型如果不懂什么是“坐标轴句柄”不懂“工作区”在 MATLAB 里意味着什么翻译出来就会生硬甚至错误。所以我会在术语表之外给模型塞一段简短的软件背景说明比如“本软件中轴对象包含刻度、标签、范围等属性工作区保存当前会话中的所有变量”。这段背景比一百句“请你专业一点”都管用。以后再遇到新的帮助文档翻译任务我大概率会直接复用这套流程拆文档、建术语表、保护代码、分块翻译、自动校验、打包发布。前期准备花的时间多一点但后面批量翻译和长期维护省出来的时间远超前期投入。如果你手上也有英文软件文档需要汉化建议你就从“先拆文档结构和建术语表”这两件事做起别的先不用管做完这两个后面的事就是流水线。