Spring Boot 国际化配置项详解

---

Spring Boot 国际化配置项详解

---

1. 核心配置项分类

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

---

1.1 消息源配置（MessageSource 相关）

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

配置项	作用	默认值	示例	说明
spring.messages.basename	指定属性文件的路径前缀（不包含语言后缀）	messages	classpath:i18n/messages	支持多路径用逗号分隔，如 messages,custom
spring.messages.encoding	属性文件的编码格式	UTF-8	GBK	避免中文乱码需显式指定
spring.messages.cache-duration	属性文件缓存时间（仅 ReloadableResourceBundleMessageSource 有效）	7200s（2小时）	60s 或 PT1M（ISO 8601格式）	设置为 0 禁用缓存，实现热加载

---

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

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

配置项	作用	默认值	示例	说明
spring.mvc.locale	默认区域（当无法自动检测时使用）	由系统 Locale 决定	es（西班牙语）	直接指定语言代码（如 zh-CN）
spring.mvc.fallback-locale	备用区域（当主区域无效时使用）	en	zh	支持多个值，用逗号分隔
spring.http.accept-language.header	自定义语言检测的请求头名称	Accept-Language	X-Language	例如从自定义头读取语言

---

1.3 Cookie 持久化配置（仅 CookieLocaleResolver）

配置项	作用	默认值	示例	说明
spring.mvc.locale-resolver.cookie-name	Cookie 名称	LOCALE	lang	自定义 Cookie 名称
spring.mvc.locale-resolver.cookie-max-age	Cookie 有效期（秒）	1440（24分钟）	3600（1小时）	设置为 -1 表示会话级，0 删除 Cookie

---

1.4 Session 持久化配置（仅 SessionLocaleResolver）

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

---

1.5 其他高级配置

配置项	作用	默认值	示例	说明
spring.messages.always-use-message-format	是否强制使用 MessageFormat 解析消息（支持 {0} 占位符）	true	false	关闭后仅支持简单键值对，性能更高
spring.messages.use-code-as-default-message	当消息未找到时，是否返回原始键（如 error.login）	false	true	开启后避免因消息缺失导致空值

---

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. 配置项总结表格

配置类型	配置项	作用	默认值	适用场景
消息源	spring.messages.basename	属性文件路径	messages	自定义多语言文件路径
消息源	spring.messages.encoding	文件编码	UTF-8	解决乱码问题
消息源	spring.messages.cache-duration	热加载间隔	7200s	开发环境快速调试
区域	spring.mvc.locale	默认语言	系统默认	设置全局默认语言
区域	spring.http.accept-language.header	自定义语言头	Accept-Language	适配非标准请求头
Cookie	spring.mvc.locale-resolver.cookie-name	Cookie 名称	LOCALE	避免与其他应用冲突
Session	无独立配置项	依赖 Session	——	会话内语言切换

---

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）和文件加载方式。