SpringBoot项目的国际化流程

在 Spring Boot 项目已经开发完成后，想要实现国际化（i18n），让所有提示信息（后端返回的错误消息、成功消息、异常信息、枚举描述等）支持多语言，处理流程如下：

1. 创建国际化资源文件（messages.properties）

在 src/main/resources 目录下（新建 i18n 子目录），创建以下文件：

src/main/resources/
└── i18n/
    ├── messages.properties           # 默认语言（通常是中文或英文）
    ├── messages_zh_CN.properties     # 简体中文
    ├── messages_en_US.properties     # 美式英文
    ├── messages_zh_TW.properties     # 繁体中文（可选）
    └── messages_ja.properties        # 日语（可选）

messages.properties（中文示例）：

# 通用提示
success=操作成功
error.system=系统异常，请稍后重试
error.notfound=资源不存在

# 业务提示
user.login.success=登录成功
user.login.fail=用户名或密码错误
user.notfound=用户不存在

messages_en_US.properties（英文示例）：

success=Operation successful
error.system=System error, please try again later
error.notfound=Resource not found

user.login.success=Login successful
user.login.fail=Username or password is incorrect
user.notfound=User not found

注意：

• 文件名必须以 messages 开头（Spring Boot 默认查找规则）。
• 所有提示统一放在 i18n 目录下，方便管理。

2. 配置 application.yml（或 application.properties）

# application.yml
spring:
  messages:
    basename: i18n/messages          # 资源文件基础名（支持通配符）
    encoding: UTF-8                 # 必须是 UTF-8
    fallback-to-system-locale: false # 推荐设置为 false（找不到对应语言时不回退到系统默认Locale）
    use-code-as-default-message: true # 找不到key时直接返回code（调试方便，上线可改为false）

#  properties
spring.messages.basename=i18n/messages
spring.messages.encoding=UTF-8
spring.messages.fallback-to-system-locale=false
spring.messages.use-code-as-default-message=true

3. 自定义 LocaleResolver 和 LocaleChangeInterceptor（支持前端传参切换语言）

Spring Boot 默认使用 AcceptHeaderLocaleResolver（根据请求头 Accept-Language 自动识别），生产环境通常还需要支持通过参数或 cookie 切换语言。

使用 SessionLocaleResolver + LocaleChangeInterceptor：

@Configuration
public class LocaleConfig implements WebMvcConfigurer {

    // 默认语言
    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver localeResolver = new SessionLocaleResolver();
        localeResolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE); // 默认简体中文
        return localeResolver;
    }

    // 拦截器：支持 ?lang=zh_CN 或 ?lang=en_US 切换语言
    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
        lci.setParamName("lang"); // 前端传参名
        return lci;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

若优先从请求头识别，再支持参数切换，可以自定义 LocaleResolver（更灵活）。

4. 在代码中使用 MessageSource 获取国际化消息

方式一：注入 MessageSource

@RestController
@RequestMapping("/api")
public class UserController {

    @Autowired
    private MessageSource messageSource;

    @GetMapping("/test")
    public ResponseEntity<String> test(Locale locale) { // Locale 可选从参数注入
        // 方式1：直接使用 locale 参数
        String msg = messageSource.getMessage("user.login.success", null, locale);

        // 方式2：从 LocaleContextHolder 获取当前语言（推荐！）
        String msg2 = messageSource.getMessage("user.login.success", null, LocaleContextHolder.getLocale());

        return ResponseEntity.ok(msg2);
    }
}

方式二：统一封装工具类

@Component
public class MessageUtils {

    private static MessageSource messageSource;

    @Autowired
    public void setMessageSource(MessageSource messageSource) {
        MessageUtils.messageSource = messageSource;
    }

    /**
     * 获取国际化消息
     */
    public static String getMessage(String code, Object... args) {
        return messageSource.getMessage(code, args, LocaleContextHolder.getLocale());
    }

    public static String getMessage(String code) {
        return getMessage(code, (Object) null);
    }
}

使用方式：

throw new BusinessException(MessageUtils.getMessage("user.notfound"));
// 或
return Result.error(MessageUtils.getMessage("error.system"));

5. 全局异常处理中使用国际化

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        // 假设 BusinessException 里面存了 messageCode
        String message = MessageUtils.getMessage(e.getCode(), e.getArgs());
        return Result.error(message);
    }

    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        return Result.error(MessageUtils.getMessage("error.system"));
    }
}

6. 支持参数占位符

# messages.properties
user.age.limit=年龄必须在 {0} 到 {1} 岁之间

String msg = MessageUtils.getMessage("user.age.limit", 18, 60);
// 输出：年龄必须在 18 到 60 岁之间

7. 常见最佳实践总结

处理点	处理方式
资源文件位置	src/main/resources/i18n/messages_*.properties
默认语言	简体中文（Locale.SIMPLIFIED_CHINESE）
语言切换方式	请求头 Accept-Language + ?lang=zh_CN
消息获取方式	优先使用 LocaleContextHolder.getLocale()
工具类	封装 MessageUtils 统一获取
异常消息	全部使用 code + MessageUtils 获取
找不到key	建议 use-code-as-default-message=false
编码	必须 UTF-8

 

8. 测试方法

• 浏览器开发者工具 → Network → 修改请求头 Accept-Language: en-US,en;q=0.9
• 或直接在 URL 后加 ?lang=en_US

完成以上步骤，你的 Spring Boot 项目就实现了标准的国际化支持，所有提示信息都可以根据用户语言自动切换。