Skip to content

7. 国际化

7.1. 示例 21:双语应用程序

双语应用程序有三种需要翻译的文本:

  • 应用程序文本:标签和消息。它们存放在字典中,每种语言一个;
  • 日期和金额:[Intl] 对象,来自 [JavaScript] ,用所需的语言格式化它们(见示例 09);
  • [Ionic] 自身的文本:其日历的月份和星期、它的按钮。日历([<ion-datetime>])通过它的 [locale] 属性接收语言。

7.1.1. 字典

{
  "APP": {
    "TITLE": "Exemple 21 - deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} rendez-vous",
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un",
    "CALENDAR": "Ouvrir le calendrier",
    "CALENDAR_OK": "OK",
    "CALENDAR_CANCEL": "Annuler"
  },
  "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 :"
  }
}

每段文本都有一个键 ("HOME.HELLO")。参数写成 [{{name}}];复数文本有多个键:[_zero]、[_one]、[_other]。这些是 [JavaScript] [i18next] 库的约定,[React] 和 [Vue.js] 的 [RdvMedecins] 客户端就使用了它:案例研究将使用它们的字典,并补充几个额外的键。英文字典使用相同的键:

{
  "APP": {
    "TITLE": "Example 21 - two languages",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} appointments",
    "ADD": "Add an appointment",
    "REMOVE": "Remove one",
    "CALENDAR": "Open the calendar",
    "CALENDAR_OK": "OK",
    "CALENDAR_CANCEL": "Cancel"
  },
  "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:"
  }
}

项目的 [public/] 文件夹中的文件会随应用程序原样交付(在浏览器中:位于地址 /i18n/ex21-fr.json;在 [Android] 上:位于应用程序自身之内)。与 [Flutter] 示例中的字典相比,增加了两个键:[CALENDAR_OK] 和 [CALENDAR_CANCEL],它们对应于日历的按钮(下文讨论)。

7.1.2. 翻译

// =========================================================================
// src/app/ex21-i18n/translations.ts - 字典,当前语言
// -------------------------------------------------------------------------
// 每种语言都有它的字典(DICTIONARY),一个随应用程序一起提供的 JSON 文件
// (public/i18n/ex21-fr.json、ex21-en.json),其中每段文本
// 都有一个键(KEY)("HOME.HELLO"):
//   - t('HOME.HELLO', { name: 'Marie' }):当前(CURRENT)语言的文本,
//     其参数 {{name}} 会被替换;
//   - t('HOME.APPOINTMENTS', { count: n }):复数形式的文本;我们
//     根据 n 和语言的规则选择键 APPOINTMENTS_zero、_one 或 _other
//     (在法语中,0 和 1 是单数;在英语中,
//     只有 1);
//   - changeLanguage('fr'):加载另一个字典。语言和
//     字典都是信号(SIGNALS):调用 t() 的模板会
//     更新,它们会重新翻译自己。
// 这些是 JavaScript 库 i18next 的约定:
// 字典就是 RdvMedecins 的 Vue.js、Angular 和 React 客户端
// 所使用的字典……服务器只返回键(KEYS)
// (“ERRORS.LOGIN_TAKEN”),也使用它们。
// =========================================================================

import { signal } from '@angular/core';
import { Preferences as DeviceStorage } from '@capacitor/preferences';

export const languages = ['fr', 'en'];

// 一个字典:文本,或其他字典(嵌套的 JSON)
type Dictionary = { [key: string]: string | Dictionary };

export class Translations {
  private readonly _language = signal('en');
  private readonly _dictionary = signal<Dictionary>({});
  readonly language = this._language.asReadonly();

  // prefix:字典名称的开头(public/i18n/<prefix>-<language>.json)
  constructor(private readonly prefix: string) {}

  // 初始语言:存储在设备上的语言,否则是手机的语言
  // (如果已知),否则是英语
  async start(): Promise<void> {
    const stored = (await DeviceStorage.get({ key: `${this.prefix}.language` })).value;
    const device = navigator.language.substring(0, 2); // “en-US” -> “en”
    await this.changeLanguage(stored ?? (languages.includes(device) ? device : 'en'));
  }

  async changeLanguage(language: string): Promise<void> {
    // fetch:读取随应用程序一起提供的文件(public/ 文件夹)
    const response = await fetch(`i18n/${this.prefix}-${language}.json`);
    this._dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    // 页面的语言(屏幕阅读器、断字……)
    document.documentElement.lang = language;
    await DeviceStorage.set({ key: `${this.prefix}.language`, value: language });
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO'];如果不存在则为 undefined
  private find(key: string): string | undefined {
    let node: string | Dictionary | undefined = this._dictionary();
    for (const part of key.split('.')) {
      node = typeof node === 'object' ? node[part] : undefined;
    }
    return typeof node === 'string' ? node : undefined;
  }

  t(key: string, params: Record<string, string | number> = {}): string {
    let text: string | undefined;
    const count = params['count'];
    if (typeof count === 'number') {
      // Intl.PluralRules:复数形式("one"、"other"……),依据
      // 语言的规则;_zero 键如果存在,则对 0 优先
      const form = new Intl.PluralRules(this._language()).select(count);
      text = (count === 0 ? this.find(`${key}_zero`) : undefined) ?? this.find(`${key}_${form}`);
    }
    text ??= this.find(key);
    // 未知的键会原样显示:我们可以立即看出缺少了什么
    if (text === undefined) return key;
    // {{name}} -> name 参数的值
    return text.replace(/\{\{(\w+)\}\}/g, (all, name: string) => String(params[name] ?? all));
  }
}
  • 第 25 行:应用程序的语言;
  • 第 28 行:字典的类型——一个对象,其中每个属性要么是文本,要么是另一个字典(该类型是递归的:它引用自身);
  • 第 30–33 行:翻译类把当前语言及其字典存放在变量中。它是一个简单的类,而不是 [@Injectable] 服务:每个使用者用自己的前缀来创建它(第 36 行;示例 25 将有它自己的字典 [ex25-fr.json]……)。它将通过“工厂”提供给页面(稍后讨论);
  • 第 36 行:构造函数参数中的 [private readonly prefix] 既声明又初始化一个字段:这是 [TypeScript] 的一种简写;
  • 第 40–44 行:源语言:存储在设备上的语言(示例 20 中的 [@capacitor/preferences] 插件),否则是手机的语言([navigator.language]:“en-US”,保留其前两个字母),如果已知;否则为英语;
  • 第 46–54 行:切换语言:使用 [fetch] 读取字典,它是 [JavaScript] 中读取某个地址(这里是随应用程序一起提供的文件)并返回表示响应的 [Promise] 的函数;解码其 JSON 内容([response.json()],另一个 [Promise]);把字典和语言存入各自的字段;更新页面的语言([lang] 属性,位于 [<html>] 标签上,对屏幕阅读器很有用);把所选语言保存到设备上。我们本可以使用 [Angular] 的 HTTP 客户端(示例 22):[fetch] 可以避免在一个简单的类中依赖它;
  • 第 57–63 行:在字典中查找键“HOME.HELLO”:我们逐段([split('.')])向下遍历嵌套的 JSON 对象。[typeof node === 'object'] 是一种类型检查,它会在其为真的分支中“收窄”变量的类型:[TypeScript] 于是知道 [node] 是一个字典。读取信号([this._dictionary()],第 58 行)至关重要:调用 [t()] 的模板以这种方式读取信号,因此会在字典变化时更新;
  • 第 65–79 行:翻译。对于复数(数值参数 [count]),[Intl.PluralRules] 根据该语言的规则返回复数形式:[select(n)] 的结果是 [one] 或 [other] (其他语言还有 [two]、[few]、[many])。在法语中,0 和 1 是单数([one]);在英语中,只有 1 是单数。键 [_zero] 如果存在,则优先于 0(第 72 行),就像 [i18next] 一样。未知的键会原样显示(第 76 行):你可以立即看出缺少了什么。最后(第 78 行),每个 [{{name}}] 都被替换为参数的值:使用一个正则表达式 [/\{\{(\w+)\}\}/g],以及一个函数,它接收每个匹配([all])和括号中捕获的名称([name])。

为什么不使用官方的 [Angular] 工具?[Angular] 有自己的国际化系统([@angular/localize]):我们标记模板中的文本([<p i18n>Hello</p>]),把翻译提取到文件中,编译时为每种语言生成一个(ONE)应用程序。对于所有文本都事先已知的网站,这是最佳方案。然而,它不能“即时”切换语言,而我们的服务器返回的是键 (“ERRORS.LOGIN_TAKEN”),必须在运行时翻译:按键查询的字典更适合这一目的,并且使我们能与其他客户端共享字典。也有一些库为 [Angular] 做这件事([ngx-translate]、[Transloco]):我们的服务是它们的一个最小化版本。

7.1.3. 翻译后的页面

// =========================================================================
// src/app/ex21-i18n/ex21.page.ts - 一个双语应用程序
// -------------------------------------------------------------------------
//   - 应用程序的文本(TEXTS):字典(translations.ts),
//     通过依赖注入(providers)提供给页面;
//   - 日期和金额:JavaScript 的 Intl 对象,使用
//     当前语言(见示例 09);
//   - Ionic 自身(ITSELF)的文本(日历):<ion-datetime> 的 locale 属性,
//     以及它的按钮,由我们的字典翻译。
// 更改语言会重新翻译整个屏幕,无需重新启动。
// =========================================================================

import { Component, computed, effect, inject, signal } from '@angular/core';
import { Title } from '@angular/platform-browser';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardSubtitle, IonContent,
  IonDatetime, IonHeader, IonIcon, IonLabel, IonModal, IonSegment, IonSegmentButton, IonTitle, IonToolbar,
  SegmentValue,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendarOutline } from 'ionicons/icons';
import { languages, Translations } from './translations';

// RdvMedecins 服务器会返回的内容(见关于黑盒的那一章)
const serverResponses: { statusCode: number; key: string; params: Record<string, string> }[] = [
  { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
  { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
];

@Component({
  selector: 'app-ex21',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonSegment, IonSegmentButton, IonLabel, IonContent,
    IonCard, IonCardHeader, IonCardSubtitle, IonCardContent, IonButton, IonIcon, IonModal, IonDatetime,
  ],
  templateUrl: './ex21.page.html',
  // 页面专属(SPECIFIC)的提供者:ex21-*.json 字典的翻译
  providers: [{ provide: Translations, useFactory: () => new Translations('ex21') }],
  styles: `
    ion-segment { width: 110px; margin-inline-end: 8px; }
    ion-segment-button { min-width: 50px; }
    ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
    .code { font-family: monospace; font-size: 12px; }
  `,
})
export class Ex21Page {
  readonly tr = inject(Translations);
  readonly languages = languages;
  readonly serverResponses = serverResponses;
  readonly count = signal(2);
  private readonly today = new Date();

  // 按当前(CURRENT)语言格式化:在语言变化时重新计算
  readonly date = computed(() =>
    new Intl.DateTimeFormat(this.tr.language(), { dateStyle: 'full' }).format(this.today),
  );
  readonly price = computed(() =>
    new Intl.NumberFormat(this.tr.language(), { style: 'currency', currency: 'EUR' }).format(1234.5),
  );
  // ion-datetime 的语言:一个完整的“locale”(语言-国家)
  readonly locale = computed(() => (this.tr.language() === 'fr' ? 'fr-FR' : 'en-US'));

  constructor() {
    addIcons({ calendarOutline });
    this.tr.start();
    // 文档的标题(浏览器标签页),已翻译:一个副作用,
    // 在语言变化时重新执行
    const title = inject(Title);
    effect(() => title.setTitle(this.tr.t('APP.TITLE')));
  }

  // 顶部栏的分段控件:它的值(类型为 SegmentValue:一个
  // 字符串或数字)就是所选的语言
  chooseLanguage(value: SegmentValue | undefined): void {
    this.tr.changeLanguage(String(value));
  }
}
<!-- ======================================================================
     ex21.page.html - a page in two languages
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('APP.TITLE') }}</ion-title>
    <!-- 各种语言:一个“segment”,由若干按钮组成,其中只有一个被选中 -->
    <ion-segment slot="end" [value]="tr.language()" (ionChange)="chooseLanguage($event.detail.value)">
      @for (l of languages; track l) {
        <ion-segment-button [value]="l"><ion-label>{{ l.toUpperCase() }}</ion-label></ion-segment-button>
      }
    </ion-segment>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-card>
    <ion-card-content>
      <div>{{ tr.t('HOME.HELLO', { name: 'Marie' }) }}</div>
      <div>{{ tr.t('HOME.TODAY', { date: date() }) }}</div>
      <div>{{ tr.t('HOME.PRICE', { price: price() }) }}</div>
      <!-- count:选择复数形式,并替换 {{count}} -->
      <p><strong>{{ tr.t('HOME.APPOINTMENTS', { count: count() }) }}</strong></p>
      <ion-button fill="clear" size="small" (click)="count.set(count() + 1)">
        {{ tr.t('HOME.ADD') }}</ion-button>
      <ion-button fill="clear" size="small" [disabled]="count() === 0" (click)="count.set(count() - 1)">
        {{ tr.t('HOME.REMOVE') }}</ion-button>
      <br />
      <!-- id="calendar" 的按钮打开 trigger="calendar" 的模态对话框 -->
      <ion-button id="calendar" fill="outline">
        <ion-icon slot="start" name="calendar-outline" />
        {{ tr.t('HOME.CALENDAR') }}
      </ion-button>
      <ion-modal class="calendar" trigger="calendar">
        <!-- ng-template:内容只有在对话框打开时才会创建 -->
        <ng-template>
          <!-- locale: the months and the days in the current language (Intl);
               firstDayOfWeek: Monday (1) in French, Sunday (0) in English -->
          <ion-datetime presentation="date" min="2026-01-01" max="2027-12-31"
            [locale]="locale()" [firstDayOfWeek]="tr.language() === 'fr' ? 1 : 0" [showDefaultButtons]="true"
            [doneText]="tr.t('HOME.CALENDAR_OK')" [cancelText]="tr.t('HOME.CALENDAR_CANCEL')" />
        </ng-template>
      </ion-modal>
    </ion-card-content>
  </ion-card>

  <ion-card>
    <ion-card-header>
      <ion-card-subtitle>{{ tr.t('SERVER.TITLE') }}</ion-card-subtitle>
    </ion-card-header>
    <ion-card-content>
      <p>{{ tr.t('SERVER.EXPLANATION') }}</p>
      <!-- 服务器的键就是(IS)字典的键;params 提供它的参数 -->
      @for (r of serverResponses; track r.key) {
        <p class="code ion-margin-top">{{ r.statusCode }} {{ r.key }}</p>
        <p>→ {{ tr.t(r.key, r.params) }}</p>
      }
    </ion-card-content>
  </ion-card>
</ion-content>
  • 第 25–28 行(.ts):服务器会为 [RdvMedecins] 返回的内容:一个 HTTP 代码、一个键及其参数;
  • 第 38 行(.ts):页面专属的(SPECIFIC)提供者:装饰器 [providers] 中的 [@Component] 为该页面(及其组件)创建一个翻译实例,它随页面一起销毁。[useFactory] 提供创建它的函数,以及它的前缀;
  • 第 40–42 行(.ts):语言选择的尺寸和日历窗口的尺寸(一个大小适合其内容的对话框,而不是整页);
  • 第 47 行(.ts):翻译,作为服务获得;
  • 第 54–59 行(.ts):日期和价格,由 [Intl.DateTimeFormat] ([dateStyle: 'full']:“Tuesday, October 6, 2026”、“mardi 6 octobre 2026”)和 [Intl.NumberFormat] ([style: 'currency']:“€1,234.50”、“1 234,50 €”)按当前语言格式化。它们是计算信号:它们会检测语言,并在语言变化时重新计算。([date] 和 [currency] 管道,来自 [Angular] ,也接受语言作为参数,但那样的话你必须存储每种语言的规则,就像 [main.ts] 对法语所做的那样。)
  • 第 61 行(.ts):日历语言,采用 [<ion-datetime>] 所期望的“语言-国家”格式;
  • 第 65 行(.ts):源语言;
  • 第 68–69 行(.ts):文档标题(浏览器标签页),已翻译:[Title] 服务来自 [Angular],由一个副作用调用,该副作用会在语言变化时重新执行;
  • 第 74–76 行(.ts):语言选择;
  • 第 10 行(html):页面标题,已翻译;
  • 第 12–16 行(html):顶部栏中的语言选择:一个 [<ion-segment>],由多个按钮组成,其中只有一个被选中([value]),对应于 [SegmentedButton] 在 [Flutter] 中的作用;
  • 第 23–25 行(HTML):带参数的文本。已经格式化的日期和价格作为参数传入;
  • 第 27 行(html):[count] 选择复数形式并替换 [{{count}}];
  • 第 34–47 行(html):日历,位于一个模态窗口([<ion-modal>])中,由其 [id] 通过 [trigger] 属性指定的按钮打开。它的内容位于 [<ng-template>] 中,只有在窗口打开时才会创建。[<ion-datetime>] 使用 [Intl],按其 [[locale]] 属性指定的语言格式化月份和星期;[[firstDayOfWeek]]:一周在法语中从星期一开始,在英语中从星期日开始。它的按钮(默认为“Done”、“Cancel”)不会被 [locale] 翻译:[[doneText]] 和 [[cancelText]] 接收来自我们字典的文本。在 [flutter_localizations] 包中,对应的是 [Flutter] 的做法;
  • 第 58–61 行(html):[RdvMedecins] 服务器会返回的内容。服务器的键就是字典的键;它的参数就是文本的参数。

7.1.4. 输出

英文(左);法文,在添加之后(中);法文的日历(右):

更改语言会重新翻译整个屏幕,既无需重新启动,也不向服务器发出任何请求:语言和字典都是信号,所有读取它们的内容(模板文本、日期、价格、标题)都会随之更新。所选语言存储在设备上:重新启动应用程序(在浏览器中,重新加载页面),它就会以上次所选的语言打开。