Skip to content

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]:

1
2
3
<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 时,页面是英语,即默认语言):

Image

Image

点击 EN:

curl -i -H "Referer: http://localhost:3000/products" http://localhost:3000/language/en
1
2
3
4
5
6
7
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 并重定向到原来的页面,该页面现在是英语:

Image

Image

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