不建翻译表,一列JSON实现后台国际化,后端零改动
很多人做后台国际化,第一反应就是建翻译表、写Mapper、加关联查询,后端忙活好几天,前端还要拼数据。但这篇文章我要讲一个相当取巧的思路:不建翻译表,一列 JSON,后端零改动。这个方案不是凭空想出来的,是我在几个前后端分离的项目里实测沉淀下来的,适合管理后台这种以枚举、字典、状态值翻译为主的中后台场景。你如果正被“后台文案多语言、但又不想大动干戈”折磨,这篇文章应该能帮你省下不少时间。
先交代一下这套思路的适用边界。管理后台和官网前台不一样,后台的核心诉求是让运营、客服、管理员能看懂数据,而不是给 C 端用户展示。所以后台的国际化,绝大多数场景是“枚举值翻译”,比如订单状态 0、1、2 要显示成“待支付、已支付、已取消”,角色类型要显示成“超级管理员、运营、财务”。这些数据的特点是总量有限、变化不频繁、散落在各个业务表里。如果为这种体量去建几十张翻译表,反而是过度设计。我的做法是:在每张业务表里加一个 locale 字段,类型是 JSON,直接存多语言文案的映射,后端完全不动,前端拿到 JSON 自己解析。
这套做法我会从设计思路、核心细节、实操过程、踩坑实录四个部分展开讲,尽量把每一步的“为什么”也交代清楚,方便你直接拿去用。
1. 内容整体设计与思路拆解
1.1 为什么敢说“后端零改动”
通常我们聊国际化,后端是最先被拉下水的。要建语言表、翻译表,要改查询逻辑,要加关联,甚至要考虑回退策略。但你想过没有,管理后台的数据查询,其实绝大多数场景是“查列表、点详情、做操作”,后端返回的是结构化数据,前端负责渲染。那既然渲染归前端管,文案转换这一步,为什么不能也归前端管?
我当时的判断依据有三条。第一,后台的国际化文案不是面向搜索引擎的,不存在 SEO 诉求,所以不需要服务端渲染出多语言 HTML。第二,后台的数据量级撑死几万条,JSON 字段的解析开销可以忽略不计。第三,也是最重要的,后台业务的“语言”切换,本质上是“把数据库里的 code 翻译成当前语言的 label”,这个翻译关系是静态的、低频的,完全可以在前端常量层解决。
所以我把方案定为:后端继续返回业务数据,只要额外多返回一个 locale 字段(JSON 格式),里面带着翻译所需的映射关系。前端拿到后,用预先埋好的 i18n 工具函数去解析,动态替换显示文本。 后端代码一行不改,数据库只加一列,接口返回天然自带翻译信息。
1.2 对比传统翻译表方案的核心优势
传统方案长这样:一张 translation 表,字段有 table_name、row_id、field_name、locale、translated_text。每次查询要么 JOIN 翻译表,要么先查业务数据再循环查翻译。字段一多,查询次数成倍上升,后期还会遇到“某个语言没翻译、要不要回退英文”这种破事。
JSON 列方案的对比优势很明显:
- 结构零侵入:不需要新建表、不需要改现有表结构,只需要
ALTER TABLE加一列。对于已经上线的系统,这是成本最低的变更方式。 - 查询不用 JOIN:
locale字段直接挂在业务行上,拿一行数据就带一行翻译,没有 N+1 查询问题。 - 后端零改动:后端 ORM 只需要在查询结果里多序列化一个字段,如果你的后端用的是“查出来直接转 JSON 返回”的模式,甚至连实体类都不用改,像 MyBatis-Plus 这种框架,Map 结构查询天然支持新增字段自动带出。
- 文案维护直观:翻译文案跟着业务记录走,运营后台直接编辑这一列 JSON 就行,不需要跨表去维护对应关系。
1.3 这套方案的边界和限制
必须说明白,这个方案不是银弹。它最适合的是字典类、枚举类、短文本翻译。如果你的系统需要翻译的是一整篇长文章、富文本内容、规格参数说明,这个方案就会变得很别扭,因为 JSON 字段会变得巨大,管理后台编辑也不方便。
另外,如果你的权限体系很严格,比如不同管理员只能看到部分语言的翻译,那么翻译表反而更适合做数据权限控制。还有,如果前端有强 SEO 需求,C 端页面必须由服务端直接输出多语言 HTML,那这个方案也不适用——但管理后台基本不会有这种需求。
提示:用这个方案前,先确认你的场景是“翻译固定枚举”还是“翻译任意文本”。前者用 JSON 列完全够用,后者老老实实建翻译表。
2. 核心细节解析与实操要点
2.1 JSON 列的结构设计
这一列到底怎么设计,直接决定了方案好不好用。我踩过坑,最开始我设计成 {"order_status_0": "待支付", "order_status_1": "已支付"},结果发现字段名里带序号,前端解析起来还得拼 key,非常不优雅。后来调整成更合理的结构:
这样设计有几个好处:外层 key 是字段名,内层 key 是枚举值。前端拿到这一列 JSON 之后,按字段名和孩子 key 去查,要哪个字段的翻译就是一行代码的事。而且如果前端需要预加载所有翻译映射,直接遍历这个对象就可以生成一个全局字典。
你可能会问,为什么不让后端把翻译好的 label 直接返回来,非要返回这一坨 JSON 让前端自己查?核心原因在于,列表数据里同一个枚举值会出现在很多行里,如果后端直接返回翻译好的文本,每一行都要去翻译一次,效率低。而前端拿到 JSON 映射后,只需要构建一次 map,就能在整页表格里复用。 这就是“一列 JSON”比“直接翻译字段”更高效的原因。
2.2 静态字典的存放策略
管理后台有很多翻译是全局通用的,比如“性别:男/女”“状态:启用/禁用”。这种不建议放在每一行数据的 JSON 里,因为太占地方,重复度高。我建议区分两类:
- 全局字典:写死在前端项目里的
locale文件中(比如zh-CN.js、en-US.js)。里面管全局通用枚举,如状态、性别、是否。 - 业务字典:存放在数据库这一列 JSON 里,专门管业务自定义字段的枚举翻译,如订单来源渠道、优惠券类型、审核节点名称。
这样做的原因是,全局字典的修改频率极低,跟着前端版本走完全没问题。业务字典的修改频率稍高,由运营在后台维护更合理。如果混在一起,前端每次发版为了改一个字段的文案,代价太大。
实际操作上,我会在 utils/i18n.js 里写一个 getLabel(field, value, localeJson) 方法,优先查业务字典,查不到再回退全局字典,再查不到就直接展示原始值,避免出现空白格。
2.3 语言切换与回退机制
管理后台做国际化,不可能要求运营把每种语言都翻译得完美无缺。所以必须有回退逻辑。我的玩法是:JSON 列里默认存一份完整中文,其他语言能翻多少翻多少。前端解析时,如果当前语言查不到对应翻译,自动回退中文,中文也没有,就回退原始枚举值。
实现思路大致这样:切换语言时,把当前语言存到 localStorage,同时全局触发一个事件。表格渲染时,每一行都调用 getLabel,函数内部读取当前语言,依次查“目标语言 -> 中文 -> 原始值”。
这一套在体验上很稳。因为管理后台的使用者往往特定国家的运营人员,他们可能只切一次语言,之后就固定了。跟“页面整体翻译”不同,这种“数据字典翻译”对回退机制的依赖很高,设计初期就把回退链路想好,后面就不用返工。
2.4 字段命名和表结构变更的注意事项
加这一列的时候,命名要尽量语义化。我见过有人用 extra、remark_json,结果半年后自己都忘了里面装的是什么。建议用 locale 或者 i18n_json,一看就知道是国际化的翻译映射。
表结构变更可以这么做:
注意两点。第一,MySQL 5.7 以上才支持 JSON 类型,如果是 5.6 或更老版本,建议用 TEXT 类型代替,反正前端解析也是 JSON.parse,没区别。第二,这个字段允许为 NULL,不要加 NOT NULL 约束,避免历史数据迁移时报错。历史数据可以先设为 NULL,等业务访问时由程序做一次惰性写入。
3. 实操过程与核心环节实现
3.1 完整的后端数据结构示例
这里我以一个真实的订单表为例子。假设 order 表有 id、order_no、status、pay_method、channel 几个核心字段,再加上 locale 列。查询接口返回的数据大概长这样:
后端连实体类都不用改,只要查询 SQL 里带了 locale 字段,序列化时自然会出现在 JSON 结果里。这是“后端零改动”里最值钱的部分——对老系统,可能真的就只需要 DBA 执行一条 ALTER TABLE 而已。
3.2 前端核心解析代码实现
前端需要一个轻量的工具函数,用来解析那一列 JSON。我通常放在 src/utils/i18n.js 里:
然后在表格组件里这么用:
这一段可以说是整个方案的核心,“一行代码解析”就是靠 getLabel 这个函数实现的。实测下来,Vue 或 React 都没问题,Angular 也兼容,因为它只是一个纯函数。
3.3 数组场景怎么处理
管理后台还经常遇到“多选值”的场景,比如一个订单有多个标签,数据库里存的是逗号分隔的字符串或者 JSON 数组。这种情况下,枚举翻译就不能简单按字段查了。我的做法是:在 locale JSON 里单独建一个数组类型的映射,前端解析时先 split,再逐项翻译。
前端这样处理:
这里有一个细节:如果数据库里 tags 存的就是 [0, 1, 2] 这种 JSON 数组,那就直接遍历数组翻译。总之,数据类型的差异只在处理逻辑上有一点变化,整体架构不变。
3.4 查询列表时如何减少重复查询
既然这一列 locale 是挂在业务行上的,查询列表时天然会带出来。如果你的表加了这一列,但接口返回时被后端的字段过滤规则干掉了,记得把这一列加入白名单。用 MyBatis-Plus 的时候,实体类如果有 @TableField(exist = false) 的字段,要注意别误伤。如果是 Map 查询,基本上不用管,因为 Map 会把查询到的所有列都返回。
另外,如果列表接口一次性返回几千行数据,每一行都带一个不小的 JSON 字段,要注意返回体大小。实测下来,几百行的列表,多了这个字段也就多几十 KB,完全可控。但如果是非常大列表(比如导出全量数据),可以考虑在导出接口里把这个字段剔除,因为导出一般走 Excel,文案翻译在导出时由后端临时映射,不影响前端体验。
3.5 后端框架兼容情况:MyBatis-Plus 和若依
我主要用 MyBatis-Plus 和若依框架(RuoYi)比较多,这里单独讲一下兼容性。
MyBatis-Plus 的实体类默认按驼峰映射下划线字段。你只要在实体里加一个 private String locale; 字段,查询时就能直接映射。不需要额外配置 TypeHandler,因为 locale 在 MySQL 里是 JSON 类型,JDBC 驱动会自动转成字符串。这一点实测很稳。
若依框架要走一遍它的代码生成器。最简单的做法是:数据库加好 locale 列之后,重新生成一遍代码(或者手动在实体类里补上字段),前端直接用生成好的接口。若依的 BaseEntity 自带 params 扩展字段,如果你不想动实体类,也可以把 locale 塞到 params 里返回。但那样做有两个副作用:一是和业务字段语义混在一起,二是前端取值要绕一圈,不推荐。
如果你用的是 Spring Boot + JPA,更简单,实体加一个 @Column(columnDefinition = "json") private String locale; 就行。
3.6 管理后台编辑端的实现
聊完读,还得聊写。运营要能维护这些翻译文案,通常是在详情页加一个“多语言配置”的 Tab,这里放一个动态表单。前端结构大概是这样的:加载详情时,把 locale 字段解析成表格,每一行是“字段名 -> 枚举值 -> 对应翻译”。
编辑完保存时,前端把整个 JSON 对象 JSON.stringify 后放进请求体,后端老代码直接接收并更新到数据库。因为后端只是把这个字段当一个普通字符串处理,所以依旧是零改动。
这里有个小坑要提醒:运营在编辑时,前端要保证 JSON 的结构不乱,特别是枚举值如果是数字,保存时不能变成字符串,否则前端解析时 localeJson[field][value] 查不到(数字 0 和字符串 "0" 是不同 key)。我通常在保存前做一次序列化清洗:
这段代码翻译成大白话就是:把数字字符串 key 老老实实转回数字类型,这样前端 getLabel 的时候才不会因为类型不一致而匹配失败。 这个问题属于典型的“不踩不知道,一踩想骂人”的坑,在写文章时我必须重点拎出来讲。
4. 常见问题与排查技巧实录
4.1 数字 key 的类型不匹配
前面提到过,数据库 JSON 里如果存的是 "0": "待支付",前端 getLabel 传入的 value 如果是数字 0,用 localeJson[field][value] 就会查不到,因为 JS 对象的 key 都是字符串,localeJson[field][0] 实际会转换成 localeJson[field]["0"]——等等,这里其实能查到。
那真正的坑在哪?在于反向场景:数据库 JSON 里存的是数字 key(JSON.stringify 后变成字符串),前端查询时用字符串 "0" 和数字 0 都能命中,因为 JS 对象索引会把数字自动转字符串。但如果你用 Map 结构存储就不会自动转换。还有一个场景是后端用某些语言把 JSON 解析成 Map 再序列化时,数字 key 类型可能发生变化,导致前端拿到的 key 是 0 而不是 "0",进而出现 localeJson[field]["0"] 查不到(实际上是同一个)的反直觉问题。
最稳妥的做法是:在 getLabel 里先统一做一次 string 转换:
这样无论数据库里 key 是数字还是字符串、传入的 value 是数字还是字符串,都能稳定匹配。这个改动小到不能再小,但能避免九成以上的“翻译不出来”问题。
4.2 老数据没有 locale 字段
给线上表加一列并不可怕,可怕的是存量数据的 locale 字段是空的。前端表格渲染时,scope.row.locale 是 undefined,getLabel 就会直接短路,返回原始 value。这意味着所有枚举都会以数字形式展示,用户会看到一堆 0、1、2。
解决思路有两种。第一种,写一个一次性脚本,扫描所有业务表,把已有的业务字典回填到 locale 字段里,这需要后端协助,最好在发版窗口执行。第二种,更简单但也要后端配合,就是在前端全局字典里先硬编码一份中文映射,让老数据在没有 locale 的情况下也能显示中文。
我个人倾向第二种,因为老系统上线国际化时,中文翻译是必有的,全局字典本来就要写,提前放进全局兜底即可。新数据进来时再依赖 locale 字段的完整映射。
4.3 前端语言切换后表格没刷新
这是 Vue 项目容易踩的坑。切换语言之后,表格数据还是原来那批对象,getLabel 函数虽然换了语言读取逻辑,但组件没有重新渲染,界面纹丝不动。解决方案是在切换语言时,给表格组件加一个 :key="locale",强制重新渲染。
React 的话,多半是在状态管理里放一个 locale 字段,切换后触发组件重新渲染即可。本质逻辑相同——语言切换必须引起视图层重新渲染,而不是仅仅改一个存储值。
4.4 JSON 列占空间和性能
有人会担心,每行都带一个 JSON 会不会让表变得臃肿。实测下来,一个包含 10 个字段翻译映射的 JSON,序列化后大概是 300~500 字节,一万行数据也就是 5MB 左右,完全不是问题。查询性能方面,MySQL 的 JSON 列不走索引、也不能走索引,但你要知道你根本不需要用它做 WHERE 条件,只是作为返回数据,所以性能损耗几乎为零。
如果哪天彻底不需要国际化,把这个列 DROP 掉就行,不留尸体。这也是相比“多张翻译表+外键关联”方案最大的运维优势。
4.5 常见问题速查表
为了方便你排查问题,我整理一张速查表:
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 所有枚举都显示原始数字 | locale 字段为空 | 前端全局字典兜底,或写脚本回填 |
| 部分字段翻译不出来 | locale JSON 里缺字段映射 | 检查 JSON 的 key 是否和接口字段名一致 |
| 切换语言后界面没变化 | 组件未强制刷新 | 给表格动态加 key |
| 编辑保存后翻译失效 | 数字 key 被转成字符串 | 保存前做类型清洗 |
| 导出 Excel 时文案是数字 | 导出未处理 locale | 导出前由后端做映射或前端先翻译再导出 |
5. 扩展思路与更多玩法
5.1 结合代码生成器实现“半自动配置”
如果你用的是若依这类带代码生成器的框架,可以再进一步。代码生成器生成实体类时,自动加上 locale 字段。生成的前端页面里,自动把枚举字段替换成 getLabel 渲染。这样新业务的开发效率会更高,基本上建完表、跑完生成器,国际化的基础能力就带出来了。
我实际做过一个内部脚手架,就是这样玩的。在代码生成器的模板里,识别所有 enum 类型的字段注释,自动读取数据库里的字典表,并把映射 JSON 灌进 locale 字段的初始化值里。上线之后,运营只需要在后台调整文案,前端和后端都不需要改代码。
5.2 把 locale JSON 做成可缓存的配置接口
有一种更激进的做法:后端把 locale 字段的 JSON 内容聚合成一个全局配置接口,比如 /api/i18n/dicts。前端在登录时拉取一次,缓存到内存里。这样表格渲染时,甚至不需要依赖行的 locale 字段,直接从全局配置里取。这个方案适合量级较大的系统,相当于把“数据库行内 JSON”升级成了“分布式缓存里的一份配置”。
但这里有一个权衡:如果翻译跟着业务行走(不同岗位看到的翻译配置不同),全局配置就不适用。我的建议是,小体量用行内 JSON,大体量用全局配置接口,千万别一上来就做全局缓存,先跑通再说。
5.3 与前端社区标准 i18n 库的融合
很多人会问,这个方案和 vue-i18n、react-i18next 这类库冲突吗?完全不冲突。你的页面标题、按钮文字、菜单栏依然可以用这些库来管理。而我们的 JSON 列只管“数据里的枚举翻译”,两者各司其职。你可以把 getLabel 看成是 i18n 库之外的一个补充函数,专门处理动态数据集的翻译。
如果想让 getLabel 也用上 i18n 库的语言状态管理,可以在实现时读取 i18n.global.locale,而不是自己维护一套语言变量。这样切换语言时,语言状态天然是全局的,不会出现两套状态不同步的问题。
5.4 可能的坑:字段值往往不是中文
使用这个方案时,还会遇到一个隐藏问题:如果业务字段本身存的是中文,比如 channel 字段直接存了“抖音”而不是“douyin”,那 locale 映射就属于重复造轮子。 在做国际化之前,先确认业务表里存的是“业务编码”而不是“展示文本”。如果数据库里已经直接存中文,那这个方案基本帮不上忙,你需要先做一次数据治理,把展示文本改成业务编码体系。
而且这种事越早做越省事,等到前端已经写死了“如果 channel 是抖音就展示...”这种逻辑,再改就是牵一发动全身。我接手过一个项目,渠道字段直接存的中文,导致国际化需求提上来时,整个渠道模块要重新梳理数据字典,前后端一起改动,加班了两周才搞定。
结尾:关于方案落地的个人体会
最后聊一点实在的。这个方案执行到位的关键,不在于技术难度,而在于“先想清楚边界”。管理后台的国际化,绝大多数时候就是枚举翻译,别把它妖魔化。一列 JSON 加上前端的解析函数,就能解决掉 80% 的痛点,剩下的 20% 才是真正需要翻译表或第三方服务的复杂场景。
我在实际使用中的体会是,越简单的方案越容易被团队接受。当时我给后端同事讲了十分钟,他听完就回去执行 ALTER TABLE 了;前端同事拿到 getLabel 函数之后,半天时间就把整站表格的枚举翻译都搞定了。没有建表、没有改接口、没有权限讨论、没有数据迁移的事故。如果当初按传统方案去设计翻译表,这会还在讨论“要不要加 language 维度索引”。
最后再分享一个小技巧:上线之后,可以把每种语言的文案校验写进自动化测试里,确保运营提交的 locale JSON 在结构上合法。我当时写了一个简单的 JSON Schema 校验,每次运营编辑保存时先校验再落库,从此再没出现过“某个字段翻译丢了”的事情。这个技巧虽然不起眼,但真的能让方案长期稳定运行。