Skip to content

6. 国际化

6.1. 示例 21:双语应用

[RdvMedecins]应用提供法语和英语两种语言。在[NestJS]课程中,服务器在发送页面之前负责翻译页面。现在,页面在浏览器中生成:由客户端翻译页面,切换语言不再需要与服务器进行任何交互。

[Angular] 有自己的翻译系统[@angular/localize],它会为每种语言生成一个编译后的应用:因此切换语言只需加载另一个应用。我们将改用[ngx-translate]库,它是与[Angular]搭配使用最广泛的库,它在运行时进行翻译:只需点击一下,就能重新翻译整个页面。

1
2
3
4
5
6
7
8
21-i18n/src/app/
├── i18n/
│   ├── fr.json          法语词典
│   ├── en.json          英语词典
│   ├── i18n.ts          ngx-translate 的配置
│   └── plural.pipe.ts   复数形式的选择
├── app.ts
└── app.html

该库在工作区的[package.json]文件中声明:

        "@ngx-translate/core": "^18.0.0",

6.1.1. 字典

{
  "APP": {
    "TITLE": "Exemple 21 - une application en deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS": {
      "zero": "aucun rendez-vous",
      "one": "un rendez-vous",
      "other": "{{n}} rendez-vous"
    },
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Traduire une réponse du serveur",
    "EXPLANATION": "Le serveur RdvMedecins ne renvoie que des clés. C'est le client qui les traduit :"
  }
}
{
  "APP": {
    "TITLE": "Example 21 - a two-language application",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS": {
      "zero": "no appointment",
      "one": "one appointment",
      "other": "{{n}} appointments"
    },
    "ADD": "Add an appointment",
    "REMOVE": "Remove one"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Translating a server response",
    "EXPLANATION": "The RdvMedecins server only sends keys. The client translates them:"
  }
}
  • 每段文本都有一个键 ,由各级名称组成:[HOME.HELLO]、[ERRORS.LOGIN_TAKEN]……代码和模板中不再包含任何文本,只有键;
  • 第 7 行:参数写在双花括号之间:[{{name}}];
  • 第 10–14 行:复数形式,归入同一个键下(见下文);
  • 第 18–21 行:[ERRORS.*] 这些键是服务器[RdvMedecins] 在其错误响应中返回的键(下一章)。服务器不返回文本,而是返回一个键;客户端将其翻译成用户的语言。

6.1.2. 配置

// =========================================================================
// 21-i18n/src/app/i18n/i18n.ts - ngx-translate 的配置
// -------------------------------------------------------------------------
// ngx-translate 是 Angular 中使用最广泛的翻译库。
// 我们为它提供:
//   - 每种语言一个词典(fr.json、en.json),其中每段文本都有一个
//     键("HOME.HELLO");参数写作 {{name}};
//   - 一个加载器(TranslateLoader),返回某种语言的
//     词典。我们的加载器从应用代码中获取词典(导入
//     JSON 文件);也可以换成下载词典的加载器;
//   - 起始语言(存储在 localStorage 中的语言,否则取
//     浏览器的语言,再否则为英语)和回退语言。
// 在模板中,{{ 'HOME.HELLO' | translate: { name: 'Marie' } }}
// 会显示当前语言的文本;切换语言会更新
// 整个页面。
//
// 这在客户端与 NestJS 课程的原理相同(词典
// i18n/*.json + 辅助函数 {{t}})——但现在翻译在
// 浏览器中完成,切换语言不再需要服务器参与。
//
// (Angular 也有自己的体系 @angular/localize,它为每种语言构建一个
// 编译好的应用:此时只能通过
// 切换页面来更换语言。而 ngx-translate 则是在运行时翻译。)
// =========================================================================

import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const LANGUAGE_KEY = 'example21.language';

// 词典的加载器
class DictionariesLoader implements TranslateLoader {
  getTranslation(language: string): Observable<TranslationObject> {
    return of(language === 'en' ? en : fr);
  }
}

function initialLanguage(): Language {
  const stored = localStorage.getItem(LANGUAGE_KEY);
  if (stored === 'fr' || stored === 'en') {
    return stored;
  }
  return navigator.language.startsWith('fr') ? 'fr' : 'en';
}

export function provideI18n(): Provider[] {
  return provideTranslateService({
    loader: provideTranslateLoader(DictionariesLoader),
    fallbackLang: 'en', // 法语中缺失的键:使用英语的
    lang: initialLanguage(),
  });
}
  • 第 29–30 行:字典作为模块导入;它们是应用代码的一部分。这得益于[resolveJsonModule]选项,该选项位于[tsconfig.json]文件中;
  • 第 34 行:所选语言在[localStorage] 中存储时使用的键(示例 20);
  • 第 37–41 行:字典加载器:[ngx-translate] 调用它,以可观察对象的形式获取某种语言的字典。我们的加载器从代码中获取字典;另一种加载器也可以从服务器下载字典;
  • 第 43–49 行:源语言:用户上次选择的语言;否则,如果浏览器语言为法语,则为法语;否则为英语;
  • 第 51–57 行:[provideTranslateService] 使[ngx-translate] 的服务在整个应用中可用。[fallbackLang]:当当前字典中缺少某个键时所使用的语言。
// =========================================================================
// 21-i18n/src/main.ts
// -------------------------------------------------------------------------
// provideI18n():ngx-translate(参见 app/i18n/i18n.ts)。
// registerLocaleData(localeFr):日期、
// 货币……管道的法语规则(英语始终可用)。
// =========================================================================

import { registerLocaleData } from '@angular/common';
import localeFr from '@angular/common/locales/fr';
import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';
import { provideI18n } from './app/i18n/i18n';

registerLocaleData(localeFr);

bootstrapApplication(App, { providers: [provideI18n()] }).catch((error) => console.error(error));
  • 第 15 行:管道[date] 和[currency] (示例 09)了解英语的规则;法语的规则必须进行注册;
  • 第 17 行:[ngx-translate] 的服务被添加到应用中。

6.1.3. 复数

[ngx-translate] 不支持复数。一个小型管道负责选择正确的形式:

// =========================================================================
// 21-i18n/src/app/i18n/plural.pipe.ts - 选择复数形式
// -------------------------------------------------------------------------
// ngx-translate 不处理复数。词典在同一个键下给出
// 各种形式("APPOINTMENTS": { "zero", "one", "other" }),而
// 这个管道根据数量和语言选择合适的形式:
//     {{ 'HOME.APPOINTMENTS' | plural: n : language | translate: { n } }}
// Intl.PluralRules 了解每种语言的规则(英语和法语是 "one" 或 "other",
// 而波兰语、阿拉伯语等则有其他形式)。
// =========================================================================

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({ name: 'plural' })
export class PluralPipe implements PipeTransform {
  transform(key: string, n: number, language: string | null): string {
    if (n === 0) {
      return `${key}.zero`;
    }
    return `${key}.${new Intl.PluralRules(language ?? 'en').select(n)}`;
  }
}
  • 第 16–21 行:该管道接收一个键([HOME.APPOINTMENTS])、一个数字和一种语言;它返回正确形式的键(例如[HOME.APPOINTMENTS.one]);
  • 第 18 行:零有自己的格式(“没有预约”);
  • 第 20 行:由浏览器提供的[Intl.PluralRules]遵循每种语言的规则:法语和英语使用[one] 或[other] ,而波兰语或阿拉伯语则有其他形式。(注意:在法语中,1.5 是单数;在英语中,它是复数。)

6.1.4. 翻译后的页面

// =========================================================================
// 21-i18n/src/app/app.ts - 翻译后的页面
// -------------------------------------------------------------------------
//   - 'KEY' | translate 一段文本;
//   - 'KEY' | translate: { name: ... } 带参数的文本;
//   - date / currency 与语言配合 日期、金额,采用
//                                          当前语言的格式;
//   - translate.use('fr') 切换语言:整个
//                                          页面会被重新翻译。
// TranslateService.currentLang 是一个信号:当前语言。
// =========================================================================

import { Component, effect, inject, signal } from '@angular/core';
import { CurrencyPipe, DatePipe } from '@angular/common';
import { TranslatePipe, TranslateService } from '@ngx-translate/core';
import { LANGUAGE_KEY, Language, LANGUAGES } from './i18n/i18n';
import { PluralPipe } from './i18n/plural.pipe';

@Component({
  selector: 'app-root',
  imports: [CurrencyPipe, DatePipe, TranslatePipe, PluralPipe],
  templateUrl: './app.html',
})
export class App {
  private readonly translate = inject(TranslateService);
  protected readonly language = this.translate.currentLang;
  protected readonly languages = LANGUAGES;
  protected readonly count = signal(2);
  protected readonly today = new Date();

  // RdvMedecins 服务器将返回的内容(参见关于黑盒的章节)
  protected readonly serverResponses = [
    { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
    { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
  ];

  // translate.translate(key):跟随当前语言的信号
  private readonly title = this.translate.translate('APP.TITLE');

  constructor() {
    // 每次切换语言时:将其存储起来,并更新
    // 页面的 lang 属性(对屏幕阅读器、拼写检查器有用)
    effect(() => {
      const language = this.language();
      if (language) {
        localStorage.setItem(LANGUAGE_KEY, language);
        document.documentElement.lang = language;
      }
      document.title = String(this.title());
    });
  }

  protected choose(language: Language): void {
    this.translate.use(language);
  }
}
  • 第 21 行:[TranslatePipe]:管道[translate];
  • 第 25 行:[TranslateService]:[ngx-translate]的主服务;
  • 第 26 行:[currentLang]:当前语言,以信号的形式提供;
  • 第 32–35 行:两个错误响应,与服务器返回的形式一致:一个键和若干参数;
  • 第 38 行:[translate.translate(key)] 返回一个信号 ,其值等于该键的翻译,并随当前语言变化;
  • 第 43–50 行:每当语言改变时执行的动作:保存语言(第 46 行),更新页面的[lang]属性(第 47 行;屏幕阅读器和拼写检查器会用到它),以及标签页标题(第 49 行);
  • 第 54 行:[use] 更改当前语言:整个页面被重新翻译。
<div class="container py-4" style="max-width: 720px">
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h1 class="h3 mb-0">{{ 'APP.TITLE' | translate }}</h1>
    <div class="btn-group btn-group-sm" role="group" [attr.aria-label]="'APP.LANGUAGE' | translate">
      @for (l of languages; track l) {
        <button class="btn" [class]="language() === l ? 'btn-primary' : 'btn-outline-primary'" (click)="choose(l)">
          {{ l.toUpperCase() }}
        </button>
      }
    </div>
  </div>

  <div class="card p-3 mb-3">
    <p>{{ 'HOME.HELLO' | translate: { name: 'Marie' } }}</p>
    <!-- 由另一个管道按当前语言计算出的参数 -->
    <p>{{ 'HOME.TODAY' | translate: { date: (today | date: 'fullDate' : '' : language() ?? 'en') } }}</p>
    <p>{{ 'HOME.PRICE' | translate: { price: (1234.5 | currency: 'EUR' : 'symbol' : '1.2-2' : language() ?? 'en') } }}</p>
    <!-- plural 选择键(zero、one、other),translate 负责翻译 -->
    <p class="fw-bold">{{ 'HOME.APPOINTMENTS' | plural: count() : language() | translate: { n: count() } }}</p>
    <div class="d-flex gap-2">
      <button class="btn btn-sm btn-outline-success" (click)="count.set(count() + 1)">{{ 'HOME.ADD' | translate }}</button>
      <button class="btn btn-sm btn-outline-secondary" [disabled]="count() === 0" (click)="count.set(count() - 1)">
        {{ 'HOME.REMOVE' | translate }}
      </button>
    </div>
  </div>

  <div class="card p-3">
    <h2 class="h6">{{ 'SERVER.TITLE' | translate }}</h2>
    <p>{{ 'SERVER.EXPLANATION' | translate }}</p>
    <ul class="mb-0">
      @for (r of serverResponses; track r.key) {
        <!-- 服务器的键就是词典中的一个键;params 提供其参数 -->
        <li><code>{{ r.statusCode }} {{ r.key }}</code><br>&rarr; {{ r.key | translate: r.params }}</li>
      }
    </ul>
  </div>
</div>
  • 第 3 行:['APP.TITLE' | translate]:该键在当前语言中的翻译;
  • 第 6 行:当前语言的按钮高亮显示;
  • 第 14 行:带参数的文本:管道接收一个对象,该对象提供每个参数的值;
  • 第 16–17 行:参数的值可以由另一个管道计算得出。[date] 和[currency] 的最后一个参数是语言:日期和金额按法语或英语的风格书写;
  • 第 19 行:两个链式管道:[plural] 选择键,[translate] 翻译该键;
  • 第 34 行:服务器返回的键连同其参数一起被翻译。

[npm start 21-i18n];当浏览器设置为法语时,页面显示为法语:

Image

点击[EN],然后点击“Remove one”:

Image

重新加载页面:它仍然是英语;语言已被保存。