国际化 spring-boot-nebula-i18n

开箱即用的多语言响应组件：自动解析请求语言、按语言翻译统一响应 msg 与错误码文案，支持本地资源与远程配置中心（HTTP）加载。

引入依赖

<dependency>
    <groupId>io.github.weihubeats</groupId>
    <artifactId>spring-boot-nebula-i18n</artifactId>
    <version>3.0.6</version>
</dependency>

快速开始

1. 配置

nebula:
  i18n:
    default-locale: zh_CN
    basename: i18n/messages
    supported-locales:
      - zh_CN
      - en_US
    header-name: X-Lang
    param-name: lang

2. 资源文件

放在 src/main/resources/i18n/ 下（basename 对应路径）：

i18n/messages_zh_CN.properties

result_code.param_miss=缺少必要的请求参数
greeting=你好，{0}！

i18n/messages_en_US.properties

result_code.param_miss=Missing required request parameter
greeting=Hello, {0}!

3. 请求示例

语言来源优先级：X-Lang header → lang query 参数 → Accept-Language → 默认语言。

### 中文（默认）
GET localhost:8091/i18n/error

### 英文 - X-Lang header
GET localhost:8091/i18n/error
X-Lang: en_US

### 英文 - lang query 参数
GET localhost:8091/i18n/error?lang=en_US

框架自动解析语言并写入 LocaleContextHolder，NebulaResponse.msg 与全局异常处理器输出按语言翻译。

消息 key：三种指定方式

错误码消息通过 key 查找翻译，按以下优先级取最终 key：

优先级	方式	说明
1	显式 getMessageKey()	实现 IErrorCode 时 override，完全手动控制
2	@NebulaMessageKey 注解	标注在枚举常量上手动指定
3	自动生成	蛇形类名.蛇形常量名

自动生成规则：ResultCode.PARAM_MISS → result_code.param_miss，无需任何配置。

@Getter
@AllArgsConstructor
public enum SampleErrorCode implements IErrorCode {

    // 注解手动指定 key
    @NebulaMessageKey("order.not_found")
    ORDER_NOT_FOUND(40001, "订单不存在"),

    // 未标注，自动生成 sample_error_code.stock_not_enough
    STOCK_NOT_ENOUGH(40002, "库存不足");

    private final int code;
    private final String message;
}

内置 ResultCode 已支持国际化，message 作为未命中翻译时的兜底文案。

业务代码取文案

任意位置取当前请求语言的文案：

// 按当前请求语言（LocaleContextHolder）
String msg = NebulaI18nMessage.get("greeting", name);

// 指定语言 / 指定兜底
String msg = NebulaI18nMessage.getOrDefault("greeting", args, "Hello", locale);

未装配 MessageSource 或 key 未命中时安全回退，不抛异常。

与 Web 模块整合

引入 spring-boot-nebula-web 后自动生效：

• NebulaResponse.fail(IErrorCode) 写 msg 前按请求语言翻译
• NebulaRestExceptionHandler 各异常响应文案自动翻译
• 未装配 i18n 模块时行为不变（回退默认 message），不影响现有调用方

远程文案加载

支持从远程配置中心拉取文案，本地资源作为兜底，远程优先覆盖。

方式一：HTTP 拉取（内置实现）

nebula:
  i18n:
    remote:
      enabled: true
      # {basename}、{locale} 占位符
      url-template: "http://config.xxx/i18n/{basename}_{locale}.properties"
      refresh-interval-seconds: 300   # 定时刷新，0=关闭

启动时自动加载，之后按配置间隔刷新；远程未命中时自动下探本地资源。

方式二：SPI 自定义实现

注册自定义 RemoteMessageLoader bean 即可覆盖内置 HTTP 实现，接入 Nacos / Apollo 等任意配置中心：

@Bean
public RemoteMessageLoader myRemoteMessageLoader() {
    return () -> {
        Map<Locale, Properties> map = new HashMap<>();
        // 从配置中心拉取文案放入 map
        return map;
    };
}

远程 vs 本地

远程（优先）→ 本地资源（兜底）→ 默认 message

远程可提供本地没有的新 key，也可覆盖本地同名 key。

配置项

配置	默认值	说明
nebula.i18n.enabled	true	模块开关
nebula.i18n.default-locale	zh_CN	默认语言
nebula.i18n.basename	i18n/messages	本地资源 basename
nebula.i18n.supported-locales	[zh_CN, en_US]	支持语言（用于远程加载与校验）
nebula.i18n.header-name	X-Lang	自定义语言 header，空则停用
nebula.i18n.param-name	lang	query 语言参数，空则停用
nebula.i18n.prefer-accept-language	false	Accept-Language 是否优先于自定义 header/param
nebula.i18n.fallback-to-default	true	未命中是否回退系统语言
nebula.i18n.remote.enabled	false	是否启用远程加载
nebula.i18n.remote.url-template	-	远程 URL 模板，支持 {basename}/{locale}
nebula.i18n.remote.refresh-interval-seconds	0	定时刷新间隔，0 关闭
nebula.i18n.remote.timeout-seconds	5	远程请求超时

完整示例

参考 spring-boot-nebula-i18n-sample：内置 mock 远程配置服务，演示远程加载、注解 key、自动 key、NebulaI18nMessage 全场景。