5. 国际化
一个 国际化的应用会以用户的语言显示文本。案例研究使用法语和英语。原理很简单:视图中不再包含文本,而是 键 ([MENU.HOME]),每种语言都有一个 词典 ,为每个键关联一段文本。所选语言保存在 Cookie 中。
5.1. 示例 22:双语应用
| 22-i18n/
├── i18n/
│ ├── en.json
│ └── fr.json
├── src/
│ ├── app.module.ts
│ ├── helpers.ts
│ ├── i18n.ts
│ ├── language.controller.ts
│ ├── main.ts
│ └── pages.controller.ts
├── views/
│ ├── partials/
│ │ └── navbar.hbs
│ ├── home.hbs
│ ├── layout.hbs
│ └── products.hbs
├── nest-cli.json
└── tsconfig.json
|
5.1.1. 词典
文件 [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."
}
}
|
文件 [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 行:文本可以包含 参数,用花括号括起来,翻译时会被替换。词序因语言而异:这就是为什么文本不能通过简单拼接翻译后的片段来构造。
5.1.2. 翻译模块
文件 [src/i18n.ts]:
| import { readFileSync } from 'fs';
import { join } from 'path';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';
// Intl 用于日期和数字的 "locale"
export const LOCALES: Record<Language, string> = { fr: 'fr-FR', en: 'en-US' };
// 字典是嵌套的 JSON 对象:{ "MENU": { "HOME": "Home" } }
type Dictionary = { [key: string]: string | Dictionary };
// 字典在启动时只读取一次
const FOLDER = join(__dirname, '..', 'i18n');
const dictionaries: Record<Language, Dictionary> = {
fr: JSON.parse(readFileSync(join(FOLDER, 'fr.json'), 'utf-8')),
en: JSON.parse(readFileSync(join(FOLDER, 'en.json'), 'utf-8')),
};
export function isLanguage(value: unknown): value is Language {
return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}
// translate('en', 'HOME.HELLO', { name: 'Marie' }) -> "Hello Marie!"
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
const text = lookup(dictionaries[language], key) ?? key;
return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}
// 'HOME.HELLO':先进入 HOME,再进入 HELLO
function lookup(dictionary: Dictionary, key: string): string | null {
let node: string | Dictionary | undefined = dictionary;
for (const part of key.split('.')) {
if (typeof node !== 'object') {
return null;
}
node = node[part];
}
return typeof node === 'string' ? node : null;
}
|
我们来逐行说明这段代码:
- 第 4–6 行:支持的语言;
- 第 8 行:每种语言的“区域设置”,供 [Intl] 用于格式化日期和数字([fr-FR]: 23/09/2026, 12,50 €; [en-US]: 9/23/2026, €12.50);
- 第 14–18 行:词典在模块加载时只读取 一次,然后保存在内存中;
- 第 20–22 行:一个 类型检查,类似 [TypeScript] 的([value is Language]):测试为真之后,编译器就知道该值是 [Language];
- 第 25–28 行:翻译。在词典中查找键;如果找不到,就显示键本身:任何遗漏都能立刻在屏幕上看到。正则表达式 [/\{(\w+)\}/g] 找到每个参数 [{name}] 并用其值替换;
- 第 31–40 行:键 [HOME.HELLO] 被拆分为 [HOME],然后是 [HELLO],并继续逐层深入 JSON 对象。
5.1.3. 辅助函数
文件 [src/helpers.ts]:
| import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, LOCALES, isLanguage, translate } from './i18n';
interface Hbs {
registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}
// 页面的语言:res.locals.lang,合并到根模型中
function languageOf(options: HelperOptions): Language {
const lang = options.data?.root?.lang;
return isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
}
export function registerHelpers(hbs: Hbs): void {
// {{t 'KEY'}} 或 {{t 'KEY' name=...}}:翻译,可带具名参数
hbs.registerHelper('t', (key: string, options: HelperOptions) => translate(languageOf(options), key, options.hash));
// {{longDate when}}:"mercredi 23 septembre 2026" / "Wednesday, September 23, 2026"
hbs.registerHelper('longDate', (when: string, options: HelperOptions) =>
new Intl.DateTimeFormat(LOCALES[languageOf(options)], { dateStyle: 'full' }).format(new Date(when)),
);
// {{money price}}:"12,50 €" / "€12.50"
hbs.registerHelper('money', (amount: number, options: HelperOptions) =>
new Intl.NumberFormat(LOCALES[languageOf(options)], { style: 'currency', currency: 'EUR' }).format(amount),
);
hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
}
|
- 第 9–12 行:页面的语言位于 根模型中([options.data.root.lang]),由 [main.ts] 中间件通过 [res.locals] 放入其中;
- 第 16 行:辅助函数 [t] 翻译一个键。辅助函数的命名参数([options.hash])就是文本参数:[{{t 'HOME.HELLO' name=name}}];
- 第 19–21 行和第 24–26 行:日期和金额按语言进行格式化。
5.1.4. 语言选择
文件 [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import { NextFunction, Request, Response } from 'express';
import * as hbs from 'hbs';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { registerHelpers } from './helpers';
import { isLanguage, DEFAULT_LANGUAGE } from './i18n';
const ROOT = join(__dirname, '..');
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
app.setBaseViewsDir(join(ROOT, 'views'));
app.setViewEngine('hbs');
registerHelpers(hbs);
await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));
app.use(cookieParser());
// 每个页面的语言:取自 [language] Cookie,否则为英语
app.use((req: Request, res: Response, next: NextFunction) => {
const cookie = req.cookies?.language;
res.locals.lang = isLanguage(cookie) ? cookie : DEFAULT_LANGUAGE;
next();
});
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
第 22–26 行:对于每个请求,语言从 [language] Cookie 中读取(默认为英语)并存入 [res.locals.lang],从而进入每个视图的模型。
文件 [src/language.controller.ts]:
| import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from './i18n';
@Controller('language')
export class LanguageController {
// GET /language/fr:将选择存入 Cookie,然后返回上一页
@Get(':language')
change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
if (!isLanguage(language)) {
throw new NotFoundException();
}
res.cookie('language', language, { maxAge: 365 * 24 * 3600 * 1000, sameSite: 'lax', httpOnly: true });
res.redirect(originPage(req));
}
}
// 我们来自的页面(Referer 标头),只保留其路径:
// 重定向到取自请求的完整地址,会导致
// 将用户发送到另一个站点("open redirect" 漏洞)
function originPage(req: Request): string {
const referer = req.get('referer');
if (!referer) {
return '/';
}
try {
const url = new URL(referer);
return url.pathname + url.search;
} catch {
return '/';
}
}
|
- 第 8–15 行:[GET /language/en] 把所选语言存入一个有效期为一年的 Cookie,然后重定向到用户来自的页面。未知的语言会导致 404 错误;
- 第 21–32 行:原始页面由 [Referer] 头指定,浏览器在点击链接时会添加该头。我们只保留路径:如果重定向到请求中的 完整 URL,恶意网站就可以创建一个链接,用户经过我们的站点后会被送往该恶意网站(这种漏洞称为 [open redirect])。
5.1.5. 视图
[views/layout.hbs] 文件:
| <!doctype html>
<html lang="{{lang}}">
<head>
<meta charset="utf-8">
<title>{{t pageTitle}}</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
</head>
<body>
<div class="container py-3">
{{> navbar}}
{{{body}}}
</div>
</body>
</html>
|
- 第 2 行:页面的 [lang] 属性反映所选语言(对屏幕阅读器和拼写检查器有用);
- 第 5 行:页面标题是一个键,由操作提供([pageTitle]),并由视图翻译:[{{t pageTitle}}]。没有撇号时,辅助函数的参数是模型 变量,而不是字面字符串。
文件 [views/partials/navbar.hbs]:
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
<a class="nav-link" href="/">{{t 'MENU.HOME'}}</a>
<a class="nav-link" href="/products">{{t 'MENU.PRODUCTS'}}</a>
</div>
{{!-- 当前语言高亮显示 --}}
<div class="btn-group btn-group-sm">
<a class="btn {{#if (eq lang 'fr')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/fr">FR</a>
<a class="btn {{#if (eq lang 'en')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/en">EN</a>
</div>
</nav>
|
第 8–9 行:两个链接(更改语言不会修改任何应用数据:使用 GET 是合适的),当前语言高亮显示。
文件 [views/home.hbs]:
| <h1>{{t 'HOME.TITLE'}}</h1>
<p>{{t 'HOME.HELLO' name=name}}</p>
<p>{{t 'HOME.DATE' date=(longDate today)}}</p>
|
第 3 行:一个子表达式:日期先由 [longDate] 格式化,然后作为 [date] 参数传给辅助函数 [t]。
文件 [views/products.hbs]:
| <h1>{{t 'PRODUCTS.TITLE'}}</h1>
<table class="table table-sm w-auto">
<thead><tr><th>{{t 'PRODUCTS.NAME'}}</th><th class="text-end">{{t 'PRODUCTS.PRICE'}}</th></tr></thead>
<tbody>
{{#each products}}
{{!-- 在循环内部,辅助函数在根模型中查找语言 --}}
<tr><td>{{name}}</td><td class="text-end">{{money price}}</td></tr>
{{/each}}
</tbody>
</table>
<p>{{t 'PRODUCTS.COUNT' n=count}}</p>
|
[src/pages.controller.ts] 文件:
| import { Controller, Get, Render } from '@nestjs/common';
@Controller()
export class PagesController {
@Get()
@Render('home')
home(): object {
// pageTitle 是一个键:由视图负责翻译
return { pageTitle: 'HOME.TITLE', name: 'Marie', today: '2026-09-23' };
}
@Get('products')
@Render('products')
products(): object {
const products = [
{ name: 'Keyboard', price: 25 },
{ name: 'Mouse', price: 12.5 },
{ name: 'Screen', price: 1149 },
];
return { pageTitle: 'PRODUCTS.TITLE', products, count: products.length };
}
}
|
5.1.6. 执行
法语(点击 FR 之后;没有 Cookie 时,页面是英语,即默认语言):


点击 EN:
| curl -i -H "Referer: http://localhost:3000/products" http://localhost:3000/language/en
|
| HTTP/1.1 302 Found
Set-Cookie: language=en; Max-Age=31536000; Path=/; Expires=Thu, 23 Sep 2027 14:16:03 GMT; HttpOnly; SameSite=Lax
Location: /products
Content-Type: text/plain; charset=utf-8
Content-Length: 31
Found. Redirecting to /products
|
服务器设置 Cookie 并重定向到原来的页面,该页面现在是英语:


案例研究正是这样进行的,使用更完整的词典([i18n/fr.json] 和 [i18n/en.json]):相同的辅助函数 [t]、相同的控制器 [/language/:language]、相同的 Cookie。只有一个区别:业务层和 Web 层生成的错误消息也是 键,由视图在最后一刻翻译。