Spring Boot3整合Thymeleaf Session国际化切换后本地化文本不显示

开发者阿泽

2026-8-29

问题根因

三个配置错误叠加导致故障：

语言参数值写错：日语的ISO 639标准语言代码是ja，你写的jp是国家/地区代码，传lang=jp根本无法解析出正确的日语Locale
参数和资源文件命名不匹配：你切换语言时传的是不带地区信息的短语言码（en、fr、jp），但现有资源文件全是带地区后缀的命名格式（messages_en_US.properties、messages_fr_FR.properties、messages_ja_JP.properties），没有对应短码的资源文件。首次访问能正常显示，是因为浏览器自动传的Accept-Language请求头带完整的「语言-地区」标识（比如en-US、fr-FR），刚好能匹配到现有文件；一旦手动切换传短码，Spring找不到对应资源，再加上你关了系统Locale回退逻辑、默认messages文件是空的，自然读不到对应文本
SessionLocaleResolver没有配置默认Locale，缺少异常场景下的兜底值

修复步骤

按顺序改完就能正常用：

修正语言切换参数，两种方案二选一即可：
- 方案一（省事不用加文件）：直接改Thymeleaf模板里的切换链接，传完整的「语言-地区」标识，和现有资源文件名对应：
```
<li><a class="dropdown-item" th:href="@{''(lang=en_US)}">English</a></li>
<li><a class="dropdown-item" th:href="@{''(lang=fr_FR)}">Français</a></li>
<li><a class="dropdown-item" th:href="@{''(lang=ja_JP)}">日本語</a></li>
```
- 方案二（保留短参数写法）：补三个不带地区后缀的资源文件，内容和对应带后缀的文件保持一致，同时把日语参数从jp改成ja：
  - 新增i18n/messages_en.properties，内容和messages_en_US.properties一致
  - 新增i18n/messages_fr.properties，内容和messages_fr_FR.properties一致
  - 新增i18n/messages_ja.properties，内容和messages_ja_JP.properties一致

放开LocalizationConfiguration类里被注释的默认Locale配置，给会话级解析器加兜底值：

@Bean
public LocaleResolver localeResolver() {
    SessionLocaleResolver localeResolver = new SessionLocaleResolver();
    localeResolver.setDefaultLocale(Locale.US); // 取消这行注释
    return localeResolver;
}

不要留空默认的i18n/messages.properties文件，把英文文案填进去当全局兜底，避免Locale解析异常时页面出现空白占位
（可选优化）把application.properties里的spring.messages.always-use-message-format=true改为false，你当前的资源文件没有{0}这类MessageFormat占位符，开启这个配置反而可能触发不必要的格式解析问题。

改完重启项目，手动切换语言时就能正常加载对应国际化文案了。

内容的提问来源于stack exchange，提问作者Theo Huwume