SpringBoot 国际化 i18n 实战：配置文件与动态切换方案

2.1.2 目录结构

在 resources 目录下创建 i18n 文件夹，用于存放多语言配置文件，最终目录结构：

resources/
├── application.yml          # 核心配置
└── i18n/                    # 国际化配置文件目录
    ├── messages.properties       # 默认配置（无语言标识）
    ├── messages_zh_CN.properties # 简体中文
    ├── messages_zh_TW.properties # 繁体中文
    └── messages_en_US.properties # 英文

2.2 多语言配置文件编写

2.2.1 命名规则

配置文件命名必须遵循 basename_语言代码_国家代码.properties 规则：

• basename：自定义前缀（如 messages），需在 application.yml 中配置。
• 无语言标识的 messages.properties 为默认配置，当匹配不到指定 Locale 的配置时，会使用该文件内容。

2.2.2 配置文件内容

1. 默认配置（messages.properties）：兜底使用，建议与默认语言（简体中文）保持一致

# 通用提示
common.submit=提交
common.cancel=取消
# 用户相关
user.name=用户名
user.age=年龄
# 校验提示
validate.required.id=主键不能为空
validate.required.name=姓名不能为空

2. 简体中文（messages_zh_CN.properties）：

# 通用提示
common.submit=提交
common.cancel=取消
# 用户相关
user.name=用户名
user.age=年龄
# 校验提示
validate.required.id=主键不能为空
validate.required.name=姓名不能为空

3. 繁体中文（messages_zh_TW.properties）：

# 通用提示
common.submit=提交
common.cancel=取消
# 用户相关
user.name=使用者名稱
user.age=年齡
# 校验提示
validate.required.id=主鍵不能為空
validate.required.name=姓名不能為空

4. 英文（messages_en_US.properties）：

# 通用提示
common.submit=Submit
common.cancel=Cancel
# 用户相关
user.name=Username
user.age=Age
# 校验提示
validate.required.id=Primary key cannot be empty
validate.required.name=Name cannot be empty

注意：properties 文件默认编码为 ISO-8859-1，直接写中文会乱码！需将 IDE 的 properties 文件编码设置为 UTF-8（IDEA：Settings → File Encodings → Properties Files → 勾选 Transparent native-to-ascii conversion）。

2.3 SpringBoot 核心配置

在 application.yml 中配置国际化相关参数，指定配置文件路径、默认语言、编码等：

spring:
  # 国际化配置
  messages:
    basename: i18n/messages      # 配置文件路径（无需写.properties 后缀）
    encoding: UTF-8              # 解决中文乱码
    fallback-to-system-locale: false  # 禁用系统语言回退
    default-locale: zh_CN        # 默认语言：简体中文
    cache-duration: 3600s        # 配置文件缓存时间（生产建议设置）
  # Web 配置（可选，用于请求参数解析）
  web:
    locale: zh_CN

2.4 自定义语言解析器与拦截器

默认情况下，SpringBoot 仅支持从请求头 Accept-Language 获取 Locale，为了方便通过请求参数（如 ?Accept-Language=en-US）切换语言，需自定义 LocaleResolver 并注册拦截器。

2.4.1 自定义 LocaleResolver

创建 config/I18nConfig.java，实现 LocaleResolver 接口：

package com.example.i18n.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.SessionLocaleResolver;
import org.springframework.web.servlet.handler.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Locale;

/**
 * 国际化核心配置类（修改为 Header 拦截语言）
 */
@Configuration
public class I18nConfig implements WebMvcConfigurer {

    /**
     * 注册自定义 LocaleResolver（基于 Session 存储 Locale）
     * 替代默认的 AcceptHeaderLocaleResolver
     */
    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver resolver = new SessionLocaleResolver();
        // 设置默认语言：简体中文（与 application.yml 中保持一致）
        resolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE);
        return resolver;
    }

    /**
     * 自定义拦截器：从 Accept-Language Header 解析并设置 Locale
     */
    @Bean
    public HandlerInterceptor localeHeaderInterceptor(LocaleResolver localeResolver) {
        return new HandlerInterceptor() {
            @Override
            public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
                // 1. 从请求头中获取语言标识（自定义 Header 名：Accept-Language，可根据需求修改）
                String acceptLanguage = request.getHeader("Accept-Language");
                // 2. 设置默认语言为空或者抛异常使用 Locale locale = Locale.SIMPLIFIED_CHINESE; // 默认语言// 默认：zh_CN
                Locale locale = Locale.SIMPLIFIED_CHINESE;
                // 3. 若 Header 中有值，则解析并设置 Accept-Language；无值则使用默认 Accept-Language
                if (acceptLanguage != null && !acceptLanguage.isEmpty()) {
                    try {
                        // 取第一个语言项（如 "zh-CN,en;q=0.8" → "zh-CN"）
                        String primary = acceptLanguage.split(",")[0].trim();
                        // Spring 工具类能正确解析 "zh-CN"、"en" 等格式
                        locale = StringUtils.parseLocale(primary);
                    } catch (Exception e) {
                        // 解析失败则使用默认语言，不抛异常
                    }
                }
                // 使用容器中真实的 LocaleResolver 实例设置 Locale（存入 Session）
                localeResolver.setLocale(request, response, locale);
                return true;
            }
        };
    }

    /**
     * 注册拦截器到 Spring MVC 拦截器链
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeHeaderInterceptor(localeResolver()))
                .addPathPatterns("/**")
                .order(0); // 优先级最高
    }
}

关键说明：

• SessionLocaleResolver：将 Locale 存储在 Session 中，一次切换后，后续请求无需重复传参。
• localeHeaderInterceptor：拦截请求头 Header 中 Accept-Language 参数，自动更新当前 Locale（如 Accept-Language=zh-TW 会切换为繁体中文）。

2.5 国际化消息使用示例

2.5.1 工具类封装（推荐）

创建 utils/I18nUtils.java，封装获取国际化消息的方法，简化业务使用：

package com.example.i18n.utils;

import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;
import javax.annotation.Resource;
import java.util.Locale;

/**
 * 国际化工具类
 */
@Component
public class I18nUtils {

    @Resource
    private MessageSource messageSource;

    /**
     * 获取国际化消息（使用当前 Locale）
     * @param key 消息键
     * @return 消息值
     */
    public String getMessage(String key) {
        return getMessage(key, null, LocaleContextHolder.getLocale());
    }

    /**
     * 获取国际化消息（带参数）
     * @param key 消息键
     * @param args 参数数组（如消息为"你好{0}"，args=new Object[]{"张三"}）
     * @return 消息值
     */
    public String getMessage(String key, Object[] args) {
        return getMessage(key, args, LocaleContextHolder.getLocale());
    }

    /**
     * 手动指定 Locale 获取消息
     * @param key 消息键
     * @param args 参数数组
     * @param locale 语言标识
     * @return 消息值
     */
    public String getMessage(String key, Object[] args, Locale locale) {
        try {
            // 从 MessageSource 中获取消息，若未找到则返回 key 本身
            return messageSource.getMessage(key, args, locale);
        } catch (Exception e) {
            return key;
        }
    }
}

核心 API 说明：

• LocaleContextHolder.getLocale()：获取当前线程的 Locale（由 LocaleResolver 解析）。
• messageSource.getMessage(key, args, locale)：核心方法，参数说明：
  • key：消息键（如 user.name）。
  • args：消息参数（用于替换消息中的占位符，如 user.hello=你好{0}）。
  • locale：指定语言标识。

2.5.2 控制器使用示例

创建 controller/I18nController.java，编写接口测试国际化效果：

package com.example.i18n.controller;

import com.example.i18n.utils.I18nUtils;
import org.springframework.web.bind.annotation.