1. 为什么我会在2025年动手做这个工具
先交代一下背景。过去几年我一直混在制造业供应链交付的一线，日常打交道的对象是各类工厂体系文件——控制计划、PFMEA、作业指导书、设备点检表、来料检验规范，密密麻麻的表格，每一行都是评审过的工艺参数和管控要求。
这里有个很现实的问题：很多外销型工厂的总部团队在国内，制造基地在东南亚，或者反过来，海外客户审厂要求提供英文版文件，而工厂日常执行的版本是中文的。两边文件一多，就出现了一个长期没人好好解决的场景——中英文双向的体系文件翻译。
我试过很多办法。最开始是人工翻译，一份三十页的控制计划发出去，翻译公司两周后返回，格式全乱，表格合并单元格崩掉，工艺参数序号对不上，术语前后不统一，今天叫“焊接温度”，明天叫“焊锡温度”，审核老师看一遍就挑出一堆问题。后来用在线翻译工具，内容涉及内部工艺参数，直接扔到云上，合规这关就过不去，而且表格版式照样是重灾区。
我的感觉是：市场上不缺翻译工具，缺的是面向工厂体系文件场景、能把版式、术语、追溯这三件事同时管起来的东西。这背后是一个很具体的分工：翻译引擎负责语言转换，但版式保留需要文档结构层的处理，术语约束需要业务侧的词典沉淀，可追溯需要的是过程数据的记录和审计。把这三件事在一款桌面工具里串起来，就是我开发 Factory-translator 的出发点。
这款工具面向的受众很明确：供应链质量工程师、体系工程师、海外工厂的文件管理专员，以及需要经常处理中英文双语文件的中小制造企业。它解决的问题是让“工厂体系文件的双语转换”这件事从纯人工的翻译等待中解脱出来，同时保证输出文件能直接用、术语能对齐、版本能追溯。
实操中它到底能做什么，先用一段话概括：打开一个中文的 SOP 文档，设置好术语词典和翻译引擎参数，点击执行，输出一份英文版本，表格结构、合并单元格、字体字号、页边距这些版式要素保持不变，正文内容被翻译成目标语言，同时全流程生成处理日志，记录每一处被翻译的内容、所采用的术语、处理耗时和异常信息。全程离线可用，文件不出本地。
这篇文我不会只讲它怎么用，更想把当时为什么做这套方案、版式和术语这两个最麻烦的点是怎么拆解的、日志追溯到底记录到了什么粒度的信息，这些决策过程一并摊开讲。如果你也正在处理工厂文件国际化这件事，或者打算自建一套文档翻译流水线，应该能少走不少弯路。
2. 工厂体系文件翻译，真正的死结在哪里
体系文件翻译和普通文档翻译完全是两码事。普通文档翻译，版式稍乱一点无伤大雅，术语不统一也就是读者别扭。但体系文件不行，它是给产线执行和客户审核用的，任何一个环节的错位都可能引发连锁问题。
2.1 版式不是“美观问题”，是“有效性”问题
很多没做过工业文档处理的人，对版式的理解停留在“好看”这个层面。实际上在工厂体系文件里，版式直接关乎信息的可读性和可追溯性。
一份控制计划的表格里，每一列都有严格的业务含义：过程编号、工位名称、设备参数、控制方法、反应计划。这些列宽、行高、合并单元格，是经过评审后固定下来的，里面任何一个信息的位移，都可能导致一线员工读错参数，或者审核员找不到对应的控制项。
关键点在于，翻译引擎只处理语言，它不理解“表格的某一个格子”及其与相邻单元格的合并关系。常规做法是：检查是否有合并行或合并列，有则标记拆分行，同时解析表格的物理坐标和逻辑坐标的映射关系，解绑行 span 和列 span，准确填充文本单元格并执行脏矩形重绘。这套逻辑听起来不复杂，实际处理起来，批注、修订、格式覆盖、字体适配，全是细节。
这也是我一开始就确定的一个原则：翻译工具必须保留源文件的完整布局结构。表格不能被拍平，段落不能重排，每一页的内容量不能出现大的位移，否则输出文件拿去打印、签字、扫描上传系统，全是问题。
2.2 术语不统一，审核时的“定时炸弹”
体系文件里大量出现专业名词和内部缩写，比如 CTQ、CPK、SPC、FMEA、8D、APQP，不同的人翻译出来可能是不同的写法。更麻烦的是同一个中文词在不同产线里代表不同含义，比如“首件”，在机加工和电子组装里的英文表达不同，如果全局用同一个词替换，就会出现业务层面的误导。
人工翻译之所以能保证质量，是因为翻译人员会基于上下文理解。但纯机器翻译最大的缺陷也在这里，它不知道你的公司内部已经约定俗成“这个客户的文件里，首件必须写 first article，不能写 first piece”。
因此术语约束必须做成一个可配置的机制：用户提供一份术语对照表，系统在翻译前预先锁定这些词组的表达方式，翻译引擎在工作时命中术语词典的片断必须使用指定译文，不需要重新生成。后面我会详细展开这一块的实现思路。
2.3 离线能力与审计需求长期被低估
工厂在文件处理上的 IT 环境，和互联网公司完全是两个物种。很多工厂的信息化部门对外部工具接入有严格要求，在线翻译服务的 API 调用需要把文档内容上传到第三方服务器，这在合规上存在风险，尤其涉及客户私有工艺参数的文件，数据主权是红线。
此外，体系文件的更新往往伴随着客户审核、第三方认证。审核员会有这样的提问：“这个英文版文件是哪一版中文文件翻译过来的？由谁执行的？用了什么术语策略？”如果没有任何过程记录，这类问题只能靠邮件往来补充说明，非常被动。
所以我在设计时把“离线可运行”和“操作日志全记录”作为两个必须满足的非功能性需求，而不是可有可无的加分项。前者保证了数据安全边界，后者让每一份翻译产物都有据可查。
3. 技术选型：为什么是 Python 与 PySide6
选型这件事，我前前后后推翻过好几轮，也劝过自己要不要直接用 Electron 交个差。最终敲定 Python 加 PySide6 的方案，核心是权衡了几个维度的结果。
3.1 桌面端 vs Web 端的取舍
第一版原型我其实是按 Web 服务设计的，后端翻译任务用队列管理，前端页面上传下载文件，听起来很现代。但很快我就否掉了这个方向：工厂用户不是互联网用户，他们不习惯“部署一个服务”这件事。桌面工具独立出包，双击可运行，是这部分用户群体的刚需。
同时，离线运行的诉求，天然就排除了纯 Web 的方案。桌面应用数据全程本地流转，没有上传下载动作，也就不存在文件内容被第三方接触的风险。用 Electron 可能界面更好看，但包体积、内存占用、跨平台处理的成本，在工具型应用里都不占优势。
PySide6（Qt for Python）在这个场景下是更务实的选择。它安装体积相对可控，界面响应性能足够，而且 Python 生态里有后面要提到的文档解析库可以直接引用，集成成本低。
3.2 文档解析层：python-docx 与 openpyxl 的组合
文档解析是整个系统里最底层的依赖，这一层选不好，上面所有的翻译逻辑都等于盖在沙滩上。
- 处理 Word 格式（.docx）时，我用了 python-docx。它能解析 document.xml 的结构，识别段落、表格、样式定义，并且支持读取表格的合并信息。
- 处理 Excel 格式（.xlsx）时，我用了 openpyxl。它能精确读取单元格的坐标、数据格式、合并单元格范围，实现单元格级别的文本提取和回填。
这里多提一句：为什么不用一些更重量级的跨平台文档 SDK？因为对于“保留版式”这个诉求，Word 和 Excel 本身是事实标准，直接从 OOXML 这个层面去读写，能拿到最稳定的控制力。docx 本质上是一个 zip 包，里面是 xml 文件，解析和构建在理论上不存在障碍。而 PDF 这类格式，天然不适合“保留版式地翻译”，排版引擎的差异会引发一连串问题，所以我把支持范围限定在 Office 文档。
3.3 翻译引擎接口的抽象设计
翻译引擎这块，我刻意做成可插拔的。预置了“自定义 HTTP 接口”和“本地模型”两种接入模式，用户可以通过配置指向自己的翻译服务，也可以在本地部署翻译模型。
对外接口是一个统一协议，无论对接的是哪类模型，都遵循相同的请求和响应结构。这样有个好处：用户今天用一个通用翻译 API，明天想换成针对工业领域微调的模型，只需要改配置，不用改主程序逻辑。
在设计这个协议的时候，我还特意加了一个“术语优先”的机制：在请求发给翻译引擎之前，系统先在本地把命中的术语词条用占位符替换掉，等翻译完成后，再把占位符还原为指定的译文。这样能保证任何引擎在语义层面都“被迫”遵循术语约束，而不是寄希望于模型自己理解。
4. 版式保留的底层逻辑：结构和内容分离再合并
我做这个工具最核心的一个设计原则，就是“结构不动，只动文本”。整个翻译过程在逻辑上分成三步：提取、翻译、回填。
4.1 第一步：把文档结构完整抽取出来
以 docx 为例，系统读取文档后，先不急着翻译任何内容。首要任务是把整个文档的结构树还原出来：每个段落属于哪个样式、是否在表格内、表格有几行几列、哪些单元格是合并的、每段的字体字号和缩进是多少。
这一步实际上是构建一个“文档骨架”。所有结构信息，包括表格的列宽、单元格的合并范围、段落的边框底纹，都会被记录下来。之后翻译环节就是在骨架的各个节点上替换文本内容，骨架本身原封不动。
这样做的好处是，输出文档的结构和信息结构完全对应，等于给文档做了一次“换皮不换骨”的手术。
4.2 第二步：表格单元格的映射关系
表格是体系文件里结构最复杂、也最容易在翻译中出错的部分。我专门为表格处理写了一套独立的逻辑：
- 先读取表格的坐标系，识别每个单元格的合并范围。
- 对合并单元格做特殊处理。横向合并（colspan）通常代表一个分类标题，纵向合并（rowspan）则可能是多个行的共享信息。对这类单元格，需要保持合并范围不变，只替换内部的文本。
- 对普通单元格，逐格提取文本，积累成翻译批次，按批送入翻译引擎。
同时还要关注单元格内的段落格式。一个单元格里可能有多段文本，每段的缩进、行距、项目符号这些都要在回填时一并保持。否则即使表格轮廓还在，阅读体验也会很差。
4.3 第三步：字体和长度的适配
中英文在文本呈现上有天然差异。中文字符宽度一致，排版相对规整；英文单词长度不一，同一段文字翻译成英文后很可能变长或变短。
如果单元格宽度是固定的，文本变长就会出现“溢出”或者被截断的视觉问题。所以在回填时我做了一个判断：如果目标文本长度超出单元格宽度的可容纳范围，自动缩小字号，或者转换对齐方式，尽量减少溢出。这一步不追求完美，但能保证大部分场景下输出文档的可用性。
这类适配逻辑说实话很难做到尽善尽美，不同的内容组合会衍生出各种特殊情况，但整体交付质量已经能覆盖工厂正式文件的使用标准。
5. 术语约束机制：让机器翻译“记住”你的业务规则
术语约束这个模块，是整个工具里用户感知最强、也最能体现“懂行”的部分。它在处理流程上的设计非常有讲究，下面我把完整的处理链路拆开讲。
5.1 从词典配置到匹配逻辑
系统支持一个术语词典的导入和配置。词典的本质是一个“原文→译文”的映射表结构，在词典中，每个词条支持精确匹配和模糊匹配两种模式。
- 精确匹配：适用于专有名词、缩写等，如“控制计划”→“Control Plan”，这种词在文档任何地方出现都必须使用固定译文。
- 模糊匹配：适用于可能存在不同上下文形态的词组，如“首件检验”，系统会识别词根的变形方式，在命中后优先采用词典译文。
术语配置是在翻译动作之前被加载的。加载完成后，系统会对源文本先执行一遍“术语预扫描”——扫描的过程中，命中的术语会被替换为带有特殊标记的占位符，比如[[TERM_0001]]。这样翻译引擎拿到的文本里，术语已经不是自然语言了，自然也就不会被翻译成其他表达。
5.2 占位符策略如何避免术语被“二次翻译”
这是最核心的细节：如果不把术语替换成占位符，直接告诉引擎“遇到控制计划请翻译成 Control Plan”，很多模型并不稳定，往往前面几段能遵循，后面就又按自己的理解翻了。而占位符策略是从机制层面强行锁死，不存在“不遵循”的可能。
翻译完成后，系统再把占位符还原为词典中指定的译文。同时，为了避免占位符被打散，术语预扫描时我会设置一个保护区间：术语所在片断整体被占用时，其他规则不介入。这样每个词条在处理过程中都是完整的，不会出现被截断或拆分的情况。
5.3 术语未命中时的兜底策略
不管词典做得多全，总会遇到词典里没有的词。系统对此也有明确的兜底流程：未命中术语的词条，会由翻译引擎按照通用规则翻译，但这条内容会被记录到“待确认术语清单”里，并在日志中标记为“未约束”，提醒用户后续补充词典。
这个设计非常重要，它让系统不只是一个翻译工具，还是一个持续积累的组织级词汇库。工厂的文件体系是滚动的，每次项目中遇到的新术语，都可以沉淀进词典，越用越准。
6. 可追溯日志：每个翻译动作都有据可查
之前做工厂项目的时候，我被客户问过“这个英文版文件是怎么来的，能不能追溯？”当时我拿不出来，只能邮件来回找，花了两天做了一份说明。自那之后，我就把日志追溯当成系统的一等公民来设计。
6.1 日志记录的数据模型
日志系统记录的信息分成三层：
- 任务层：记录一次翻译任务的基本信息，如处理时间、源文件路径、目标文件路径、使用的翻译引擎配置、术语词典版本。
- 结构层：记录文档中每个被处理的结构单元，如第几个表格、第几行第几列、是段落还是单元格，方便定位任意一段译文在原文件中的位置。
- 内容层：记录每一段文本的源文、译文、术语命中情况、耗时、状态（成功/失败/人工复核）。
这套日志写出来之后是 JSON 格式，可以直接对接后续的审计需求，也能导入到其他系统做汇总分析。用户在界面上就能查看，每一条记录都是可展开的，定位到具体的文档位置。
6.2 审计场景下能回答哪些问题
拿这套日志，可以回答以下几类典型问题：
- 这份英文文件的母本是哪份中文文件？什么时候翻译的？用的是哪个版本的术语表？
- 文件里有哪些术语是通过词典约束的，哪些是走了通用翻译的兜底路径？
- 某个术语在上一版和这一版之间的翻译策略是否发生变化？
- 翻译过程中是否有失败或异常的内容？失败的内容被如何处理？
操作界面里一眼能看到：源文件、目标文件、处理时间、引擎配置、词典版本，每一项都是可用的追溯信息。这些信息在客户审核和内部文件管理上，价值远远超过“能翻”本身。
6.3 日志与异常重试的配合
日志不只是事后记录，它还参与任务执行的过程控制。当某一段文本翻译失败（比如网络超时、引擎返回异常），系统会根据日志记录的失败原因自动触发重试，重试次数和间隔都是可配置的。
如果重试仍失败，系统会保留源文，并在输出文档中以特定标记标出失败位置，同时在日志中醒目标注“需人工处理”。这样可以避免“一个人拿到文件，发现有段话是空的，但不知道是漏了还是怎么了”这类尴尬情况。
7. 实际部署和运行效果：拿一份真实的控制计划试一遍
理论设计说得再多，最终还是得看实际跑起来的效果。我拿一份脱敏后的真实控制计划文件做了完整的测试，这里把过程和参数一并给出，方便有需要的人参考。
7.1 环境准备与安装
运行环境建议：
- Python 3.10 或更高版本（项目依赖 f-strings 和较新的类型标注语法，版本太老会有兼容问题）
- 操作系统：Windows 10/11 或 Ubuntu 20.04 以上均验证过
- 建议通过 virtualenv 或 conda 创建独立环境，避免依赖冲突
安装命令（Windows 示例）：
# 克隆项目 git clone https://github.com/your-repo/factory-translator.git cd factory-translator # 创建虚拟环境并激活 python -m venv .venv .venv\Scripts\activate # 安装依赖 pip install -r requirements.txt # 启动 python main.py依赖项里比较核心的是 PySide6、python-docx、openpyxl、requests，另外会让用户自行配置翻译服务的地址。启动后进入主界面，左上是文件选择区，右侧是配置区，下方是任务执行与日志区。
7.2 配置一份术语词典
我准备了一个示例词典，覆盖了控制计划里最常出现的一批词，格式是简单的 “中文,英文,匹配模式” 三列。
控制计划,Control Plan,exact 特性,Characteristic,exact 特殊特性,Special Characteristic,exact 过程编号,Process Number,exact 反应计划,Reaction Plan,exact 首件检验,First Article Inspection,exact 焊接温度,Welding Temperature,fuzzy 扭矩,Torque,exact 供应商,Supplier,exact 工程变更,Engineering Change Request,exact词典导入后在界面上会显示词条数量，并实时计算覆盖率（即当前文档中能命中的词条数占总词条的比例）。覆盖率可以作为衡量词典质量的直观指标。
7.3 执行翻译并查看版式结果
在配置区选择“自定义 HTTP 接口”模式，填写本机部署的翻译服务地址，语言方向选择“中文→英文”，勾选“保留版式”和“生成日志”，点击执行。
输出文档用微软 Office 或 WPS 打开，可以看到：
- 表格数量、行列结构完全一致，合并单元格位置没有发生位移
- 字体和字号默认跟随源文件样式，仅在文本溢出时自动修正
- 段落顺序不变，项目符号保留
- 术语全部按照词典译文输出，未出现同义词混用
我用一段中文作业指导书做了对比，原文中的“操作工应佩戴防静电手环”，在词典命中“防静电手环”→ESD wrist strap 的情况下，译文稳定输出 “Operators shall wear ESD wrist strap”，不会把“防静电”和“手环”拆开翻译。
7.4 日志文件的内容示例
执行完成后，日志文件输出到指定目录，我用 JSON 片段展示一下实际记录的字段结构：
{ "task_id": "20250317-001", "source_file": "control_plan_v3.2.docx", "target_file": "control_plan_v3.2_EN.docx", "executed_at": "2025-03-17T14:32:08", "engine": "custom-http", "dictionary_version": "2025Q1", "items": [ { "location": "table_2_row_3_col_4", "source": "焊接温度", "target": "Welding Temperature", "term_status": "exact_match", "engine_status": "success", "duration_ms": 245 } ] }这个结构在后续做追溯时非常实用，可以按任务、按文档、按术语命中状态过滤，也可以导成 CSV 交还给质量部门存档。
8. 踩坑记录与工具设计中的权衡取舍
开发过程中最有价值的往往不是那些顺利的部分，而是一个个实际踩下去的坑。这里挑几个对使用影响最大的写出来。
8.1 合并单元格的“拍平”与还原陷阱
最初处理表格时，我为了方便提取文本，把合并单元格直接拍平成普通单元格。结果回填时发现，源文档里明明是合并单元格，输出的表格里却变成了多个独立单元格，结构信息整个乱掉了。
后来的修复方式是：在解析阶段单独记录每个单元格的合并范围信息，翻译完成后，在构建输出文档时通过合并范围的坐标重新创建合并单元格。整个过程分了两条线：结构线和文本线，互不干扰，最后再合并回完整文档。现在无论横纵合并都能保持，批注的位置也不会错。
8.2 占位符被翻译引擎截断的问题
术语占位符策略曾经被翻译引擎坑过一次。引擎在语义分析时，把含占位符的长句“智能优化”了，把占位符和正文词拆分重组，导致回填时找不到对应的占位符 ID。
我的规避办法是，在预扫描时把术语词条连同词条左右两边的标点一起作为整体替换，并且告诉引擎“这是一个术语标记，请原样保留”。不同的引擎对指令的遵循度有差异，但至少从机制上降低了被打散的概率。实际操作时，建议术语词典里将两个词以上的短语优先配置为完整表达，尽量避免单个字或词的约束，这样占位符策略的稳定性会高很多。
8.3 “完全一致”不是目标，“可用”才是
在做版式保真的时候，我一度追求“输出文件与源文件在视觉上完全一致”，后来发现这是一个性价比极低的目标，甚至是一个伪目标。中英文文本的字符密度不同，只要语义准确、结构不散、信息完整，形式上已经达到了审核使用的标准。
翻译后的文本长度增加，某些单元格的字号做了调整，这是合理且必要的偏差。所谓版式保留，保的是文档的结构骨架和信息布局，而不是每一个像素。把这个预期管理好，用户的使用体验反而更好。
8.4 词典质量和翻译引擎输出不能彼此替代
词典不能替代翻译引擎。它解决的是“术语表达必须一致”的问题，但无法解决“这句话怎么组织更符合行业习惯”的问题。这两件事实质上依赖同一套内容，但处理逻辑上只能分工。实测下来，配合工业领域语料微调后的引擎，再加上术语约束，才能达到“拿出去就能用”的交付质量。通用模型不配术语约束时，即使能翻，术语一致性依然会翻车，这几乎是铁律。
9. 项目当前状态与后续演进方向
项目已经以开源形式发布，核心代码覆盖了上面讲到的全流程。当前版本是 v0.9，供足够多的人在真实业务场景里试用，同时我把它定位在“生产可用但还不够完善”的阶段。
9.1 已知边界与适用限制
- 当前版本主要支持 .docx 和 .xlsx 格式的文档，暂不处理 .pdf。
- 文本量特别大的文档处理速度会明显变慢，建议每次翻译控制在几百段以内。
- 术语词典的匹配规则目前是线性的：逐条正则匹配。词典过大（上万条）时，匹配效率会下降，但一般工厂的体系文件词典规模在几千条以内，实际使用中还行。
- 表格中的图片、嵌入对象不会被翻译，保持原样输出。
9.2 后续最想补的几个能力
一是术语词典的自动学习。理想的形态是：用户对某段译文做了人工修正后，系统能自动对比源文和修正结果，提炼出新的术语建议。这样词典的积累成本大幅降低，从“人工录入”升级为“半自动沉淀”。
二是样式模板的扩展支持。不同客户的审厂模板对格式要求不同，比如特定字体、特定字号、特定页眉页脚。目前在代码里预留了样式配置的入口，后续计划做成可视化配置，让用户自己定义输出样式规则。
10. 最后分享几点心得
做这个项目对我个人的价值，不只是产出工具，更是把我在供应链交付中对文件管理零散的用户习惯和痛点梳理成了系统性问题解决方案。
如果你也打算处理类似的问题，听我一句劝：先把“术语约束”这件事想明白，再动手做翻译功能。术语约束不只是词典文件那么简单，它的设计决定整个工具在业务上的可信度。一个翻译引擎可能因为一两个术语译错，被业务部门一票否决。
另外，离线不是可选项，是这个场景的底线。哪怕你的使用环境允许联网，也要把离线能力作为默认水准来设计，因为工厂文件这条线，永远有不能上云的内容。
最后一个建议：日志从第一版就做，不要后补。一开始就把“可追溯”当成核心功能设计，后面在审计场景里你会感谢自己当时多写的那些字段。如果一开始不做，等用户真的来要追溯信息的时候，你就只能对着零散的文件干瞪眼，那种感觉我已经帮你们体验过了，不太好受。
如果有这方面的问题，欢迎一起交流。
