大型系统多语言设计

目录

• 痛点
• 多语言场景
  • 静态文案多语言
  • 异常提醒
  • 异常抛出
• 词条设计
  • 词条key设计
    • 一、词条Key分层设计规范（保证唯一性与可读性）
  • 词条表设计
• 多语言物理模型设计
  • • 二、词条属性扩展设计（增强管理能力）
• 本地词条管理，和上线流程
• 参考资料

痛点

1 不同国家的语言，同一个语义宽度不一样，排版需要适配
2 生产环境翻译错误需要紧急修正，需要实时热更新，不需要发版

多语言场景

静态文案多语言

异常提醒

• 静态文案提醒
  如：手机号码格式不正确

• 带替换变量的提示。
  如单号比如某个sku没有库存。 词条定义
  "SKU_NO_STOCK": "Der SKU {sku} ist nicht auf Lager. Bitte wählen Sie einen anderen oder schauen Sie später wieder vorbei.",

  前端收到后端数据做替换符替换。

 {
  "success": false,
  "error": {        // 必选，统一用 error 对象封装异常信息
    "code": "SKU_NO_STOCK", // 标准化的错误码（必选）
    "params": {     // 可选，专门用于动态插值的键值对
      "sku": "ABC123" // 键名必须和词条中的占位符完全匹配
    },
    "errMessage": "Stock not found for sku: ABC123" // 可选，仅用于后端日志/调试
  },
  "data": [  // 业务数据集合
    { ... }, // 数据对象1
    { ... }  // 数据对象2
  ],
  "timestamp": "2024-05-28T10:00:00Z", // 可选
  "traceId": "req-123456" // 可选，用于问题追踪
}

异常抛出

抛出的异常类，除了要赋值 errorCode，还需要messageKey （多语言词条编码），variables可选

public class BizException extends RuntimeException {

    private static final long serialVersionUID = 1L;

    private String              errorCode;
    private String              messageKey;
    private Map<String, Object> variables;
}

词条设计

词条key设计

一、词条Key分层设计规范（保证唯一性与可读性）

1. 分层结构：系统域:产品线:模块:页面/功能:语义名
   • 示例：cbs:payment:invoice:btn_submit
     • cbs：核心银行系统（Core Banking System）
     • payment：支付产品线
     • invoice：发票管理模块
     • btn_submit：提交按钮的语义名称
   • 优势：通过层级划分，快速定位词条归属，避免不同系统或模块间的Key冲突。
     key定义规范

• 通用词条（如“提交”“取消”）提取到公共命名空间：common:btn_submit（各系统直接引用，无需重复翻译）
• 如商品详情页和购物车页均需显示“库存不足”，若语义相同则复用
• 语境或受众差异需独立 Key 的场景

2. 语义名称命名规则

   • 字符限制：仅使用小写字母、数字、下划线（如 merchant_list_title）；
   • 语义明确：动词+名词组合（如 create_order_failed），禁用无意义的缩写；
   • 长度控制：单级Key不超过20字符，总长不超过80字符（如 oms:warehouse:stock_alert）。

3. 动态语境标识
   对同一词条在不同场景的差异化翻译，增加语境后缀：

   • 示例：crm:contact:phone_number（默认） → crm:contact:phone_number:tooltip（悬浮提示专用）。

词条表设计

除了key和value字段，

多语言物理模型设计

二、词条属性扩展设计（增强管理能力）

除基础翻译文本外，词条需关联以下元数据属性：

属性字段	必填	说明	示例值
product_line	是	归属产品线	payment（支付产品）
module	是	功能模块分类	invoice（发票模块）
page_code	否	关联前端页面/路由路径	/payment/invoice/create
variable_definitions	否	动态变量定义（JSON格式，声明插值参数）	{"date":"日期","amount":"金额"}

本地词条管理，和上线流程

本地词条和线上词条的边界
本地词条：本地开发的时候用。不用管线上有没有配置，本地该怎么开发就怎么开发。
线上：读数据库。 前端代码是不是 先通过接口将数据库的词条翻译加载到缓存， 如果缓存没有数据再读本地的词条翻译

流程：
1 本地开发
本地开发新增词条，为了开发效率，不需要在数据库维护，直接在前端本地维护词条。
2 测试阶段。
将本地的词条合并到测试环境（test，sit等）。
具体实现：前端代码直连测试数据库，拿数据库的词条跟本地对比，找出本地比测试环境多的词条，做合并操作（选择哪些词条合并到数据库）。
3 上预发布/或者上线。
sit导出来（变更），导入到生产 （需要人工审核）

4 生产紧急修改了词条需要合并到本地。 生产导出excel，导入到sit。 本地跟sit做比较，将sit的词条合并到本地

参考资料