发布于 由admin

JAVA REST API 如何实现国际化响应？Spring i18n 配置详解

Java REST API 国际化响应：Spring i18n 配置详解

大家好，今天我们要深入探讨如何在 Java REST API 中实现国际化（i18n）响应，并详细解析 Spring Framework 提供的 i18n 支持。国际化是软件开发中的一项重要技术，它允许应用程序根据用户的语言和区域设置提供定制的内容，从而提升用户体验。在 REST API 的上下文中，国际化意味着 API 响应应该根据客户端的 Accept-Language 请求头或其他约定的机制来返回不同语言的文本消息。

1. 国际化需求分析

在开始编码之前，我们需要明确国际化的具体需求。这包括：

  • 支持的语言种类： 确定 API 需要支持哪些语言（例如，英语、中文、法语等）。
  • 可翻译的内容： 识别哪些文本消息需要翻译（例如，错误消息、提示信息、标签等）。
  • 语言环境确定机制： 确定如何确定客户端的语言环境（例如，Accept-Language 请求头、URL 参数、Cookie 等）。
  • 翻译存储方式： 选择合适的存储方式来保存翻译后的文本（例如，属性文件、数据库、YAML 文件等）。

2. Spring i18n 核心组件

Spring Framework 提供了强大的 i18n 支持，主要依赖于以下组件：

  • Locale: 代表一个特定的地理、政治或文化区域。它用于标识用户的语言和区域设置。
  • MessageSource: 接口，用于解析消息文本。Spring 提供了多种 MessageSource 的实现，最常用的是 ResourceBundleMessageSource，它从属性文件中加载翻译后的文本。
  • LocaleResolver: 接口，用于确定当前请求的 Locale。Spring 提供了多种 LocaleResolver 的实现，例如 AcceptHeaderLocaleResolver (基于 Accept-Language 头)，CookieLocaleResolver (基于 Cookie)，SessionLocaleResolver (基于 Session)。
  • LocaleContextHolder: 一个线程安全的类，用于存储当前线程的 Locale。

3. Spring i18n 配置步骤

下面是一个典型的 Spring i18n 配置步骤：

3.1 添加依赖

首先，确保你的项目中包含了 Spring Web 的依赖。如果你使用 Maven，可以在 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

3.2 配置 MessageSource

在 Spring 配置文件（例如，application.properties 或 application.yml）中，配置 MessageSource：

# application.properties
spring.messages.basename=messages
spring.messages.encoding=UTF-8

或者，使用 YAML 格式：

# application.yml
spring:
  messages:
    basename: messages
    encoding: UTF-8

spring.messages.basename 指定了消息属性文件的基本名称。Spring 会根据请求的 Locale 自动查找相应的属性文件。例如，如果 basename 设置为 messages，并且请求的 Locale 为 en_US，Spring 将会查找 messages_en_US.properties 文件。

3.3 创建消息属性文件

在 src/main/resources 目录下，创建消息属性文件。文件名应遵循 basename_language_country.properties 的格式。

  • messages.properties (默认语言，例如英语):

    greeting.message=Hello, world!
error.invalid.input=Invalid input.

  • messages_zh_CN.properties (简体中文):

    greeting.message=你好，世界！
error.invalid.input=无效的输入。

  • messages_fr_FR.properties (法语):

    greeting.message=Bonjour le monde!
error.invalid.input=Entrée invalide.

注意： 对于非 ASCII 字符，需要使用 Unicode 转义序列。可以使用工具将文本转换为 Unicode 编码。

3.4 配置 LocaleResolver

配置 LocaleResolver 来确定当前请求的 Locale。最常用的两种方式是使用 AcceptHeaderLocaleResolver 和 CookieLocaleResolver。

  • AcceptHeaderLocaleResolver: 根据 Accept-Language 请求头确定 Locale。这是最简单的方式，但客户端可能没有设置 Accept-Language 头，或者设置的值不正确。

    @Configuration
public class LocaleConfig {

    @Bean
    public LocaleResolver localeResolver() {
        AcceptHeaderLocaleResolver resolver = new AcceptHeaderLocaleResolver();
        resolver.setDefaultLocale(Locale.US); // 设置默认 Locale
        return resolver;
    }
}

  • CookieLocaleResolver: 从 Cookie 中读取 Locale。这种方式允许用户手动选择语言，并将选择存储在 Cookie 中。

    @Configuration
public class LocaleConfig {

    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver();
        resolver.setDefaultLocale(Locale.US); // 设置默认 Locale
        resolver.setCookieName("language"); // 设置 Cookie 名称
        resolver.setCookieMaxAge(3600); // 设置 Cookie 过期时间 (秒)
        return resolver;
    }
}

3.5 在 Controller 中使用 MessageSource

在 Controller 中，可以使用 MessageSource 来解析消息文本。可以通过依赖注入的方式获取 MessageSource 实例。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

import java.util.Locale;

@RestController
public class GreetingController {

    @Autowired
    private MessageSource messageSource;

    @GetMapping("/greeting")
    public ResponseEntity<String> greeting(@RequestHeader(name = "Accept-Language", required = false) String locale) {
        Locale currentLocale = Locale.US; // Default to US if Accept-Language is not provided.
        if (locale != null && !locale.isEmpty()) {
          String[] localeParts = locale.split("-");
          if(localeParts.length > 1){
            currentLocale = new Locale(localeParts[0],localeParts[1]);
          } else {
            currentLocale = new Locale(localeParts[0]);
          }

        }
        String message = messageSource.getMessage("greeting.message", null, currentLocale);
        return ResponseEntity.ok(message);
    }

    @GetMapping("/error")
    public ResponseEntity<String> error() {
        String message = messageSource.getMessage("error.invalid.input", null, LocaleContextHolder.getLocale());
        return ResponseEntity.badRequest().body(message);
    }
}

代码解释:

  • @Autowired private MessageSource messageSource;: 注入 MessageSource 实例。
  • @GetMapping("/greeting"): 定义一个处理 /greeting 请求的 GET 方法。
  • @RequestHeader(name = "Accept-Language", required = false) String locale: 获取 Accept-Language 请求头的值。
  • messageSource.getMessage("greeting.message", null, locale): 使用 MessageSource 解析消息文本。
    • "greeting.message": 消息的键。
    • null: 消息的参数 (如果有)。
    • locale: 当前的 Locale。
  • LocaleContextHolder.getLocale(): 获取当前线程的 Locale。 通常由 LocaleResolver 设置。

3.6 使用 LocaleContextHolder

LocaleContextHolder 提供了一种方便的方式来访问当前线程的 Locale。在大多数情况下，LocaleResolver 会自动将 Locale 设置到 LocaleContextHolder 中。

3.7 测试

启动应用程序，并使用不同的 Accept-Language 请求头发送请求。例如：

  • curl -H "Accept-Language: en-US" http://localhost:8080/greeting
  • curl -H "Accept-Language: zh-CN" http://localhost:8080/greeting
  • curl -H "Accept-Language: fr-FR" http://localhost:8080/greeting

你应该看到根据 Accept-Language 头返回的不同语言的问候语。

4. 高级配置

4.1 动态切换 Locale

除了使用 AcceptHeaderLocaleResolver 和 CookieLocaleResolver 之外，还可以提供一个 API 允许用户动态切换 Locale。这可以通过设置 LocaleContextHolder 的值来实现。

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Locale;

@RestController
public class LocaleController {

    private final CookieLocaleResolver localeResolver;

    public LocaleController(CookieLocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    @PostMapping("/locale")
    public String setLocale(@RequestParam("lang") String lang, HttpServletRequest request, HttpServletResponse response) {
        Locale newLocale = new Locale(lang);
        localeResolver.setLocale(request, response, newLocale);
        return "Locale changed to " + lang;
    }
}

代码解释:

  • @PostMapping("/locale"): 定义一个处理 /locale 请求的 POST 方法。
  • @RequestParam("lang") String lang: 获取 lang 请求参数的值，该参数指定了新的语言代码。
  • localeResolver.setLocale(request, response, newLocale): 使用 CookieLocaleResolver 设置新的 Locale。这会将 Locale 存储在 Cookie 中。

4.2 使用数据库存储翻译

虽然属性文件是一种简单的方式来存储翻译，但对于大型应用程序，使用数据库可能更合适。Spring 支持自定义 MessageSource，可以使用数据库来存储翻译。

首先，创建一个数据库表来存储翻译：

CREATE TABLE translations (
    id INT PRIMARY KEY AUTO_INCREMENT,
    message_key VARCHAR(255) NOT NULL,
    locale VARCHAR(10) NOT NULL,
    message TEXT NOT NULL
);

然后，创建一个自定义的 MessageSource 实现：

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.context.NoSuchMessageException;
import org.springframework.jdbc.core.JdbcTemplate;

import java.util.Locale;

public class DatabaseMessageSource implements MessageSource {

    private final JdbcTemplate jdbcTemplate;

    public DatabaseMessageSource(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    @Override
    public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
        try {
            return getMessage(code, args, locale);
        } catch (NoSuchMessageException e) {
            return defaultMessage;
        }
    }

    @Override
    public String getMessage(String code, Object[] args, Locale locale) throws NoSuchMessageException {
        String sql = "SELECT message FROM translations WHERE message_key = ? AND locale = ?";
        try {
            String message = jdbcTemplate.queryForObject(sql, String.class, code, locale.toString());
            if (args != null && args.length > 0) {
                return String.format(message, args);
            }
            return message;
        } catch (Exception e) {
            throw new NoSuchMessageException(code, locale);
        }
    }

    @Override
    public String getMessage(MessageSourceResolvable resolvable, Locale locale) throws NoSuchMessageException {
        return getMessage(resolvable.getCode(), resolvable.getArguments(), locale);
    }
}

最后，配置自定义的 MessageSource：

import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;

import javax.sql.DataSource;

@Configuration
public class MessageSourceConfig {

    @Bean
    public JdbcTemplate jdbcTemplate(DataSource dataSource) {
        return new JdbcTemplate(dataSource);
    }

    @Bean
    public MessageSource messageSource(JdbcTemplate jdbcTemplate) {
        return new DatabaseMessageSource(jdbcTemplate);
    }
}

4.3 国际化验证消息

Spring Validation 框架也支持国际化。可以使用 MessageSource 来解析验证消息。

首先，在消息属性文件中定义验证消息：

# messages.properties
javax.validation.constraints.NotEmpty.message=This field cannot be empty.

# messages_zh_CN.properties
javax.validation.constraints.NotEmpty.message=此字段不能为空。

然后，在实体类中使用验证注解：

import javax.validation.constraints.NotEmpty;

public class User {

    @NotEmpty
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

最后，在 Controller 中使用 @Valid 注解来触发验证：

import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;

@RestController
@Validated
public class UserController {

    @PostMapping("/users")
    public ResponseEntity<String> createUser(@Valid @RequestBody User user) {
        // ...
        return ResponseEntity.ok("User created");
    }
}

Spring Validation 框架会自动使用 MessageSource 来解析验证消息。

5. 最佳实践

  • 使用清晰的消息键： 为每个消息定义一个清晰且具有描述性的键。
  • 提供默认消息： 为每种语言提供默认消息，以防止找不到翻译时出现问题。
  • 使用参数化消息： 使用参数化消息来支持动态内容。例如，"error.invalid.length=The length must be between {0} and {1}."。
  • 避免硬编码文本： 避免在代码中硬编码文本。始终使用 MessageSource 来解析消息。
  • 定期审查翻译： 定期审查翻译，以确保其准确性和一致性。
  • 考虑使用翻译管理平台： 对于大型应用程序，考虑使用翻译管理平台来简化翻译流程。

6. 示例代码结构

以下是一个示例项目的代码结构：

src/main/java
├── com
│   └── example
│       ├── config
│       │   └── LocaleConfig.java
│       ├── controller
│       │   ├── GreetingController.java
│       │   └── LocaleController.java
│       └── model
│           └── User.java
└── resources
    ├── application.properties (或 application.yml)
    ├── messages.properties
    ├── messages_zh_CN.properties
    └── messages_fr_FR.properties

7. 总结概括

本文深入探讨了如何在 Java REST API 中实现国际化响应，并详细解析了 Spring Framework 提供的 i18n 支持。通过配置 MessageSource 和 LocaleResolver，可以轻松地根据客户端的语言环境提供定制的 API 响应。理解并应用这些概念和最佳实践将有助于构建更具全球化和用户友好的应用程序。

8. 扩展思考

国际化的实现不仅仅局限于文本消息的翻译。还可以考虑国际化日期、时间、货币等数据的格式。 Spring 提供了 FormattingConversionService 可以用于格式化和解析日期、时间、数字等。 此外，还应该关注字符编码问题，确保应用程序能够正确处理各种字符集。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注