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-8cache-duration: 3600smvc:locale: "zh-CN"fallback-locale: enlocale-resolver:cookie-name: MY_LOCALEcookie-max-age: 86400http: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 {@Beanpublic 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 {@Beanpublic 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 {@Overridepublic 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）和文件加载方式。
