Spring Boot 3 国际化(i18n)全流程实战指南

一、基础配置

1.1 依赖配置

<!-- pom.xml 确保包含web starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

1.2 配置文件结构

resources/
├── i18n/
│   ├── messages.properties      # 默认语言
│   ├── messages_en.properties   # 英文
│   ├── messages_zh.properties   # 中文
│   └── messages_ja.properties   # 日文

二、消息文件示例

2.1 内容格式

# messages.properties
welcome.message=Welcome!
user.greeting=Hello, {0}!

# messages_zh.properties
welcome.message=欢迎！
user.greeting=你好，{0}！

2.2 参数化消息

// 使用MessageSource获取带参数的消息
String greeting = messageSource.getMessage("user.greeting", 
    new Object[]{"张三"}, 
    LocaleContextHolder.getLocale());

三、核心配置类

3.1 自动配置原理

classDiagram
    class MessageSourceAutoConfiguration {
        +messageSource()
    }
    class MessageSourceProperties {
        +basename
        +encoding
    }
    MessageSourceAutoConfiguration --> MessageSourceProperties

3.2 自定义配置

@Configuration
public class I18nConfig {

    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver slr = new SessionLocaleResolver();
        slr.setDefaultLocale(Locale.US); // 默认英文
        return slr;
    }

    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
        lci.setParamName("lang"); // 切换语言的参数名
        return lci;
    }
}

四、语言切换实现

4.1 拦截器注册

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

4.2 前端切换示例

<!-- Thymeleaf模板示例 -->
<div class="language-switcher">
    <a href="?lang=en">English</a> | 
    <a href="?lang=zh">中文</a> |
    <a href="?lang=ja">日本語</a>
</div>

五、Thymeleaf集成

5.1 模板中使用

<h1 th:text="#{welcome.message}"></h1>
<p th:text="#{user.greeting(${user.name})}"></p>

5.2 日期数字格式化

<p th:text="${#dates.format(date, 'yyyy-MM-dd')}"></p>
<p th:text="${#numbers.formatDecimal(price, 1, 2)}"></p>

六、Restful API支持

6.1 控制器示例

@RestController
@RequestMapping("/api")
public class GreetingController {

    @GetMapping("/greet")
    public String greet(@RequestParam String name) {
        return messageSource.getMessage(
            "user.greeting", 
            new Object[]{name}, 
            LocaleContextHolder.getLocale()
        );
    }
}

6.2 请求头控制语言

# 使用Accept-Language头
curl -H "Accept-Language: zh-CN" http://localhost:8080/api/greet?name=李四

七、验证与测试

7.1 测试用例

@SpringBootTest
class I18nTest {

    @Autowired
    private MessageSource messageSource;

    @Test
    void testChineseMessage() {
        String msg = messageSource.getMessage(
            "welcome.message", 
            null, 
            Locale.CHINA
        );
        assertEquals("欢迎！", msg);
    }
}

7.2 Postman测试方案

测试场景	请求参数	预期响应
默认语言	无lang参数	“Welcome!”
中文请求	?lang=zh	“欢迎！”
带参数消息	?lang=zh&name=王五	“你好，王五！”

八、高级功能扩展

8.1 数据库存储方案

@Entity
public class MessageResource {
    @Id
    private String code;
    private String en;
    private String zh;
    private String ja;
    // getters/setters
}

@Repository
public interface MessageRepo extends JpaRepository<MessageResource, String> {
}

8.2 动态消息源

public class DatabaseMessageSource extends AbstractMessageSource {
    
    @Autowired
    private MessageRepo messageRepo;

    @Override
    protected MessageFormat resolveCode(String code, Locale locale) {
        MessageResource msg = messageRepo.findById(code).orElse(null);
        if (msg != null) {
            String text = getTextForLocale(msg, locale);
            return new MessageFormat(text, locale);
        }
        return null;
    }
    // 其他必要方法实现...
}

九、性能优化

9.1 消息缓存配置

# application.properties
spring.messages.cache-duration=1h
spring.messages.use-code-as-default-message=true

9.2 预加载策略

@PostConstruct
public void preloadMessages() {
    log.info("预加载消息...");
    Arrays.asList("en", "zh", "ja").forEach(locale -> {
        messageSource.getMessage("welcome.message", null, new Locale(locale));
    });
}

十、异常处理

10.1 缺失消息处理

@Bean
public MessageSource messageSource() {
    ReloadableResourceBundleMessageSource ms = new ReloadableResourceBundleMessageSource();
    ms.setBasenames("classpath:i18n/messages");
    ms.setDefaultEncoding("UTF-8");
    ms.setUseCodeAsDefaultMessage(true); // 无对应locale时使用code
    return ms;
}

10.2 统一错误消息

# messages.properties
error.not_found=Resource not found
error.unauthorized=Access denied

# messages_zh.properties
error.not_found=资源不存在
error.unauthorized=访问被拒绝

完整示例项目结构

src/
├── main/
│   ├── java/
│   │   └── com/example/i18n/
│   │       ├── config/
│   │       │   └── I18nConfig.java
│   │       ├── controller/
│   │       │   └── GreetingController.java
│   │       └── I18nApplication.java
│   └── resources/
│       ├── i18n/
│       │   ├── messages.properties
│       │   ├── messages_en.properties
│       │   └── messages_zh.properties
│       └── templates/
│           └── index.html

关键实践建议：