---

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