Skip to content

5. 国际化

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

[Symfony] 包含一个翻译组件,即 Translator,我们在示例 09 的验证消息中已经遇到过它。它的字典存储在 [translations] 文件夹中,每个域 和每种语言一个文件:[validators.en.yaml] (验证消息域,示例 09)、[messages.en.yaml] (默认域,用于我们自己的文本)。YAML 格式允许嵌套键:案例研究中 [ASP.NET Core MVC]、[NestJS]、[Spring MVC]、[Flask] 和 [Laravel] 各版本的字典就是这样组织的,除语法之外完全相同。对于消息本身的语法,我们选择 ICU 格式(International Components for Unicode),这是 [intl] 扩展(来自 [PHP] )能够解释的标准,例如,它可以把文本变为复数形式。日期和金额的格式化仍与示例 16 相同。

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

22-i18n/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   ├── LanguageController.php
│   │   └── PagesController.php
│   ├── EventListener/
│   │   └── SetLanguage.php
│   ├── Model/
│   │   └── Product.php
│   └── Twig/
│       └── FormatsExtension.php
├── templates/
│   ├── fragments/
│   │   └── navbar.html.twig
│   ├── layout.html.twig
│   └── pages/
│       ├── home.html.twig
│       └── products.html.twig
├── translations/
│   ├── messages+intl-icu.en.yaml
│   └── messages+intl-icu.fr.yaml
└── ...

5.1.1. 配置:config/packages/framework.yaml

# config/packages/framework.yaml:FrameworkBundle 的配置
framework:
    secret: '%env(APP_SECRET)%'
    # 默认语言,以及应用程序支持的语言
    default_locale: en
    enabled_locales: ['en', 'fr']
    # 翻译服务;其字典位于 translations/ 文件夹中。
    # 法语字典中缺失的键,会到英语字典中查找
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks: ['en']
  • 第 5 行:应用程序的默认语言,用于未指定语言的请求(示例 09);
  • 第 6 行:应用程序支持的语言。该列表由 [Symfony] 使用(分析器、本地化路由生成等);我们自己的代码在监听器 [SetLanguage] 中也有自己的列表;
  • 第 9–11 行:翻译服务。[fallbacks] 指定回退语言:如果所请求语言的字典中缺少某个键,就会到英语字典中查找。所有字典中都缺少的键会原样显示:这样,任何遗漏都会立即在屏幕上显现出来。

5.1.2. 字典

文件 [translations/messages+intl-icu.fr.yaml]:

# translations/messages+intl-icu.fr.yaml:法语字典。
# messages:默认域;+intl-icu:消息遵循 ICU 语法
# ({name}:参数;{n, plural, ...}:取决于数字的消息)
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, plural, =0 {Aucun produit} one {# produit} other {# produits}} au catalogue.'

文件名由三部分组成:域([messages],默认域)、后缀 [+intl-icu](表示 ICU 格式的消息),以及语言([fr])。键使用 YAML 的嵌套结构按主题分组:菜单项“Accueil”的键是 [MENU.HOME],各级之间用句点分隔。文本可以包含参数,写作 [{name}],翻译时会被替换。

  • 第 9 行:撇号用作 YAML 字符串的定界符;当文本包含 YAML 会解释的字符(花括号、冒号等)时,它们是必需的;
  • 第 15 行:一条复数消息。[{n, plural, ...}] 根据参数 [n] 的值选择一种形式:[=0] 表示恰好为 0,[one] 表示单数,[other] 表示复数;[#] 会被替换为数字。复数规则取决于语言,ICU 知道这些规则:在法语中,0 和 1 是单数,而在英语中,0 是复数(“0 products”)。这相对于案例研究以前版本中使用的“product(s)”是一个改进。

文件 [translations/messages+intl-icu.en.yaml] 具有完全相同的键:

# translations/messages+intl-icu.en.yaml:英语字典;键相同
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, plural, =0 {No products} one {# product} other {# products}} in the catalogue.'

如果没有后缀 [+intl-icu],参数将写作 [%name%],复数将使用 [Symfony] 特有的语法([{0} Aucun produit|{1} Un produit|]1, Inf[ %n% produits])。ICU 格式是 [Symfony] 文档目前推荐的格式。

5.1.3. 每个请求的语言:src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php:每个请求的语言

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// 优先级 20:在路由之后,在使用语言的 Symfony 监听器之前(见示例 16)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // 支持的语言;第一个是默认语言
    public const LANGUAGES = ['en', 'fr'];

    public const COOKIE = 'language';

    // 如果 [language] Cookie 的语言受支持,则使用它,否则使用英语
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $language = $request->cookies->get(self::COOKIE);
        $request->setLocale(in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0]);
    }
}

这是示例 16 中的 [SetLanguage] 监听器,这次它从 Cookie 中获取语言:

  • 第 11 行:[kernel.request] 事件监听器,优先级为 20:在路由之后,但在使用请求语言的 [Symfony] 监听器之前(示例 16);
  • 第 15–17 行:支持的语言和 Cookie 名称:公共的类常量,可从其他类访问([SetLanguage::LANGUAGES]);
  • 第 22–24 行:请求的语言:如果存在且受支持,则为[language] Cookie 的语言;否则为英语。[$request->cookies] 是浏览器发送的 Cookie 集合(示例 05);[get] 返回 Cookie 的值,或 [null]。[in_array] 以 [true] 作为第三个参数时,也会比较类型([===])。[setLocale] 设置请求的语言:翻译器、我们的格式化过滤器,以及 [Twig] 的 [format_currency] 过滤器所使用的就是这种语言。

与 [Laravel] 不同,[Symfony] 不会加密 Cookie:[language] Cookie 以明文传输。这不是问题:它不包含机密信息,而且服务器只接受受支持的语言。下一个示例将重新讨论对 Cookie 能有多大信任的问题。

5.1.4. 语言选择:src/Controller/LanguageController.php

<?php
// src/Controller/LanguageController.php:语言的选择

namespace App\Controller;

use App\EventListener\SetLanguage;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class LanguageController extends AbstractController
{
    // GET /language/fr:将选择存储在 Cookie 中,然后返回上一页。
    // requirements:不是 en 或 fr 的语言与路由不匹配(404)
    #[Route('/language/{code}', name: 'language', requirements: ['code' => 'en|fr'], methods: ['GET'])]
    public function change(Request $request, string $code): RedirectResponse
    {
        $response = $this->redirect(self::originPage($request));
        // 该 Cookie:有效期一年,页面的 JavaScript 无法读取(httpOnly),
        // 绝不会随来自其他站点的 POST 请求一起发送(sameSite lax)
        $response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
            ->withExpires(new \DateTimeImmutable('+1 year'))
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // 我们来自的页面(Referer 头部),其中只保留路径:
    // 如果重定向到请求中带来的完整地址,就可能
    // 把用户送到另一个站点(“开放重定向”漏洞)
    private static function originPage(Request $request): string
    {
        // parse_url 将 URL 拆分为各个组成部分(路径、参数...)
        $url = parse_url($request->headers->get('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." 会被浏览器理解为另一个站点上的地址
        // :同样拒绝
        if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
            return '/';
        }
        return isset($url['query']) ? "$path?{$url['query']}" : $path;
    }
}
  • 第 17 行:路由 [/language/{code}]。选项 [requirements] (示例 02)把参数限制为两种受支持的语言:[/language/de] 不对应任何路由,返回 404 错误;
  • 第 20 行:动作以重定向到用户来源页面作为响应:用户会被带回他们原来所在的页面,只是语言已改变;
  • 第 23–26 行:响应包含一个 Cookie,浏览器会在每个请求中将其发回。[Cookie] 类(来自 [Symfony] )对其进行描述:[Cookie::create(name, value)] 创建它,而每个 [with...] 方法 都返回一个修改后的副本(不可变对象;参见示例 03):[withExpires],即过期日期(一年后);[withHttpOnly(true)] 使页面上的 [JavaScript] 无法看到它;[withSameSite(Cookie::SAMESITE_LAX)] 防止浏览器在来自其他站点的 POST 请求中发送它。(顺带一提,[httpOnly] 和 [lax] 正是 [Cookie::create] 的默认值。)[$response->headers->setCookie] 把它作为 [Set-Cookie] 头添加到响应中;
  • 第 33–44 行:原始页面由请求中的 [Referer] 头指定(HTTP 标准使用的是拼写错误的版本,只有一个 [r]),浏览器会用包含该链接的页面的 URL 填充它。但这个头来自客户端,客户端可以在其中放入任何内容。盲目地重定向到这个地址会使我们的应用程序变成开放重定向:带有我们域名的恶意链接可能把用户引向恶意网站。因此,我们只保留 URL 的路径和参数([parse_url] 函数(来自 [PHP] )把它分解为关联数组中的各个组成部分),并拒绝任何以 [//] 开头的路径,浏览器会把这样的路径解释为另一个站点的地址。

5.1.5. 动作:src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php:这些操作对语言一无所知:
// 它们提供数据,由视图进行翻译和格式化

namespace App\Controller;

use App\Model\Product;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('pages/home.html.twig', ['name' => 'Marie',
            'today' => new DateTimeImmutable('2026-09-23')]);
    }

    #[Route('/products', name: 'products')]
    public function products(): Response
    {
        return $this->render('pages/products.html.twig', ['products' => [
            new Product('Keyboard', 2500),
            new Product('Mouse', 1250),
            new Product('Screen', 114900),
        ]]);
    }
}

这些动作与语言无关:它们提供原始数据(名称、日期、以分为单位的金额)。翻译和格式化由视图负责。[Product] 类有名称和以分为单位的价格;扩展 [FormatsExtension] 就是示例 16 中的那个:它的过滤器 [long_date] 以请求语言的“完整”格式写出日期(“Wednesday, September 23, 2026”“mercredi 23 septembre 2026”),而它的过滤器 [money] 写出金额。

5.1.6. 在视图中翻译

<!doctype html>
{# app.request.locale:请求的语言,"en" 或 "fr" #}
<html lang="{{ app.request.locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# 标题:页面的 [title] 块,已经翻译 #}
  <title>{% block title %}{% endblock %}</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {% include 'fragments/navbar.html.twig' %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • 第 3 行:页面的 [lang] 属性向浏览器、搜索引擎和屏幕阅读器指明其语言;[app.request.locale] 是请求的语言;
  • 第 8 行:页面标题由页面本身提供,已经翻译(块 [title])。
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# 'KEY'|trans:键的翻译,使用请求的语言 #}
    <a class="nav-link" href="{{ path('home') }}">{{ 'MENU.HOME'|trans }}</a>
    <a class="nav-link" href="{{ path('products') }}">{{ 'MENU.PRODUCTS'|trans }}</a>
  </div>
  {# 当前语言会突出显示 #}
  <div class="btn-group btn-group-sm">
    {% for code in ['fr', 'en'] %}
      <a class="btn {{ app.request.locale == code ? 'btn-primary' : 'btn-outline-primary' }}"
         href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
    {% endfor %}
  </div>
</nav>
  • 第 4–5 行:过滤器 [trans] 把键翻译成请求的语言;
  • 第 9–12 行:每种语言一个按钮,触发动作 [/language/{code}]。当前语言会被突出显示([btn-primary],实心按钮)。
{% extends 'layout.html.twig' %}
{% block title %}{{ 'HOME.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'HOME.TITLE'|trans }}</h1>
  {# 参数:trans 过滤器的参数,一个关联数组 #}
  <p>{{ 'HOME.HELLO'|trans({name: name}) }}</p>
  {# 日期,先格式化(long_date 过滤器,见示例 16),再作为 [date] 参数传递 #}
  <p>{{ 'HOME.DATE'|trans({date: today|long_date}) }}</p>
{% endblock %}
  • 第 2 行:模板的已翻译 [title] 块;
  • 第 7 行:文本的参数以关联数组的形式提供,作为 [trans] 过滤器的参数;[{name}] 会被键 [name] 的值替换;
  • 第 9 行:日期,由 [long_date] 过滤器按请求语言格式化,然后作为参数传递。
{% extends 'layout.html.twig' %}
{% block title %}{{ 'PRODUCTS.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'PRODUCTS.TITLE'|trans }}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{{ 'PRODUCTS.NAME'|trans }}</th><th class="text-end">{{ 'PRODUCTS.PRICE'|trans }}</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          <td>{{ product.name }}</td>
          {# 示例 16 的 money 过滤器:格式取决于语言 #}
          <td class="text-end">{{ product.priceCents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# 复数消息:ICU 根据 n 参数选择形式 #}
  <p>{{ 'PRODUCTS.COUNT'|trans({n: products|length}) }}</p>
{% endblock %}
  • 第 13 行:过滤器 [money],其结果取决于语言;
  • 第 19 行:消息复数形式的 [n] 参数:产品数量([length],示例 14)。产品名称本身不翻译:它们是数据 ,在真实的应用程序中会来自数据库。

在视图之外,翻译器是类型为 [TranslatorInterface] 的服务,动作或服务可以通过注入来接收它:[$translator->trans('HOME.HELLO', ['name' => 'Marie'])]。

5.1.7. 执行

首页,先是英语(默认语言),然后点击“FR”按钮后变为法语:

Image

Image

产品页面,两种语言各一个。金额遵循各自语言的习惯:

Image

Image

用 [curl] 观察到的语言切换。选项 [-H] 提供浏览器会发送的 [Referer] 头:

curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/en
1
2
3
4
5
HTTP/1.1 302 Found
...
Location: /products
...
Set-Cookie: language=en; expires=Mon, 27 Sep 2027 09:47:37 GMT; Max-Age=31536000; path=/; httponly; samesite=lax

重定向把你带回原来的页面([Symfony] 写出的是相对 URL,由浏览器补全),并且 Cookie 被设置为一年有效。指向其他站点的 [Referer] 不会把你重定向到那里:只保留它的路径。

curl -i -H "Referer: https://pirate.example/trap" http://localhost:8000/language/en
curl -i -H "Referer: http://localhost:8000//pirate.example/x" http://localhost:8000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 Found
Location: /trap
...
HTTP/1.1 302 Found
Location: /
...

页面 [/trap] 在我们的站点上不存在:用户会收到 404 错误,但仍停留在我们的站点上。最后,使用 Cookie [language=en] ([-b] 选项,属于 [curl])请求首页:

curl -b "language=en" http://localhost:8000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Welcome</title>
...
        <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/products">Products</a>
...
    <p>Hello Marie!</p>
    <p>Today is Wednesday, September 23, 2026.</p>
...

选择语言的另一种方式是读取浏览器的 [Accept-Language] 头(示例 12;[$request->getPreferredLanguage(['fr', 'en'])] 从受支持的语言中选出最佳语言)。两者经常结合使用:首次访问时用浏览器的语言,之后用用户选择的语言。[Symfony] 中常用的第三种方法是把语言放在 URL 中([/en/products]):一个特殊的路由参数 [{_locale}] 会自行设置请求的语言。本案例研究侧重于 Cookie,并以英语为默认语言。