Spring Boot + Thymeleaf 国际化配置与手动切换实战

Theo

发布时间：2026-10-15| 4人浏览过

原创

在 Web 开发中提供多语言支持是提升用户体验的关键环节。本文演示如何利用 Spring Boot 内置的国际化机制，配合 Thymeleaf 模板引擎，在登录页等前端界面上实现动态语言切换。重点涵盖配置文件创建、基础名设置、自定义区域解析器（LocaleResolver）实现手动切换逻辑，以及页面中的具体应用语法。

第1步：准备国际化资源文件

在项目类路径 resources 下新建 i18n 文件夹，用于集中管理多语言配置。根据需要创建的 key-value 对通常对应 UI 上的标签、提示语或按钮文本。

默认配置：login.properties（作为 fallback）。
中文配置：login_zh_CN.properties。
英文配置：login_en_US.properties。

以下是示例内容结构：

# login.properties && login_zh_CN.properties
login.tip=请登录
login.username=用户名
login.password=密码
login.rememberme=记住我
login.button=登录

# login_en_US.properties
login.tip=Please sign in
login.username=Username
login.password=Password
login.rememberme=Remember me
login.button=Login

Spring Boot 默认扫描 messages.properties，由于我们将前缀定制为 login 并放在 i18n 目录下，后续需在主配置文件中指定基础名称。

第2步：配置全局属性

修改项目的 application.properties，指定国际化文件的基础路径和前缀名。格式要求为：i18n.前缀名。

spring.messages.basename=i18n.login

该配置确保框架在遇到 #{...} 表达式时，能正确到 i18n/login.properties 及其语言变体中查找对应的值。

第3步：编写自定义区域解析器

为了实现手动切换语言的功能（例如通过 URL 携带参数），需要覆盖默认的 `Accept-Language` 解析逻辑。创建一个配置类实现 LocaleResolver 接口。

package com.lagou.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.LocaleResolver;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Locale;
@Configuration
public class MyLocalResolver implements LocaleResolver {
    @Override
    public Locale resolveLocale(HttpServletRequest request) {
        // 1. 尝试获取手动切换参数 l (如 zh_CN 或 en_US)
        String l = request.getParameter("l");
        Locale locale = null;
        if (!StringUtils.isEmpty(l)) {
            // 使用下划线分割，匹配 .properties 文件名格式
            String[] s = l.split("_");
            locale = new Locale(s[0], s[1]);
        } else {
            // 2. 回退到浏览器 Accept-Language 头部自动解析
            String header = request.getHeader("Accept-Language");
            String[] split = header.split(",");
            if (split.length > 0) {
                String[] split1 = split[0].split("-");
                locale = new Locale(split1[0], split1[1]);
            }
        }
        return locale != null ? locale : Locale.getDefault();
    }
    @Override
    public void setLocale(HttpServletRequest request, HttpServletResponse response, Locale locale) {
        // 保持空实现，不强制写入 cookie/session
    }
    // 将该实例注册为 Bean，覆盖默认实现
    @Bean
    public LocaleResolver localeResolver() {
        return new MyLocalResolver();
    }
}

核心逻辑在于优先读取参数 l，其次读取请求头。注意 URL 参数通常使用下划线 _，而 HTTP 头通常使用短横线 -，代码中需分别处理。

第4步：在 Thymeleaf 页面中应用

打开 HTML 模板（如 login.html），引入命名空间并使用消息表达式绑定文本。

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>用户登录</title>
    <!-- 省略 CSS 引用 -->
</head>
<body class="text-center">
    <form class="form-signin">
        <img class="mb-4" th:src="@{/login/img/login.jpg}" width="72" height="72">
        
        <h1 th:text="#{login.tip}">请登录</h1>
        <input type="text" th:placeholder="#{login.username}" required autofocus>
        <input type="password" th:placeholder="#{login.password}" required>
        
        <div class="checkbox mb-3">
            <label>
                <input type="checkbox" value="remember-me">
                [[#{login.rememberme}]]
            </label>
        </div>
        
        <button class="btn btn-lg btn-primary btn-block" type="submit" th:text="#{login.button}">登录</button>
        
        <!-- 手动切换语言的链接 -->
        <a class="btn btn-sm" th:href="@{/toLoginPage(l='zh_CN')}">中文</a>
        <a class="btn btn-sm" th:href="@{/toLoginPage(l='en_US')}">English</a>
    </form>
</body>
</html>

关键点说明：