5. 国际化
国际化的应用以用户的语言显示文本。案例研究使用法语和英语。原理很简单:视图中不再包含文本,而是包含 键 ([MENU.HOME]),而每种语言的 字典 把文本与每个键关联起来。所选的语言存放在 Cookie 中。
[Laravel] 有自己的翻译系统,我们在示例 09 的验证消息中已经遇到过。它接受两种字典,存放在 [lang] 文件夹中:[PHP] 文件,每个主题每种语言一个([lang/fr/validation.php]),返回一个键数组;以及 JSON 文件,每种语言一个([lang/fr.json]),其中每个键都是任意字符串。我们使用第二种格式:除了参数语法之外,这些字典与案例研究中 [ASP.NET Core MVC]、[NestJS]、[Spring MVC] 和 [Flask] 版本中的字典相同,而且无需任何特殊工具就可以读写其格式。日期和金额的格式化与示例 16 中相同。
5.1. 示例 22:双语应用
| 22-i18n/
├── app/
│ ├── Helpers/
│ │ └── Formats.php
│ ├── Http/
│ │ ├── Controllers/
│ │ │ ├── LanguageController.php
│ │ │ └── PagesController.php
│ │ └── Middleware/
│ │ └── SetLanguage.php
│ └── Models/
│ └── Product.php
├── lang/
│ ├── en.json
│ └── fr.json
├── resources/
│ └── views/
│ ├── fragments/
│ │ └── navbar.blade.php
│ ├── layout.blade.php
│ └── pages/
│ ├── home.blade.php
│ └── products.blade.php
└── ...
|
5.1.1. 字典
文件 [lang/fr.json]:
| {
"MENU.HOME": "Accueil",
"MENU.PRODUCTS": "Produits",
"HOME.TITLE": "Bienvenue",
"HOME.HELLO": "Bonjour :name !",
"HOME.DATE": "Nous sommes le :date.",
"PRODUCTS.TITLE": "Nos produits",
"PRODUCTS.NAME": "Produit",
"PRODUCTS.PRICE": "Prix",
"PRODUCTS.COUNT": ":n produit(s) au catalogue."
}
|
JSON 字典是一个对象,其中每个键值对把一个键与它的文本关联起来。键根据前缀按主题分组:菜单文本“Accueil”的键是 [MENU.HOME]。文本可以包含 占位符,写作 [:name],在翻译时会被替换。(案例研究其他版本中的字典把 JSON 对象嵌套起来——[{"MENU": {"HOME": "Accueil"}}] ——并把参数写成 [{name}];而 [Laravel] 中的字典是“扁平”的,并使用 [:name] 语法。)[lang/en.json] 文件的键与之完全相同:
| {
"MENU.HOME": "Home",
"MENU.PRODUCTS": "Products",
"HOME.TITLE": "Welcome",
"HOME.HELLO": "Hello :name!",
"HOME.DATE": "Today is :date.",
"PRODUCTS.TITLE": "Our products",
"PRODUCTS.NAME": "Product",
"PRODUCTS.PRICE": "Price",
"PRODUCTS.COUNT": ":n product(s) in the catalogue."
}
|
如果当前语言的 JSON 字典中缺少某个键,就会在该语言文件夹中的 [PHP] 文件([lang/fr/*.php],示例 09)中查找,然后在回退语言的文件([APP_FALLBACK_LOCALE],默认为英语)中查找。没有备用字典(JSON):当前语言的字典(JSON)和这些文件中都缺少的键会按原样显示。这样,任何遗漏都能立即在屏幕上看到。
5.1.2. 每个请求的语言:app/Http/Middleware/SetLanguage.php
| <?php
// app/Http/Middleware/SetLanguage.php:每个请求的语言
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;
class SetLanguage
{
// 支持的语言;第一个是默认语言
public const LANGUAGES = ['en', 'fr'];
public const COOKIE = 'language';
// 如果受支持,则使用 [language] Cookie 中的语言,否则使用英语
public function handle(Request $request, Closure $next): Response
{
$language = $request->cookie(self::COOKIE);
App::setLocale(in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0]);
return $next($request);
}
}
|
- 第 14–16 行:支持的语言和 Cookie 名称:public 类常量,可以从其他类访问([SetLanguage::LANGUAGES]);
- 第 21–22 行:在每个动作之前确定请求的语言:如果存在 [language] Cookie 且其指定的语言受支持,就使用它指定的语言;否则使用英语。[$request->cookie(name)] 返回浏览器发送的 Cookie 的值,或 [null]。[in_array] 以 [true] 作为第三个参数时,也会比较类型([===])。[App::setLocale] (示例 16)设置请求的应用语言:这就是用于翻译和格式化的语言。
5.1.3. 配置:bootstrap/app.php
| <?php
// bootstrap/app.php:示例 22 的应用程序
use App\Http\Middleware\SetLanguage;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Support\Facades\Blade;
(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');
return Application::configure(basePath: dirname(__DIR__))
->withRouting(
web: __DIR__.'/../routes/web.php',
// 提供 Bootstrap 的路由(见示例 15)
then: fn () => require __DIR__.'/../../common/bootstrap.php')
->withMiddleware(function (Middleware $middleware): void {
// [language] Cookie 不加密:它不包含任何机密,并且
// 服务器只接受所支持的语言
$middleware->encryptCookies(except: [SetLanguage::COOKIE]);
// 每个请求的语言:[language] Cookie 中的语言,否则为英语
$middleware->web(append: SetLanguage::class);
})
->withExceptions()
->booted(function () {
// 在视图中:@money($price)(见示例 16)
Blade::directive('money', fn (string $expression) =>
"<?php echo e(\\App\\Helpers\\Formats::money($expression)); ?>");
})
->create();
|
- 第 19 行:默认情况下,[Laravel] 会对它设置的 所有 Cookie 加密,并对收到的 Cookie 解密(这是 [EncryptCookies] 中间件的作用,它位于 [web] 组中;见示例 20):用户无法读取或创建加密的 Cookie。[language] Cookie不包含任何机密信息,而且服务器只接受受支持的语言:我们把它排除在加密之外,这样就可以用 [curl] 查看(和创建)它。下一个示例将再次讨论这种加密;
- 第 21 行:语言中间件,位于 [web] 组的末尾(示例 16):它在 [EncryptCookies] 之后运行,因此读取的是已经解密的 Cookie;
- 第 26–27 行:示例 16 中的 [@money] 指令。
类 [App\Helpers\Formats] 就是示例 16 中的那个,只有一处不同:日期按各语言的“长”格式进行格式化:
| <?php
// app/Helpers/Formats.php:按请求的语言格式化的日期和金额(见示例 16)
namespace App\Helpers;
use Brick\Math\BigDecimal;
use Carbon\CarbonInterface;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Number;
class Formats
{
// 以欧元表示的金额
public static function money(BigDecimal $amount): string
{
return Number::currency($amount->toFloat(), in: 'EUR', locale: App::getLocale());
}
// 以完整文字表示的日期。"dddd LL" 格式:星期几,然后是
// 该语言的「长」格式日期:法语为 "mercredi 23 septembre 2026",
// 英语为 "Wednesday September 23, 2026"
public static function longDate(CarbonInterface $day): string
{
return $day->locale(App::getLocale())->isoFormat('dddd LL');
}
}
|
- 第 24 行:[LL] 是一种 本地化 格式:每种语言都有自己的格式(法语中是 [23 septembre 2026] ,英语中是 [September 23, 2026] ),而 [D MMMM YYYY] 会把法语的顺序强加给所有语言。[dddd] 会加上星期几。
5.1.4. 语言选择:app/Http/Controllers/LanguageController.php
| <?php
// app/Http/Controllers/LanguageController.php:语言的选择
namespace App\Http\Controllers;
use App\Http\Middleware\SetLanguage;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class LanguageController
{
// GET /language/fr:将选择存储在 Cookie 中,然后返回上一页
public function change(Request $request, string $code): RedirectResponse
{
abort_unless(in_array($code, SetLanguage::LANGUAGES, true), 404);
// 该 Cookie:有效期一年(以分钟计),页面的 JavaScript 无法读取
// (httpOnly),来自其他站点的 POST 请求绝不会携带它(sameSite)
return redirect(self::originPage($request))
->withCookie(cookie(SetLanguage::COOKIE, $code, 365 * 24 * 60, httpOnly: true, sameSite: 'lax'));
}
// 我们来自的页面(Referer 头部),只保留其路径:
// 重定向到来自请求的完整地址会使
// 用户被送往其他站点(「开放重定向」漏洞)
private static function originPage(Request $request): string
{
// parse_url 将 URL 拆分为各组成部分(路径、参数...)
$url = parse_url($request->header('Referer', ''));
$path = $url['path'] ?? '';
// "//site.com/..." 会被浏览器理解为指向另一个站点的地址
// :同样拒绝
if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
return '/';
}
return isset($url['query']) ? "$path?{$url['query']}" : $path;
}
}
|
- 第 15 行:未知的语言代码:404;
- 第 18–19 行:该动作以重定向响应,指向用户来源的页面;用户会以新的语言回到该页面。响应中包含一个 Cookie,浏览器会在每个请求中把它发回:函数 [cookie] 创建它,方法 [withCookie] 把它添加到响应中。它的参数:名称、值、有效期 (以分钟计)(一年),以及两个命名参数:[httpOnly: true] 使它对 页面上的 [JavaScript] 不可见;[sameSite: 'lax'] 阻止浏览器在来自其他站点的 POST 请求中发送它;
- 第 25–36 行:原始页面由请求中的 [Referer] 头指定(HTTP 标准中使用的就是这个只有一个 [r] 的拼写错误的版本),浏览器会用包含该链接的页面的 URL 来填写它。但这个头来自客户端,客户端可以在其中放入任何内容。盲目地重定向到这个地址会使我们的应用变成 一个 *开放重定向*:带有我们域名的恶意链接可能把用户送到恶意站点。因此,我们只保留 URL 的路径和参数([parse_url] 函数,来自 [PHP] ,把它分解为各个组成部分,并存放在关联数组中),并拒绝任何以 [//] 开头的路径,浏览器会把这样的路径解释为另一个站点的地址。[Laravel] 还提供 [redirect()->back()] (或 [back()]),它重定向到存放在会话中的上一页(示例 20),而不是头 [Referer]:我们将在案例研究中使用它。
5.1.5. 动作:app/Http/Controllers/PagesController.php
| <?php
// app/Http/Controllers/PagesController.php:操作对语言一无所知:
// 它们提供数据,由视图进行翻译和格式化
namespace App\Http\Controllers;
use App\Models\Product;
use Brick\Math\BigDecimal;
use Carbon\CarbonImmutable;
use Illuminate\View\View;
class PagesController
{
public function home(): View
{
return view('pages.home', ['name' => 'Marie',
'today' => CarbonImmutable::create(2026, 9, 23)]);
}
public function products(): View
{
return view('pages.products', ['products' => [
new Product('Keyboard', BigDecimal::of('25')),
new Product('Mouse', BigDecimal::of('12.5')),
new Product('Screen', BigDecimal::of('1149')),
]]);
}
}
|
动作与语言无关:它们提供原始数据(姓名、日期、金额)。翻译和格式化由视图负责。
5.1.6. 在视图中翻译
| <!doctype html>
{{-- app()->getLocale(): the language of the request, "en" or "fr" --}}
<html lang="{{ app()->getLocale() }}">
<head>
<meta charset="utf-8">
{{-- the title: the [title] section of the page, already translated --}}
<title>@yield('title')</title>
<link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-3">
@include('fragments.navbar')
<main>
@yield('content')
</main>
</div>
</body>
</html>
|
- 第 3 行:页面的 [lang] 属性向浏览器、搜索引擎和屏幕阅读器指明其语言;
- 第 7 行:页面标题由页面本身提供,已经翻译好(节 [title])。
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
{{-- __('KEY'): the translation of a key, in the language of the request --}}
<a class="nav-link" href="/">{{ __('MENU.HOME') }}</a>
<a class="nav-link" href="/products">{{ __('MENU.PRODUCTS') }}</a>
</div>
{{-- the current language is highlighted --}}
<div class="btn-group btn-group-sm">
@foreach (['fr', 'en'] as $code)
<a @class(['btn', 'btn-primary' => app()->isLocale($code), 'btn-outline-primary' => ! app()->isLocale($code)])
href="/language/{{ $code }}">{{ strtoupper($code) }}</a>
@endforeach
</div>
</nav>
|
- 第 4–5 行:函数 [__] (两个下划线)返回某个键在请求语言中的翻译;
- 第 9–12 行:每种语言一个按钮,触发 [/language/{code}] 动作。当前语言高亮显示([btn-primary],实心按钮):[app()->isLocale($code)] 检查请求的语言。
| @extends('layout')
@section('title', __('HOME.TITLE'))
@section('content')
<h1>{{ __('HOME.TITLE') }}</h1>
{{-- a parameter: the second parameter of __, an array --}}
<p>{{ __('HOME.HELLO', ['name' => $name]) }}</p>
{{-- the date, formatted first, then passed as the [date] parameter --}}
<p>{{ __('HOME.DATE', ['date' => App\Helpers\Formats::longDate($today)]) }}</p>
@endsection
|
- 第 2 行:模板所用的、经过翻译的 [title] 节;
- 第 7 行:文本的参数以关联数组的形式提供,它是 [__] 的第二个参数;[:name] 被键 [name] 的值替换;
- 第 9 行:日期,使用 [longDate] 方法按请求的语言格式化,然后作为参数传递。这里不能使用指令([@longDate]):它直接写入页面,不返回值。
| @extends('layout')
@section('title', __('PRODUCTS.TITLE'))
@section('content')
<h1>{{ __('PRODUCTS.TITLE') }}</h1>
<table class="table table-sm w-auto">
<thead><tr><th>{{ __('PRODUCTS.NAME') }}</th><th class="text-end">{{ __('PRODUCTS.PRICE') }}</th></tr></thead>
<tbody>
@foreach ($products as $product)
<tr>
<td>{{ $product->name }}</td>
<td class="text-end">@money($product->price)</td>
</tr>
@endforeach
</tbody>
</table>
<p>{{ __('PRODUCTS.COUNT', ['n' => count($products)]) }}</p>
@endsection
|
- 第 17 行:一个计算得出的参数。不过,商品名称没有被翻译:它们是 数据 ,在真实的应用中会来自数据库。
5.1.7. 执行
主页,先是英语(默认语言),然后是点击“FR”按钮后的法语:


商品页面,两种语言各一个。金额遵循各语言的惯例:


用 [curl] 观察到的语言切换。选项 [-H] 提供浏览器会发送的头 [Referer] :
| curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/en
|
| HTTP/1.1 302 Found
Location: http://localhost:8000/products
Set-Cookie: language=en; expires=Sun, 26 Sep 2027 16:18:24 GMT; Max-Age=31536000; path=/; httponly; samesite=lax
...
|
重定向会把你带回原始页面,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
|
| HTTP/1.1 302 Found
Location: http://localhost:8000/trap
...
HTTP/1.1 302 Found
Location: http://localhost:8000
...
|
页面 [/trap] 在我们的站点上不存在:用户会收到 404 错误,但仍然留在我们的站点上。最后是带着 Cookie [language=en]([curl] 的选项 [-b])请求的主页;由于英语是默认语言,该页面与没有 Cookie 时相同:
| curl -b "language=en" http://localhost:8000/
|
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Welcome</title>
...
<a class="nav-link" href="/">Home</a>
<a class="nav-link" href="/products">Products</a>
...
<h1>Welcome</h1>
<p>Hello Marie!</p>
<p>Today is Wednesday September 23, 2026.</p>
...
|
选择语言的另一种方式是读取浏览器的 [Accept-Language] 头(示例 12)。二者常常结合使用:首次访问时使用浏览器的语言,之后使用用户选择的语言。本案例研究侧重于 Cookie,并以英语为默认语言。