ERPNext汉化实操指南：从翻译机制到全界面中文部署

简介ERPNext企业管理系统界面汉化资源面向需要中文环境的实施人员与开发者解决标准功能界面未汉化、操作门槛高的问题尤其适合刚接触系统、不熟悉英文界面的团队。压缩包共33个文件大小315KB以py源码、txt说明、js脚本等为主其中translations/zh.csv是界面翻译核心覆盖绝大部分标准功能菜单与表单py文件用于加载汉化及代码级扩展txt和元数据便于安装时核对依赖与版本。目前已有1579人学习下载适合正在部署或二次开发ERPNext的团队参考。资源目录结构清晰包含setup.py、hooks.py、overrides.py等模块通过hooks.py可了解翻译资源如何注册overrides.py则示范标准行为扩展适合有开发能力的团队自主适配描述亦提示代码级汉化位于另一开箱即用版本读者可据此评估后续获取路径。翻译文件可直接导入使用整体内容对快速落地中文界面有直接帮助。1. 汉化前先搞懂的事ERPNext的语言机制ERPNext是目前开源ERP里综合实力相当能打的一套系统基于Frappe框架功能覆盖财务、采购、销售、库存、HR、制造等全套业务流程。但很多团队在实际落地时第一个卡点往往不是业务流程设计而是界面语言——默认英文界面对国内业务人员的使用门槛很高直接影响了项目推进效率。严格来说ERPNext的“汉化”并不是一个简单的开关切换而是一套完整的多语言机制。系统内置了Frappe框架的翻译系统支持语言包动态加载、运行时切换、按用户偏好锁定语言。这意味着汉化工作可以分两条线并行推进一条是翻译系统自身的语言条目另一条是业务数据层面如客商名称、物料名称、单据类型的中文显示。两者配合得当才能做到真正的深度本地化而不是只换个登录页面的壳。在动手之前需要先确认一下你的ERPNext版本。不同版本的翻译机制略有差异我以目前较稳定的Version 14和Version 15为例展开说明这两个版本的配置文件路径和翻译缓存逻辑基本一致只是部分字段名在新版本中有细微调整。汉化所涉及的资源主要分为三类语言包/apps/frappe/frappe/translations/、自定义翻译通过系统内置的“翻译”功能维护、以及系统设置中的语言偏好配置。理解了这三层结构后续操作就有了清晰的目标。2. 翻译文件的底层逻辑与汉化准备工作2.1 Frappe翻译系统的词条组织方式Frappe框架的翻译词条本质上是Python gettext机制的一种变体实现。语言包文件放在各app模块的translations目录下文件名是语言代码如zh.csv、zh_TW.csv、hi.csv等每一行对应一条翻译记录。这种设计的好处是翻译词条可以按app模块独立维护——你翻译了erpnext这个模块的界面文字完全不影响frappe框架底层的系统文字所有模块的语言包叠加起来最终呈现一套完整的界面翻译。ERPNext的语言包文件通常位于/apps/erpnext/erpnext/translations/zh.csv /apps/frappe/frappe/translations/zh.csv这两个文件分别对应ERPNext业务模块和Frappe底层框架。系统启动时会将所有已安装app的翻译文件合并再按语言代码写入缓存。缓存的存放位置可能是Redis也可能是本地磁盘的缓存目录具体取决于部署方式。用Docker方式部署的话重启容器后会自动重新扫描翻译文件并更新缓存。2.2 汉化前的环境确认和备份动翻译之前必须先把环境检查一遍。我习惯先跑一次系统自带的语言检测确认当前版本默认支持的语言范围# 进入bench环境 bench --site your-site-name console # 在console中查询支持的语言列表 frappe.get_hooks(languages)如果输出中包含zh或者zh-cn说明系统本身已带中文本地化支持。如果没有也不用慌手动添加语言支持的步骤在后面详细说明。紧接着要做的是备份。翻译文件改动虽然不会直接破坏数据库但万一改坏了语言包导致界面大面积英中混杂恢复也是件头疼事。保险的做法是在改动前把两个翻译文件都复制一份留底cp /apps/frappe/frappe/translations/zh.csv /apps/frappe/frappe/translations/zh.csv.bak cp /apps/erpnext/erpnext/translations/zh.csv /apps/erpnext/erpnext/translations/zh.csv.bak另外需要特别注意的是ERPNext界面汉化过程中最容易被忽略的是“系统默认语言”这个全局变量。它存储在系统设置System Settings里而不是在语言包文件中。系统设置中的语言字段决定了所有新创建用户的默认界面语言这与你当前登录用户的语言偏好是两个不同维度的配置非常容易混淆。后面我会详细拆解这两种配置的优先级关系。3. 两种汉化路径系统翻译与自定义翻译3.1 官方内置翻译的启用ERPNext本身自带的中文翻译已经覆盖了大部分标准界面的词条。对大多数场景来说第一步要做的是正确启用它而不是急着手动翻译。具体操作路径登录系统后进入“设置 → 系统设置”在“语言”下拉框中选择“简体中文”保存。然后从右上角用户头像下拉菜单中进入“语言”设置把用户界面语言切换成中文。此处有一个关键细节系统设置的语言是兜底方案用户自身的语言偏好设置优先于系统设置。也就是说如果某个用户的账户语言是英文即使系统设置了中文该用户看到的界面依然是英文。想要让全团队默认中文除了改系统设置还需要批量修改已有用户的语言偏好。可以在bench控制台里执行bench --site your-site-name consoleimport frappe users frappe.get_all(User, filters{enabled: 1}) for user in users: doc frappe.get_doc(User, user.name) doc.language zh doc.save(ignore_permissionsTrue) frappe.db.commit()这段代码会把所有启用状态用户的语言偏好统一修改为中文。注意管理员账号Administrator也要改否则后续你用管理员登录时看到的还是英文界面。启用系统翻译后绝大部分标准菜单、按钮、字段标签都会显示为中文。但有两个地方是系统翻译覆盖不到的一是自定义字段二是业务数据里的固定选项。比如你在采购单上自定义了一个“审批备注”字段但字段的标签是英文这时候就需要用到自定义翻译功能。3.2 用翻译工作台做自定义翻译Frappe内置了专门的翻译管理界面路径是“设置 → 翻译”。这个界面的设计比较朴素但功能很实用支持按语言过滤、搜索关键词、批量修改。操作逻辑是这样的你把界面切换成中文找到那个还是英文的标签把英文原文复制到翻译工作台在翻译框中填入正确的中文保存即可。系统会自动将这个翻译词条写入翻译缓存下次页面刷新就能看到效果。翻译工作台的核心字段有三个“源文本”Source Text即界面上的英文原文、“翻译文本”Translated Text即你要显示的译文、“语言”。这里有个容易踩的坑源文本必须和界面上显示的内容完全一致包括大小写和空格。比如界面上显示的是“Expected Delivery Date”你在源文本里填“expected delivery date”系统就匹配不上。最简单的方式是直接从页面复制原文不要手打。自定义翻译和应用内翻译的区别在于隔离级别。自定义翻译存储在数据库中对应的DocType是“Translation”它会覆盖语言包文件内的原始翻译也可以在语言包文件缺失某条词条时起到补漏作用。如果你的团队后续会升级ERPNext版本这种基于数据库的自定义翻译不会在升级时被覆盖持久性比直接改语言包文件高得多。4. 实战从登录页到审批流的全界面汉化4.1 系统语言切换与用户界面汉化实际部署时通常是从登录页开始检查的。登录页右上角有一个语言选择下拉框如果这地方没有出现中文选项说明系统没有正确识别中文语言包。这时候需要检查frappe框架的language注册逻辑确认你安装的语言包是否匹配。常见的一种情况是语言包文件存在但语言代码是“zh”而不是“zh-cn”导致语言选择下拉框中显示的不是“简体中文”而是“中文Chinese”。登录进去之后的用户界面建议以采购审批这个最常见的流程为例走一遍。采购申请单从创建、提交、审批到生成采购订单全流程涉及多个DocType的状态字段、按钮标签、工作流状态。切换中文后重点检查这些字段状态字段如“待审批”“已批准”“已拒绝”动作按钮如“提交”“取消”“更新”关联字段如“供应商”“物料”“仓库”如果某个状态字段在页面显示时仍是英文大概率是源文本以特殊字符开头或结尾比如带冒号、括号导致翻译匹配失败。这时候回到翻译工作台用模糊搜索的方式查一下源文本的真实格式。4.2 业务主档中文化物料、客户、单据类型这是很多人漏掉的一个环节。系统界面翻译成中文了但你在物料主档里建的物料名称、客户名称、单据类型名称如果当初录入时用的就是英文那界面上不可能自动变成中文——这不是翻译系统的职责范围而是业务数据本身的维护问题。对于已经有存量英文数据的系统建议按优先级分步处理。第一优先级是单据类型比如费用报销单、领料单这些在流程中高频出现的类型。如果单据类型名是英文员工在使用时会持续产生困惑。第二优先级是客户和供应商名称。如果业务上要求客户档案必须以中文为主建议在客户主档的“客户名称”字段直接更新同时保留英文名称到“客户代码”或自定义字段中保证历史单据的数据引用不中断。第三优先级是物料名称和物料组。物料名称往往涉及SKU编码体系修改前需要和财务、仓库确认口径避免影响成本核算和库存维度报表。这里有一个经验之谈不要在标准字段上做二次翻译比如把物料名称写成“Steel Plate_钢板”这种格式。表面看是双语显示实则污染了后续的数据分析和报表展示。物料名称字段就是业务名称本身界面的语言显示问题应该交给翻译层去解决数据层要保持干净。4.3 处理自定义字段和多语言单据打印如果你在系统里建了一堆自定义字段那翻译工作就要延伸到自定义字段这里。自定义字段的语言切换不通过翻译工作台处理而是直接编辑字段属性。在表单设计器中找到对应自定义字段将字段标签直接修改为中文即可。需要注意的是自定义字段的“字段名”Fieldname一旦建立就不建议修改它对应数据库表的列名改动了会引发数据映射错误。你只需要修改“标签”Label显示值字段名保持不动系统界面就会显示中文标签。打印模板的汉化也是一项容易被忽略的工作。ERPNext的打印格式支持通过Jinja模板自定义默认标准打印格式的标题部分语言取决于当前文档的语言设置。如果客户收到的一张打印出来的采购订单还是英文问题通常出在文档记录本身的语言设置上——每个Transaction单据如销售订单、采购订单都有一个语言字段这个字段默认继承客户的“默认语言”属性。需要到客户主档里检查“语言”字段是否设置成了中文或者干脆在打印格式模板中把关键标题写死为中文。{% set lang doc.language or zh %} div classprint-heading h2{{ _(采购订单) }}/h2 p{{ doc.name }}/p /div用_()函数包装文本会让这个字符串也被翻译系统识別在多语言环境下依然能自动切换。如果完全没有多语言需求也可以直接硬编码中文写起来更省事。5. 汉化升级与日常维护5.1 版本升级时的汉化文件迁移ERPNext的迭代节奏不算慢每几个月就有一次小版本更新。升级成功后语言包文件可能被新版本的文件覆盖导致你之前直接修改语言包文件的汉化内容丢失。我的建议是把自定义翻译尽量都放在翻译工作台数据库层里维护而不是直接改语言包文件。数据库层的翻译能跨版本存活而语言包文件属于程序文件升级时非常容易被覆盖。如果你就是习惯直接改语言包文件那就一定要建立一套文件追踪机制。在每次升级前用diff命令比对当前翻译文件和官方文件差异把差异化内容先行导出存档。升级完成后再把这些差异重新合并回去diff -u zh.csv.org zh.csv zh_customizations.patch # 升级后执行 patch zh.csv zh_customizations.patch这套流程虽然原始但能有效防止升级导致的汉化回退问题。5.2 多语言团队的翻译管理如果你所在的团队不仅用中文还需要同时支持英文、日文等其他语言就需要考虑翻译词条的动态加载逻辑。Frappe的翻译系统支持词条按语言代码分离不同语言的翻译互不干扰。多语言团队的管理重点是建立翻译评审机制。我见过不少系统多人同时翻译导致同一术语在不同位置有不同译法比如“供应商”和“供货商”混用体验非常不专业。建议在团队中固定一位翻译管理员负责翻译工作台上所有词的终审。同时在翻译词条时约定术语表保障核心名词在全局范围内翻译一致。5.3 翻译缓存刷新的正确姿势汉化过程中“界面没变化”是大家抱怨最多的问题。改了翻译词条但页面没有任何反应原因多半是翻译缓存没有刷新。Frappe的翻译缓存刷新有两种方式第一种在翻译工作台修改词条并保存后系统会自动清理相关缓存键通常一两分钟内就能看到效果。第二种如果你直接修改了服务器上的语言包文件或者批量导入翻译词条则需要手动清理缓存bench --site your-site-name clear-cache如果界面还是没变再强行重启一次后台服务。Docker部署的执行方式不同需要重启容器内对应的bench进程。这里还有一个非常容易踩的坑浏览器缓存。ERPNext的桌面端界面虽然大部分数据交互通过Ajax但导航菜单和部分静态资源是缓存在浏览器本地的。改了翻译后如果服务端已经刷新缓存但界面依然没变强制刷新一下浏览器CtrlF5往往就解决了。6. 遇到这些问题别慌逐个排查6.1 中文乱码与字符集问题这可能是最常遇到的了。改了语言后界面上出现方框问号甚至整段文字变成乱码。产生原因基本集中在服务器本身的字符集设置。虽然现代ERPNext版本默认使用UTF-8编码但老数据库或者手动导入的数据可能带着历史遗留的latin1或gbk编码。排查方法很简单直接在服务器的MariaDB终端里查看数据库字符集SHOW VARIABLES LIKE character_set_database;如果结果不是utf8mb4就需要修改数据库字符集。修改之前务必备份数据库具体操作是把整个库导出、改库配置、再导入bench --site your-site-name backup提示字符集问题要优先处理因为乱码一旦渗透到业务数据里后续清理成本非常高。如果库里已经有乱码数据更稳妥的方式是先修复数据再统一字符集。6.2 翻译了部分词条但界面仍是英文这种情况很考验耐心。按照我的经验按照以下顺序排查90%以上能解决一是优先级覆盖问题。自定义翻译数据库层的优先级最高会覆盖语言包文件中的词条。如果你之前不小心把某个词条翻译成了和英文原文一样的文本或者在翻译工作台里保存了空白翻译那无论语言包文件怎么正确界面依然显示英文。去翻译工作台按原文搜索把该词条的翻译改成正确中文即可。二是源文本大小写/空格不匹配。前面反复提到过这个原因排查起来比较隐蔽。把一个带HTML标签或特殊字符的源文本复制到工作台搜索框中搜索看能不能精确匹配到记录。推荐复制界面上显示的内容而不要自己输入。三是应用模块未启用对应语言。检查这个模块如erpnext是否已经在系统的“语言”列表启用了中文。路径在“设置 → 语言”中直接搜索中文确认状态是否为启用。6.3 汉化后的日期和金额格式调整做完汉化还有个容易被忽略的细节是日期格式和金额格式。中文环境下日期一般习惯显示为“2025-01-15”或“2025年1月15日”而默认英文格式是“2025-01-15”在部分欧洲格式下会变成“15-01-2025”。金额格式同理中文通常不需要千分位分隔符或者保留两位小数。日期格式在“系统设置 → 日期格式”中修改金额格式调整有两种方案全局性的在系统设置中修改“货币格式”相关选项细致到单据粒度的可以在自定义字段或打印格式模板中强制格式化{{ frappe.utils.formatdate(doc.transaction_date, yyyy年MM月dd日) }}这种格式化只在显示层生效不会改变数据库里的存储值安全可靠。7. 汉化不彻底这套方案根治如果以上标准流程走完后你仍觉得汉化不够彻底大概率是以下三个深层问题在作祟第一某些第三方应用如从Frappe Cloud安装的扩展应用没有自带中文翻译文件第二系统通过API或WeChat小程序等非标准终端访问界面绕过了Web端的语言加载逻辑第三存在大量硬编码在代码里的英文提示信息。针对第三方应用的汉化思路是一样的。先查看该应用的translations目录下是否有zh.csv没有就从另一个入口补上——在该应用安装目录下手动创建一个zh.csv文件内容按“原文,译文”的CSV格式填写保存后在bench控制台执行bench build和bench clear-cache让系统重新扫描合并语言包。硬编码英文的处理更硬核。找到对应源码文件中用_()或gettext包裹的英文字符串手动改为调用翻译函数。这需要懂点Python和Frappe的开发基础如果团队没有这个能力也可以考虑在产品层规避——用审批工作流、自定义字段这些低代码能力去替换原生页面的提示语虽然不是全量汉化但在核心业务路径上能达到几近汉化的体验。最后定期巡检汉化质量也很关键。我个人的习惯是每季度导出一份翻译工作台中尚未翻译的英文词条清单按出现频次排序优先处理高频未翻译项# bench console中执行 frappe.get_all(Translation, filters{language: zh, translated_text: }, fields[source_text])这套从启用内置翻译、补漏自定义翻译、管理业务中英、到处理升级和字符集问题的流程完整走完后一个基本全中文的ERPNext系统就跑起来了。实际使用中中文环境的业务人员上手速度比英文界面快得多培训成本下降明显。这个项目做下来我最大的感受是汉化不是一次性的技术动作而是需要持续维护的运营工作。只要团队一直在用这套系统汉化质量的维护就得跟着走。本文还有配套的精品资源点击获取