内容总览

国际化与本地化 思维导图

一、起源

1.1 三类需要本地化的内容

类别 示例 解决手段 难点
界面与提示文案 按钮文字、操作提示、错误说明 资源文件按区域拆分 文案的覆盖度与维护
校验与异常消息 参数校验失败说明、业务错误提示 消息源与校验框架对接 消息来自框架还是业务代码
数据格式 时间、数字、货币、字符串排序 区域化的格式化 API 时区与区域规则本身的复杂性

前两类是"翻译"问题,第三类是"规则"问题。只做翻译而忽略格式,会出现中文界面里时间显示为本地时间而用户在其他时区看到错误时刻的情况。

1.2 单一语言假设的代价

  • 文案硬编码在代码或模板中,新增语言需要改动代码与重新发布。
  • 错误消息拼接字符串,无法整体替换,也无法按语言切换。
  • 时间统一按服务器时区处理,跨区域用户看到的时间偏移。
  • 字符串排序依赖数据库默认排序规则,多语言数据下顺序不符合该语言读者的预期。
  • 字符集链路中任一环节不是 UTF-8,就会出现乱码或截断,且问题往往在特定字符上才出现。

1.3 取舍

  • 后端返回错误码由前端映射文案:前端可复用同一套多语言资源,后端无需维护多语言消息,但错误码需要提前对外约定且不能随文案调整而变。
  • 后端直接返回本地化消息:调用方无需维护映射表,适合对第三方开放的接口,但消息文本的变更会影响调用方展示,需要保持稳定。
  • 实践中的常见组合:面向内部前端的接口返回错误码加默认消息,面向第三方的接口返回按 Accept-Language 协商后的消息。

二、原理

2.1 Locale 的构成与解析

Locale 由语言、国家或地区、变体三部分组成(如 zh_CN、en_US、pt_BR)。语言决定文案与格式,国家或地区决定区域内的具体规则,例如同样是英语,en_US 与 en_GB 的日期顺序与货币符号不同。

区域由 LocaleResolver 从请求中解析,四种策略的差异在"区域从哪里来"与"是否随请求变化":

策略 区域来源 特点 适用
AcceptHeaderLocaleResolver Accept-Language 请求头 无状态,每次请求独立判定;无法通过界面切换 无需用户手动切换的接口服务
CookieLocaleResolver Cookie 可跨请求保持,切换后下次请求生效 有界面语言切换的站点,不依赖会话
SessionLocaleResolver Session 属性 会话内保持 需要与会话生命周期一致时
FixedLocaleResolver 固定值 忽略请求信息,永远返回同一区域 仅在明确只支持一种区域时使用,该类在新版本中已标记为不推荐

与之配合的是语言切换拦截器:从请求参数(默认参数名为 locale)读取目标区域并写入解析器,因此必须把拦截器注册进拦截器链,否则参数不起作用。

选择顺序:接口服务用请求头策略;有界面切换功能的站点用 Cookie 策略,避免会话失效导致语言回退;一旦选定策略,全部环境需保持一致,否则会出现"测试环境能切换而生产不能"的差异。

2.2 消息解析:MessageSource

消息源按资源文件名查找消息,文件名由基名加区域后缀构成,查找顺序是逐级回退:

请求区域 zh_CN,基名 messages
  1. messages_zh_CN.properties
  2. messages_zh.properties
  3. messages.properties           (无区域后缀,作为兜底)
  4. 未找到 -> 抛出 NoSuchMessageException 或返回 code 本身

由此产生两条实践结论:

  • 无区域后缀的默认文件必须存在且内容完整,它既是兜底也是唯一语言时的唯一文件。
  • 缺失消息不应表现为运行时异常,React 式的前端与后端服务都更希望拿到一个可读的替代值,因此应保持"找不到时返回消息键"的行为,并在测试阶段把缺失项暴露出来。

一个高频陷阱是系统默认区域:部分实现会在找不到对应区域时回退到系统的默认区域,而服务器上的默认区域取决于启动环境的语言设置。结果是同一份代码在不同服务器上返回不同语言。正确做法是关闭该回退,只按"具体区域、语言、默认文件"的顺序查找。

消息中的占位符用于拼接动态内容,占位符的位置在不同语言中可能不同,因此不能在代码中拼接消息片段,必须整体交给消息源处理。

2.3 校验消息与异常消息的本地化

校验消息有两个来源,需要区分处理:

来源 配置位置 说明
框架内置校验消息 校验框架的默认消息文件 如"不能为空""长度必须在某范围内"的默认文案
自定义校验消息 注解的 message 属性引用 Spring 消息键 形如 {user.name.required},由消息源解析

对接的关键是让校验框架使用与业务相同的消息源,使自定义消息键与业务消息统一在一处维护;同时需要保证校验发生的时机在区域已经解析之后,否则读取到的是默认区域。

异常消息的本地化应放在统一异常处理中完成:异常只携带错误码与参数,消息在响应生成时按当前区域解析。这样异常本身与语言无关,也避免了在业务代码中到处读取区域信息。

2.4 格式化的本地化

内容 区域差异 处理方式
日期与时间格式 年月日顺序、分隔符、12 或 24 小时制 用区域化的格式化器,不手工拼接格式串
数字 千分位分隔符、小数点符号 使用区域化的数字格式
货币 符号位置、小数位、币种本地名称 金额与币种分开存储,展示时按区域格式化
字符串排序 字母顺序规则不同,如德语变音、瑞典语字母表 展示层排序使用区域化的比较器;数据库排序受排序规则影响
姓名与地址 顺序与字段数量不同 结构上避免假设"名在前姓在后"

格式化必须显式传入区域,依赖默认区域会得到随环境变化的结果。数据库中的排序由字符集与排序规则决定,应用层排序与数据库排序不一致时,会出现"列表顺序与预期不同"或"分页边界重复"的问题。

2.5 时区与夏令时

三类时间类型的语义差别是时区问题的根源:

类型 是否含时区 语义 使用建议
Instant 是(始终为 UTC) 时间轴上的一个点 存储与传输使用
ZonedDateTime 是(指定区域) 带区域规则的时刻 需要区域规则计算时使用
LocalDateTime 否 墙上时钟的读数 仅用于表示"不指向具体时刻"的语义

处理规则:

  1. 存储统一用 UTC,不存储本地时间,避免跨时区与跨夏令时产生歧义。
  2. 展示按用户或业务所属区域换算,换算发生在边界(接口输出或界面渲染),不在业务逻辑中进行。
  3. 传输使用带时区偏移或明确 UTC 标记的格式,避免接收方按本地时间解释。
  4. 夏令时带来两种特殊情况:春季前跳时某些本地时刻不存在,秋季回拨时某些本地时刻出现两次。按本地时间做定时任务或按本地日期切分数据时会因此产生漏执行或重复执行,需要按 UTC 或带区域规则的方式计算。

2.6 字符集与编码

  • 全链路统一 UTF-8:请求与响应的内容类型声明、容器编码配置、数据库连接的字符集参数、数据库与表的字符集。
  • 数据库字符集的选择需要考虑是否需要存储四字节字符(如表情符号),传统的三字节 UTF-8 存储这类字符会失败或被截断。
  • 排序规则决定比较与排序行为,同时影响唯一索引的判定,例如是否区分大小写与重音符号;变更排序规则属于结构变更,需要按迁移流程处理(见 数据库 Schema 版本化迁移)。
  • 编码不一致的典型表现是乱码,排查顺序是从客户端到数据库逐段确认,而不是只检查某一处配置。

2.7 不应本地化的内容

本地化的边界需要明确,否则会带来排障困难:

内容 是否本地化 原因
日志消息 不 日志需要统一检索,混入多语言会使关键字匹配失效
指标名与标签值 不 指标需要稳定聚合,语言变化会破坏时间序列连续性
错误码 不 调用方按错误码分支,文案可翻译而错误码不可变
接口字段名与枚举值 不 属于契约的一部分
数据库内存储的枚举 不 存代码而非文案,文案在展示层解析
面向用户的提示与通知 是 直接呈现给用户

三、实现

3.1 Spring Boot 配置

spring:
  messages:
    basename: i18n/messages          # 资源文件基名,位于 resources/i18n 下
    encoding: UTF-8
    fallback-to-system-locale: false # 关闭系统区域回退,避免服务器环境差异
    always-use-message-format: false # 关闭后对含单引号的文案更友好
    use-code-as-default-message: true # 找不到消息时返回消息键,避免抛异常
  web:
    locale: zh_CN                    # 默认区域
    locale-resolver: accept-header   # 解析策略:accept-header 或 fixed
@Configuration
public class I18nConfig implements WebMvcConfigurer {

    // 有界面语言切换需求时改用 CookieLocaleResolver
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("lang");
        resolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE);
        resolver.setCookieMaxAge(Duration.ofDays(30));
        resolver.setCookiePath("/");
        return resolver;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
        interceptor.setParamName("lang");         // 与解析器使用的参数名保持一致
        registry.addInterceptor(interceptor).addPathPatterns("/**");
    }
}

要点:解析器的参数名与切换拦截器的参数名必须一致,且拦截器的注册路径需覆盖需要切换语言的接口,否则参数会被忽略。

3.2 消息文件组织

src/main/resources/i18n/
├── messages.properties            # 默认兜底,键必须完整
├── messages_zh_CN.properties
├── messages_en_US.properties
└── messages_ja_JP.properties
# messages_zh_CN.properties
error.order.not.found=订单 {0} 不存在
error.stock.insufficient=库存不足,当前可用 {0}
user.name.required=用户名不能为空
user.name.size=用户名长度必须在 {2} 到 {1} 之间
# messages_en_US.properties
error.order.not.found=Order {0} not found
error.stock.insufficient=Insufficient stock, available: {0}
user.name.required=User name is required
user.name.size=User name length must be between {2} and {1}

组织规范:

  • 键名按"模块加用途"分层,避免不同模块出现同名键。
  • 占位符按位置引用,不在代码中拼接片段,使不同语言的语序可以自由调整。
  • 新增语言时以默认文件为清单逐项核对,缺失项在测试阶段通过比对文件键集合暴露。
  • 文案中出现的引号与特殊字符需要注意转义规则,必要时关闭按格式化解析以避免单引号被吞掉。

3.3 校验消息本地化

public class UserCreateRequest {

    @NotBlank(message = "{user.name.required}")
    @Size(min = 2, max = 20, message = "{user.name.size}")
    private String name;

    @NotNull(message = "{user.email.required}")
    @Email(message = "{user.email.invalid}")
    private String email;
}
@RestControllerAdvice
public class ApiExceptionHandler {

    // 校验异常:按当前区域解析消息键,异常本身不携带文案
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException e) {
        List<String> details = e.getBindingResult().getFieldErrors().stream()
                .map(fe -> fe.getField() + ": " + fe.getDefaultMessage())
                .toList();
        return ResponseEntity.badRequest().body(ApiError.of(ErrorCode.PARAM_INVALID, details));
    }

    // 业务异常:异常只带错误码与参数,消息在响应阶段按区域生成
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiError> handleBusiness(BusinessException e, Locale locale) {
        String message = messageSource.getMessage(e.getErrorCode().key(), e.getArgs(), locale);
        return ResponseEntity.status(e.getErrorCode().httpStatus())
                .body(ApiError.of(e.getErrorCode(), message));
    }

    @Autowired
    private MessageSource messageSource;
}

要点:异常处理器方法可以直接声明 Locale 参数由框架注入,无需自行从请求中解析;业务异常不保存消息文本,只保存错误码与参数,是保证消息可按区域变化的前提。

3.4 时间处理规范

public class OrderResponse {

    // 传输使用带偏移的格式,明确表示时刻
    @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ssXXX", timezone = "UTC")
    private Instant createdAt;

    // 仅表示业务日期,不指向具体时刻时使用 LocalDate
    private LocalDate deliveryDate;
}
spring:
  jackson:
    time-zone: UTC                       # 序列化统一使用 UTC
    serialization:
      write-dates-as-timestamps: false    # 输出可读格式而不是时间戳
// 界面展示时按用户区域换算,换算只在边界发生
ZonedDateTime display = order.getCreatedAt().atZone(userZoneId);
String text = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm", locale).format(display);

// 金额按区域格式化,币种与金额分开存储
NumberFormat currencyFormat = NumberFormat.getCurrencyInstance(locale);
currencyFormat.setCurrency(Currency.getInstance(order.getCurrency()));
String amountText = currencyFormat.format(order.getAmount());

// 展示层排序使用区域化比较器,避免与数据库排序结果不一致
List<String> sorted = names.stream()
        .sorted(Collator.getInstance(locale))
        .toList();

3.5 前后端文案职责划分

内容 归属 理由
界面元素文案 前端 与渲染逻辑同源,切换语言无需请求后端
表单校验提示 前端负责格式,后端负责最终校验消息 前端提示用于即时反馈,后端消息是最终判定
业务错误说明 后端提供错误码与参数,前端映射文案 前端可在不发布后端的情况下调整措辞
通知与邮件内容 后端 由服务端直接发送,无法依赖前端渲染

选择前端映射文案时,错误码与参数的稳定性成为契约的一部分,需要纳入接口变更管理;选择后端返回消息时,需要保证消息文本变更不影响调用方解析。

3.6 验证与排查

# 验证按请求头协商返回对应语言的消息
curl -s -H 'Accept-Language: en-US' http://localhost:8080/api/orders/not-exist
curl -s -H 'Accept-Language: zh-CN' http://localhost:8080/api/orders/not-exist

# 验证切换参数是否生效(使用 CookieLocaleResolver 与 LocaleChangeInterceptor 时)
curl -s -i -H 'Accept-Language: en-US' 'http://localhost:8080/api/orders/not-exist?lang=zh_CN' | grep -i 'set-cookie\|content-language'

# 验证时间输出是否为 UTC 带偏移格式
curl -s http://localhost:8080/api/orders/1 | jq '.createdAt'

# 核对消息文件键集合是否一致(缺失项会被列出)
diff <(grep -oE '^[^#][^=]*' src/main/resources/i18n/messages.properties | sort) \
     <(grep -oE '^[^#][^=]*' src/main/resources/i18n/messages_en_US.properties | sort)

# 核对文件的编码是否为 UTF-8
file -i src/main/resources/i18n/messages_zh_CN.properties

# 核对数据库与连接的字符集
mysql -e "SHOW VARIABLES LIKE 'character_set%'; SHOW VARIABLES LIKE 'collation%';"

3.7 常见问题对照

现象 常见原因 处理方式
部分服务器返回的语言与预期不同 开启了系统区域回退,服务器默认区域不同 关闭系统区域回退
语言切换参数不起作用 未注册切换拦截器,或参数名与解析器不一致 核对拦截器注册与参数名
校验消息始终是默认语言 校验发生时区域未解析,或校验消息未接入消息源 核对解析器生效位置与消息源对接
消息中显示为消息键本身 默认文件缺少该键 补齐默认文件,并在测试中比对键集合
含单引号的文案被吞掉 消息被按格式化规则解析 转义或关闭按格式化解析
时间显示偏移 存储了本地时间,或序列化时区配置不一致 统一存储 UTC 并在边界换算
定时任务在夏令时切换日漏执行或重复执行 按本地时间计算触发时刻 按 UTC 或带区域规则计算
列表顺序与预期不符 数据库排序规则与应用层比较器不一致 统一排序来源
特定字符乱码或被截断 链路中某处不是 UTF-8,或数据库字符集不支持四字节字符 逐段核对字符集配置
唯一索引判定与业务预期不同 排序规则区分大小写或重音符号 核对排序规则,必要时按业务调整

四、总结

  1. 本地化包含文案翻译与区域规则两部分,只做翻译会遗漏时间、数字与排序的区域差异。
  2. 区域由解析器决定,四种策略的差别在于区域来源与是否跨请求保持;有界面切换需求时用 Cookie 策略,接口服务用请求头策略。
  3. 消息查找按具体区域、语言、默认文件逐级回退,默认文件必须存在且键完整;系统区域回退应关闭,否则同一份代码在不同服务器上表现不一致。
  4. 校验消息与业务消息应共用同一消息源,校验注解通过消息键引用文案,使多语言维护集中在一处。
  5. 异常只携带错误码与参数,文案在响应阶段按区域生成,这样异常与语言解耦。
  6. 时间存储统一使用 UTC,换算与格式化只发生在展示边界;LocalDateTime 不应用于表示指向具体时刻的语义。
  7. 夏令时会带来本地时刻不存在与重复两种情况,按本地时间计算的定时任务与数据切分需要改用 UTC 或区域规则。
  8. 字符集需要在请求、容器、连接、数据库与表各层统一为 UTF-8,排序规则同时影响排序与唯一索引的判定。
  9. 日志、指标名、错误码、接口字段名与库内枚举值不应本地化,否则会破坏检索、聚合与契约稳定性。
  10. 文案职责的前后端划分决定了错误码与参数是否属于对外契约,一旦选择前端映射,就必须按契约变更流程管理错误码。