Spring Boot 国际化配置项详解

Spring Boot 国际化配置项详解

1. 核心配置项分类

将配置项分为以下类别，便于快速定位：

1.1 消息源配置（MessageSource 相关）

控制属性文件的加载、编码、缓存等行为。

1.2 区域解析配置（LocaleResolver 相关）

控制如何确定用户的区域（Locale）。

1.3 Cookie 持久化配置（仅 CookieLocaleResolver）

1.4 Session 持久化配置（仅 SessionLocaleResolver）

无独立配置项，依赖 Session 的默认行为。

1.5 其他高级配置

2. 完整配置示例（application.properties/yml）

2.1 properties 格式

# 消息源配置
spring.messages.basename=classpath:i18n/messages,classpath:i18n/overrides
spring.messages.encoding=UTF-8
spring.messages.cache-duration=3600s # 1小时热加载

# 区域配置
spring.mvc.locale=zh-CN
spring.mvc.fallback-locale=en
spring.http.accept-language.header=X-Language

# Cookie 持久化配置
spring.mvc.locale-resolver.cookie-name=MY_LOCALE
spring.mvc.locale-resolver.cookie-max-age=86400 # 1天

2.2 YAML 格式

spring:
  messages:
    basename: "classpath:i18n/messages,classpath:i18n/overrides"
    encoding: UTF-8
    cache-duration: 3600s
  mvc:
    locale: "zh-CN"
    fallback-locale: en
    locale-resolver:
      cookie-name: MY_LOCALE
      cookie-max-age: 86400
  http:
    accept-language:
      header: X-Language

3. 代码配置示例（Java 配置覆盖）

3.1 自定义 ReloadableResourceBundleMessageSource

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;

@Configuration
public class I18nConfig {
    @Bean
    public ReloadableResourceBundleMessageSource messageSource() {
        ReloadableResourceBundleMessageSource source = new ReloadableResourceBundleMessageSource();
        source.setBasenames("i18n/messages", "i18n/overrides"); // 支持多个前缀
        source.setDefaultEncoding("UTF-8");
        source.setCacheSeconds(60); // 覆盖配置项，60秒热加载
        return source;
    }
}

3.2 自定义 LocaleResolver（Cookie 持久化）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;

@Configuration
public class LocaleConfig {
    @Bean
    public CookieLocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver();
        resolver.setCookieName("CUSTOM_LOCALE"); // 覆盖配置项
        resolver.setCookieMaxAge(86400);         // 1天有效期
        resolver.setDefaultLocale(Locale.JAPAN); // 默认日语
        return resolver;
    }
}

4. 配置项总结表格

5. 常见问题解答

Q1：如何确保属性文件被正确加载？

• 检查路径：确保文件位于 src/main/resources/i18n/ 目录（或配置的路径）。
• 文件命名：格式为 <basename>_{language}.properties（如 messages_zh_CN.properties）。
• 日志调试：添加 logging.level.org.springframework.context.support=DEBUG 查看加载日志。

Q2：如何强制使用固定语言？

# application.properties
spring.mvc.locale=es # 强制西班牙语
spring.mvc.fallback-locale=es # 备用语言也设为西班牙语

Q3：如何同时支持 URL 参数切换语言？

结合 LocaleChangeInterceptor：

import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LocaleChangeInterceptor())
                .addPathPatterns("/**"); // 通过 ?lang=es 参数切换
    }
}

Q4：属性文件中的 {0} 占位符无效？

• 确保 spring.messages.always-use-message-format=true（默认值）。
• 示例消息：

  greeting=Hello, {0}!
  

Q5：如何避免 Cookie 跨域问题？

在 CookieLocaleResolver 中设置域：

resolver.setCookieDomain(".example.com"); // 设置域为整个域名

6. 最佳实践

• 多环境配置：通过 application-{profile}.properties 区分开发和生产环境的 cache-duration。
• 性能优化：生产环境禁用热加载（设为 0 可能影响性能）。
• 国际化测试：使用 Postman 或浏览器插件修改 Accept-Language 头测试不同语言。

总结

通过上述配置，可灵活控制 Spring Boot 国际化行为。核心是理解 MessageSource 和 LocaleResolver 的协作关系，结合业务需求选择合适的持久化策略（Cookie/Session）和文件加载方式。