Skip to content

5. 国际化

国际化应用程序以用户的语言显示其文本。案例研究提供法语和英语两种语言。原理很简单:视图不再包含文本,而是包含键 ([MENU.HOME]),并且每种语言都有一个字典 ,为每个键关联一段文本。所选语言存储在 Cookie 中。

[Spring] 有自己的翻译系统:[MessageSource] 接口,其标准实现读取诸如 [messages_fr.properties]、[messages_en.properties]…… 的文件。我们将保留这个接口,因为 [Spring] 和 [Thymeleaf] 都用它来进行翻译,但我们会自己实现它,使用一个读取 JSON 字典的小类:这些文件与案例研究的 [ASP.NET Core MVC] 和 [NestJS] 版本中的文件相同,其格式无需任何特殊工具即可读写。不过,我们会让 [Spring MVC] 来处理每个请求的语言选择:这是它的语言解析器 ([LocaleResolver])的职责,我们在示例 16 中已经遇到过它。

5.1. 示例 22:双语应用程序

22-i18n/
├── src/main/java/example22/
│   ├── config/
│   │   └── WebConfig.java
│   ├── controllers/
│   │   ├── LanguageController.java
│   │   └── PagesController.java
│   ├── translation/
│   │   ├── Formats.java
│   │   └── Translator.java
│   └── Example22Application.java
├── src/main/resources/
│   ├── i18n/
│   │   ├── en.json
│   │   └── fr.json
│   ├── static/css/
│   │   └── styles.css
│   ├── templates/
│   │   ├── fragments/
│   │   │   └── navbar.html
│   │   ├── pages/
│   │   │   ├── home.html
│   │   │   └── products.html
│   │   └── layout.html
│   └── application.properties
└── pom.xml

文件 [pom.xml] (启动器 [Thymeleaf])、[application.properties] (端口 5000)、[Example22Application.java] (启动类)和 [styles.css] 与之前的示例相同。

5.1.1. 字典

文件 [src/main/resources/i18n/fr.json]:

{
  "MENU": {
    "HOME": "Accueil",
    "PRODUCTS": "Produits"
  },
  "HOME": {
    "TITLE": "Bienvenue",
    "HELLO": "Bonjour {name} !",
    "DATE": "Nous sommes le {date}."
  },
  "PRODUCTS": {
    "TITLE": "Nos produits",
    "NAME": "Produit",
    "PRICE": "Prix",
    "COUNT": "{n} produit(s) au catalogue."
  }
}

文件 [src/main/resources/i18n/en.json]:

{
  "MENU": {
    "HOME": "Home",
    "PRODUCTS": "Products"
  },
  "HOME": {
    "TITLE": "Welcome",
    "HELLO": "Hello {name}!",
    "DATE": "Today is {date}."
  },
  "PRODUCTS": {
    "TITLE": "Our products",
    "NAME": "Product",
    "PRICE": "Price",
    "COUNT": "{n} product(s) in the catalogue."
  }
}
  • 字典是一个 JSON 文件,按页面或主题组织:键 [HOME.HELLO] 指的是 [HOME] 部分中的文本 [HELLO];
  • 第 8 行:文本可以包含用花括号括起来的参数,这些参数在翻译时被替换。不同语言的词序各不相同:这就是为什么文本不是通过简单地拼接已翻译的片段来生成的。

字典放在 [src/main/resources] 中:[Maven] 会将该文件夹连同编译后的类一起复制到 [target/classes] 中。因此它们属于类路径——即 [Java] 搜索应用程序的类和资源所在的文件夹和归档文件的集合:程序将在这里读取它们,而不论从哪个文件夹启动。

5.1.2. 翻译服务

[translation/Translator.java] 文件分为两部分。第一部分读取字典并进行翻译:

package example22.translation;

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;

// 翻译服务:JSON 字典,在启动时只读取一次。
// 它实现了 Spring 的 MessageSource 接口,并命名为 [messageSource]:
// 于是 Spring 将它用于所有翻译,Thymeleaf 将它用于视图中的
// #{...} 表达式。
@Component("messageSource")
public class Translator implements MessageSource {

    public static final List<String> LANGUAGES = List.of("fr", "en");
    public static final String DEFAULT_LANGUAGE = "en";

    // {name}:文本中的一个参数
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // 语言 ->(完整键 "HOME.HELLO" -> 文本)
    private final Map<String, Map<String, String>> dictionaries = new HashMap<>();

    public Translator() throws IOException {
        ObjectMapper json = new ObjectMapper();
        for (String language : LANGUAGES) {
            // 字典位于 src/main/resources/i18n 中,因此在类路径中
            try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
                Map<String, String> dictionary = new HashMap<>();
                flatten(json.readTree(stream), "", dictionary);
                dictionaries.put(language, dictionary);
            }
        }
    }

    // 与 [locale] 最接近的受支持语言:"fr_FR" -> "fr";"de" -> "en"
    public static String language(Locale locale) {
        String language = locale == null ? "" : locale.getLanguage();
        return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
    }

    // translate("HOME.HELLO", ["name", "Marie"], en) -> "Hello Marie!"
    // 参数以(名称, 值)对的形式传入。
    public String translate(String key, Object[] parameters, Locale locale) {
        if (key == null || key.isEmpty()) {
            return "";
        }
        // 缺失的键会显示键本身:疏漏在屏幕上一目了然
        String text = dictionaries.get(language(locale)).getOrDefault(key, key);
        if (parameters == null || parameters.length == 0) {
            return text;
        }
        Map<String, String> values = new HashMap<>();
        for (int i = 0; i + 1 < parameters.length; i += 2) {
            values.put(String.valueOf(parameters[i]), String.valueOf(parameters[i + 1]));
        }
        // 每个 {name} 都被同名参数的值所替换
        Matcher m = PARAMETER.matcher(text);
        return m.replaceAll(r -> Matcher.quoteReplacement(values.getOrDefault(r.group(1), r.group())));
    }

    // { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
    private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
        for (Map.Entry<String, JsonNode> property : node.properties()) {
            String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
            if (property.getValue().isObject()) {
                flatten(property.getValue(), key, result);
            } else {
                result.put(key, property.getValue().asString());
            }
        }
    }

我们来分析这段代码:

  • 第 24–25 行:该服务是一个 Bean(用 [@Component] 注解),因此是单例:文件只在启动时读取一次。它实现了 [MessageSource] 接口,该接口来自 [Spring] ,并按注解的指定命名为 [messageSource]。这个名称不是随意选择的:[Spring] 正是以这个名称查找应用程序的翻译服务。[Spring Boot]默认会创建一个(它会读取 [messages*.properties] 文件),但只要存在同名的 Bean,就不再创建;
  • 第 27–28 行:支持的语言和默认语言。[List.of] 创建一个只读列表;
  • 第 31 行:正则表达式 [\{(\w+)\}] (一个左花括号,一个或多个单词字符(被捕获),一个右花括号),用于识别文本中的参数。在 [Java] 字符串中,反斜杠写作 [\\]。[Pattern.compile] 一次性将其解析好;
  • 第 34 行:每种语言对应一个 [Java] 字典([Map]),将每个完整的键([HOME.HELLO])与其文本关联起来;
  • 第 36–46 行:构造函数读取 JSON 文件。[ClassPathResource] 引用类路径中的文件(见上文)。[try (...)] 语句(称为“try-with-resources”语句)会在代码块结束时自动关闭在其括号中打开的流,即使发生错误也是如此。来自 [ObjectMapper] 对象的 [Jackson] 库([Spring] 用于处理 JSON 的那个库)解析文本,并将其转换为 [JsonNode] 节点树;
  • 第 49–52 行:与任意给定语言最接近的受支持语言。[Locale] 对象属于 [Java] 类型,表示一种语言,可能还带有国家说明([fr]、[en_US]……);[getLanguage()] 提供其两个字母的代码。不受支持的语言([de])会返回默认语言;
  • 第 56–72 行:翻译。在所请求语言的字典中查找键;如果找不到,则显示键本身([getOrDefault]):遗漏的内容在屏幕上一目了然;
  • 第 65–68 行:参数存储在数组 [Object[]] 中,以(名称,值)对的形式:[["name", "Marie"]]。循环把它们整理成字典 [name -> value]。我们稍后会看到为什么选择这种有些不寻常的格式;
  • 第 70–71 行:[replaceAll] 将文本中找到的每个 [{name}] 参数替换为 lambda 的结果:即同名参数的值([r.group(1)] 是括号中捕获的部分),或者在没有值时保持原样的参数本身([r.group()] 是找到的整个文本)。[Matcher.quoteReplacement] 保护值中可能包含的 [$] 和 [\] 字符,否则它们对 [replaceAll] 具有特殊含义;
  • 第 75–84 行:该方法将 JSON“扁平化”:对象 ["HOME": { "HELLO": "..." }] 生成键 [HOME.HELLO]。它调用自身(递归方法)来遍历嵌套的对象。[properties()] 返回 JSON 对象的(名称,值)对;[asString()] 返回文本的值。

第二部分实现 [MessageSource] 接口:

    // —————————————————————————— MessageSource 接口

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

    @Override
    public String getMessage(String code, Object[] args, Locale locale) {
        return translate(code, args, locale);
    }

    // 由多个可能的代码描述的消息(验证错误):
    // 字典中出现的第一个代码优先
    @Override
    public String getMessage(MessageSourceResolvable message, Locale locale) {
        Map<String, String> dictionary = dictionaries.get(language(locale));
        String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
        for (String code : codes) {
            if (dictionary.containsKey(code)) {
                return translate(code, message.getArguments(), locale);
            }
        }
        String defaultText = message.getDefaultMessage();
        return defaultText != null ? defaultText : (codes.length > 0 ? codes[0] : "");
    }
}
  • 第 3–11 行:两个方法,将代码(键)及其参数翻译成指定的语言;它们调用 [translate]。注解 [@Override] 指示编译器验证确实重写了接口的方法;
  • 第 15–26 行:第三个方法接收一个 [MessageSourceResolvable] 对象,它用多个可能的代码来描述一条消息,从最具体的到最通用的。[Spring] 就是这样描述验证错误的(参见示例 19):约束 [@NotBlank] 作用于对象 [person] 的字段 [name] 会产生代码 [NotBlank.person.name], [NotBlank.name]、[NotBlank]……字典中存在的第一个代码优先;如果一个都不存在,则返回默认消息,或者第一个代码。案例研究利用这一点来翻译其错误消息。

在 [Spring] 中,消息参数的常用格式是按位置的:[Hello {0}!],其中第一个参数替换 [{0}]。我们更喜欢具名参数,它们在字典中更易读([Hello {name}!]),并且与案例研究其他版本中的参数一致。然而,[MessageSource] 接口只传递一个参数数组——因此才有了(名称,值)对的约定。

5.1.3. 在视图中翻译

在 [Thymeleaf] 视图中,表达式 [#{KEY}]——在示例 14 中已作过简单介绍——是将键 [KEY]翻译成请求语言的结果:[Thymeleaf] 调用 Bean [messageSource],也就是我们的 [Translator]。参数放在括号中传递:[#{HOME.HELLO('name', ${name})}] 会调用 [getMessage("HOME.HELLO", ["name", "Marie"], language)]。视图端无需编写任何类——这正是实现了 [Spring] 接口的好处。

剩下的是日期和金额,它们不需要翻译,而是要根据语言进行格式化。文件 [translation/Formats.java]:

package example22.translation;

import java.math.BigDecimal;
import java.text.NumberFormat;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Currency;

import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

// 日期和金额,按请求的语言格式化(参见示例 16)
@Component("formats")
public class Formats {

    // 以完整文字表示的日期
    public String longDate(LocalDate date) {
        return date.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(LocaleContextHolder.getLocale()));
    }

    // 以欧元表示的金额
    public String money(BigDecimal amount) {
        NumberFormat format = NumberFormat.getCurrencyInstance(LocaleContextHolder.getLocale());
        format.setCurrency(Currency.getInstance("EUR"));
        return format.format(amount);
    }
}

这大体上就是示例 16 中的那个类:

  • 第 14 行:一个名为 [formats] 的 Bean,视图以 [${@formats.longDate(...)}] 的形式引用它;
  • 第 19 行和第 24 行:[LocaleContextHolder.getLocale()] 指明当前请求的语言。我们稍后会看到是谁设置它的;
  • 第 19 行:长格式的日期([FormatStyle.FULL]),使用该语言;
  • 第 24–26 行:金额,采用该语言的货币格式,无论语言如何都以欧元表示。

5.1.4. 语言选择

文件 [config/WebConfig.java]:

package example22.config;

import java.time.Duration;
import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

// Spring MVC 的配置,已作补充
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // 各示例共享的 Bootstrap:examples/common/bootstrap 文件夹
    // 通过 URL /bootstrap/... 提供
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:":磁盘上的一个文件夹,相对于当前文件夹。尝试
                // 两次:从示例所在文件夹启动,或从 [examples] 启动
                .addResourceLocations("file:../common/bootstrap/", "file:common/bootstrap/");
    }

    // 每个请求的语言:取自 [language] Cookie,否则为英语。
    // 该 Bean 必须命名为 [localeResolver]:Spring 正是以这个名称查找它的。
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("language");
        resolver.setDefaultLocale(Locale.ENGLISH);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSameSite("Lax");
        return resolver;
    }
}

我们来分析这段代码:

  • 第 19–25 行:来自 [Bootstrap] 的文件,与之前的示例相同;
  • 第 29–37 行:Bean [localeResolver] (这是 [Spring MVC] 用来查找它的名称)为每个请求设置语言。在每个请求开始时,[Spring MVC] 向它询问语言,并在请求期间将其存储在 [LocaleContextHolder] 中:[Formats] 的方法、[#{...}] 表达式(来自 [Thymeleaf])以及视图中的 [#locale] 变量都从那里获取它;
  • 第 31 行:一个 [CookieLocaleResolver],由 [Spring] 提供,它从 Cookie 中读取语言,这里该 Cookie 名为 [language]。Cookie 中包含语言代码([en]);
  • 第 32 行:没有 Cookie 时,语言为英语。请注意,此时浏览器的语言(标头 [Accept-Language])会被忽略:用户通过 FR / EN 按钮选择语言;
  • 第 33–35 行:更改语言时 [CookieLocaleResolver] 所写入的 Cookie 的特性:一年的有效期;[HttpOnly] (页面上的 [JavaScript] 无法读取它);[SameSite=Lax] (来自其他站点的 POST 请求不会发送它)。

[controllers/LanguageController.java] 文件:

package example22.controllers;

import java.net.URI;
import java.util.Locale;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;

import example22.translation.Translator;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Controller
public class LanguageController {

    private final LocaleResolver localeResolver;

    public LanguageController(LocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    // GET /language/fr:将选择存入 Cookie,然后返回上一个页面
    @GetMapping("/language/{language}")
    public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
        if (!Translator.LANGUAGES.contains(language)) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // LocaleResolver 自己写入其 Cookie(名称、值、有效期等)
        localeResolver.setLocale(request, response, Locale.forLanguageTag(language));
        return "redirect:" + originPage(request);
    }

    // 我们来自的页面(Referer 头),只保留其路径:
    // 如果重定向到从请求中取得的完整地址,
    // 就可能把用户送到另一个站点(“开放重定向”漏洞)
    private static String originPage(HttpServletRequest request) {
        String referer = request.getHeader("Referer");
        try {
            URI url = URI.create(referer);
            String path = url.getRawPath();
            // "//site.com/..." 会被浏览器理解为另一个站点上的地址
            // :同样予以拒绝
            if (path == null || !path.startsWith("/") || path.startsWith("//")) {
                return "/";
            }
            return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
        } catch (RuntimeException e) {
            // 没有 Referer 头(NullPointerException),或地址无效
            return "/";
        }
    }
}

我们来分析这段代码:

  • 第 20–24 行:控制器通过依赖注入接收 [LocaleResolver] ;
  • 第 27–35 行:[GET /language/fr] 将所选语言存储在 Cookie 中,然后重定向到用户来源的页面。未知的语言会触发 404 错误([ResponseStatusException],参见示例 21);
  • 第 33 行:我们不自己创建 Cookie;而是请求 [LocaleResolver] 更改语言,由它按照 [WebConfig] 中指定的名称和特性写入 Cookie。[Locale.forLanguageTag("en")] 为英语创建 [Locale] 对象;
  • 第 34 行:[redirect:] 请求重定向(参见示例 04);
  • 第 40–55 行:原始页面由标头 [Referer] 指明,浏览器在点击链接时会添加该标头。我们只保留路径和参数([getRawPath]、[getRawQuery]:保持其在地址中出现的样子,不进行解码)。如果重定向到请求中的完整 URL,恶意网站就可以创建这样一个链接:经过我们的站点后,将用户送往该恶意网站(这种漏洞称为 [open redirect]);
  • 第 45–49 行:以两个斜杠开头的路径也会被拒绝:浏览器会把 [//pirate.example/trap] 解释为地址 [http://pirate.example/trap],即另一个站点;
  • 第 51–54 行:没有标头 [Referer] 时,[URI.create(null)] 会触发 [NullPointerException];地址无效时,会触发 [IllegalArgumentException]。两者都派生自 [RuntimeException]:这会让你回到主页。

5.1.5. 视图

文件 [templates/layout.html]:

<!doctype html>
<!--/* #locale:请求的语言;其两个字母的代码:#locale.language */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${#locale.language}" th:fragment="page(title, content)">
<head>
  <meta charset="utf-8">
  <!--/* 标题是一个键,由页面提供,由布局翻译 */-->
  <title th:text="#{${title}}">Title</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <main th:replace="${content}"></main>
  </div>
</body>
</html>
  • 第 3 行:模板(参见示例 15)是一个带有两个参数的片段:页面标题及其内容。页面的 [lang] 属性反映所选的语言(对屏幕阅读器和拼写检查器很有用):[#locale] 是请求的语言,而 [#locale.language] is 它的两个字母的代码;
  • 第 7 行:页面标题是一个键,由页面提供并由模板翻译:在 [#{${title}}] 中,键本身是一个表达式的结果;
  • 第 13 行:导航栏,来自另一个文件的片段。

文件 [templates/fragments/navbar.html]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar">
  <div class="navbar-nav me-auto">
    <!--/* #{KEY}:键的翻译,使用请求的语言 */-->
    <a class="nav-link" href="/" th:text="#{MENU.HOME}">Home</a>
    <a class="nav-link" href="/products" th:text="#{MENU.PRODUCTS}">Products</a>
  </div>
  <!--/* 当前语言高亮显示 */-->
  <div class="btn-group btn-group-sm" th:with="language=${#locale.language}">
    <a class="btn" th:classappend="${language == 'fr'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/fr">FR</a>
    <a class="btn" th:classappend="${language == 'en'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/en">EN</a>
  </div>
</nav>
  • 第 4–5 行:两段被翻译的文本。写在标签内的文本([Home])只有在直接用浏览器打开该文件时才会显示;[Thymeleaf] 会用翻译替换它;
  • 第 8 行:[th:with] 定义一个局部变量 [language],可在该标签及其子标签中使用;
  • 第 9–10 行:两个链接(更改语言不会修改任何应用程序数据:使用 GET 就足够了),当前语言会高亮显示:[th:classappend] 会在标签原有的 CSS 类之外再添加一个类。

文件 [templates/pages/home.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('HOME.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{HOME.TITLE}">Welcome</h1>
  <!--/* 参数:(参数名称, 值)这一对 */-->
  <p th:text="#{HOME.HELLO('name', ${name})}">Hello Marie!</p>
  <!--/* 日期先被格式化,然后作为 [date] 参数传入 */-->
  <p th:text="#{HOME.DATE('date', ${@formats.longDate(today)})}">Today is...</p>
</main>
</body>
</html>
  • 第 2 行:页面调用模板,使用键作为其标题和内容([main] 标签);
  • 第 7 行:一个参数,以(名称,值)对的形式传递;
  • 第 9 行:日期先由 [formats] Bean 格式化,然后作为 [date] 参数传递给消息。

[templates/pages/products.html] 文件:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('PRODUCTS.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{PRODUCTS.TITLE}">Our products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th th:text="#{PRODUCTS.NAME}">Product</th><th class="text-end" th:text="#{PRODUCTS.PRICE}">Price</th></tr></thead>
    <tbody>
      <tr th:each="product : ${products}">
        <td th:text="${product.name}">Keyboard</td>
        <td class="text-end" th:text="${@formats.money(product.price)}">€25.00</td>
      </tr>
    </tbody>
  </table>
  <p th:text="#{PRODUCTS.COUNT('n', ${#lists.size(products)})}">3 product(s) in the catalogue.</p>
</main>
</body>
</html>
  • 第 11 行:金额,根据语言进行格式化;
  • 第 15 行:数值参数:[#lists.size] 指明列表的大小;[Translator] 将该值转换为字符串([String.valueOf])。

文件 [controllers/PagesController.java]:

package example22.controllers;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

// 操作对语言一无所知:它们提供数据,
// 由视图进行翻译和格式化
@Controller
public class PagesController {

    public record Product(String name, BigDecimal price) {
    }

    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("name", "Marie");
        model.addAttribute("today", LocalDate.of(2026, 9, 23));
        return "pages/home";
    }

    @GetMapping("/products")
    public String products(Model model) {
        model.addAttribute("products", List.of(
                new Product("Keyboard", new BigDecimal("25")),
                new Product("Mouse", new BigDecimal("12.5")),
                new Product("Screen", new BigDecimal("1149"))));
        return "pages/products";
    }
}

动作与语言无关:它们提供数据,而由视图负责翻译和格式化。价格是一个 [BigDecimal],这种用于精确十进制数的 [Java] 类型适合表示货币金额(第 16 行)。主页上的日期是固定日期,即 2026 年 9 月 23 日(第 22 行),而不是当前日期:因此,下面的结果不取决于运行示例的日期。

5.1.6. 运行

英语(尚无 Cookie),位于 URL http://localhost:5000/ 和 http://localhost:5000/products:

Image

Image

点击语言按钮(这里是 EN),用 [curl] 模拟([-H] 选项添加了浏览器本应发送的 [Referer] 标头):

curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/en
1
2
3
4
HTTP/1.1 302
Set-Cookie: language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:23 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/products
Content-Length: 0

[CookieLocaleResolver] 设置 [language] Cookie,其值为 [en],并带有所要求的特性([Max-Age] 和 [Expires] 都指定生存期,分别用于较旧和较新的浏览器)。重定向返回原始页面([Tomcat];服务器已将路径 [/products] 扩展为完整地址)。点击 FR 的效果相同(Cookie [language=fr]):页面现在是法语:

Image

Image

日期和金额也随之变化:“mercredi 23 septembre 2026”“1 149,00 €”。

试图利用我们重定向的恶意网站只会看到我们自己站点的页面:

curl -i -H "Referer: https://pirate.example/trap?x=1" http://localhost:5000/language/fr
curl -i -H "Referer: https://pirate.example//pirate.example/trap" http://localhost:5000/language/fr
1
2
3
4
5
6
7
8
9
HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/trap?x=1
Content-Length: 0

HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/
Content-Length: 0

不受支持的语言:

curl -i http://localhost:5000/language/de
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:49:23.993Z","status":404,"error":"Not Found","message":"404 NOT_FOUND","path":"/language/de"}

来自 [Spring Boot] 的默认错误响应:对 [curl] 是 JSON,对浏览器是 HTML 页面。第 7 章将展示如何用我们自己的页面替换它。

最后,请记住 Cookie 是由客户端控制的。手动创建的 [language=de] Cookie 会被 [CookieLocaleResolver] 接受:文本仍然是英语([Translator] 的默认语言),但日期以德语格式显示:

curl -b "language=de" http://localhost:5000/
1
2
3
<html lang="de">
  <p>Hello Marie!</p>
  <p>Today is Mittwoch, 23. September 2026.</p>

(只显示页面的三行)。这没什么大不了:用户只是在愚弄自己。

案例研究正是以这种方式进行的,只是使用了更完整的字典([i18n/fr.json] 和 [i18n/en.json]):同样的 Bean [messageSource],同样的 [CookieLocaleResolver],同样的控制器 [/language/{language}]。唯一的区别是,业务层和 Web 层生成的错误消息也是键,由视图在最后一刻进行翻译。