Skip to content

7. Internationalisierung

7.1. Beispiel 21: Eine zweisprachige Anwendung

Eine zweisprachige Anwendung hat drei Arten von Texten, die übersetzt werden müssen:

  • Anwendungstexte: Beschriftungen und Meldungen. Sie werden in Wörterbüchern gespeichert, eines pro Sprache;
  • Datumsangaben und Beträge: Das Objekt [Intl] von [JavaScript] formatiert sie in der gewünschten Sprache (siehe Beispiel 09);
  • Texte von [Ionic] selbst: die Monate und Tage seines Kalenders, seine Schaltflächen. Der Kalender ([<ion-datetime>]) erhält die Sprache über sein Attribut [locale].

7.1.1. Die Wörterbücher

{
  "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 :"
  }
}

Jeder Text hat einen Schlüssel ("HOME.HELLO"). Die Parameter werden als [{{name}}] geschrieben; ein Text mit Pluralformen hat mehrere Schlüssel: [_zero], [_one], [_other]. Dies sind die Konventionen der Bibliothek [JavaScript] [i18next], die von den [React] und [Vue.js]-Clients von [RdvMedecins] verwendet wird: Die Fallstudie verwendet deren Wörterbücher, ergänzt um einige zusätzliche Schlüssel. Das englische Wörterbuch hat dieselben Schlüssel:

{
  "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:"
  }
}

Die Dateien im Ordner [public/] des Projekts werden unverändert mit der Anwendung ausgeliefert (im Browser: unter der Adresse /i18n/ex21-fr.json; unter [Android]: in der Anwendung selbst). Gegenüber den Wörterbüchern im Beispiel [Flutter] wurden zwei Schlüssel hinzugefügt: [CALENDAR_OK] und [CALENDAR_CANCEL], die den Schaltflächen des Kalenders entsprechen (siehe unten).

7.1.2. Übersetzungen

// =========================================================================
// src/app/ex21-i18n/translations.ts - Wörterbücher, eine aktuelle Sprache
// -------------------------------------------------------------------------
// Jede Sprache hat ihr WÖRTERBUCH, eine JSON-Datei, die mit
// der Anwendung ausgeliefert wird (public/i18n/ex21-fr.json, ex21-en.json), in der jeder Text
// einen SCHLÜSSEL hat ("HOME.HELLO"):
//   - t('HOME.HELLO', { name: 'Marie' }): der Text der AKTUELLEN
//     Sprache, in dem die Parameter {{name}} ersetzt werden;
//   - t('HOME.APPOINTMENTS', { count: n }): ein Text im Plural; wir
//     wählen den Schlüssel APPOINTMENTS_zero, _one oder _other nach n und den Regeln
//     der Sprache (im Französischen sind 0 und 1 Singular; im Englischen
//     nur 1);
//   - changeLanguage('fr'): lädt das andere Wörterbuch. Die Sprache und das
//     Wörterbuch sind SIGNALS: Die Templates, die t() aufrufen, werden
//     aktualisiert, sie übersetzen sich neu.
// Das sind die Konventionen der JavaScript-Bibliothek i18next: Die
// Wörterbücher sind die der Clients in Vue.js, Angular und React von
// RdvMedecins ... und der Server, der nur SCHLÜSSEL zurückgibt
// ("ERRORS.LOGIN_TAKEN"), verwendet sie ebenfalls.
// =========================================================================

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

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

// ein Wörterbuch: Texte oder andere Wörterbücher (verschachteltes 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: der Anfang des Namens der Wörterbücher (public/i18n/<prefix>-<language>.json)
  constructor(private readonly prefix: string) {}

  // die Startsprache: die auf dem Gerät gespeicherte, sonst die des
  // Telefons (falls bekannt), sonst Englisch
  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: liest eine mit der Anwendung ausgelieferte Datei (Ordner public/)
    const response = await fetch(`i18n/${this.prefix}-${language}.json`);
    this._dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    // die Sprache der Seite (Screenreader, Silbentrennung ...)
    document.documentElement.lang = language;
    await DeviceStorage.set({ key: `${this.prefix}.language`, value: language });
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO']; undefined, falls nicht vorhanden
  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: die Pluralform ("one", "other" ...), nach den
      // Regeln der Sprache; der Schlüssel _zero hat, sofern vorhanden, bei 0 Vorrang
      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);
    // ein unbekannter Schlüssel wird unverändert angezeigt: So sehen wir sofort, was fehlt
    if (text === undefined) return key;
    // {{name}} -> der Wert des Parameters name
    return text.replace(/\{\{(\w+)\}\}/g, (all, name: string) => String(params[name] ?? all));
  }
}
  • Zeile 25: die Sprachen der Anwendung;
  • Zeile 28: der Typ eines Wörterbuchs – ein Objekt, bei dem jede Eigenschaft entweder Text oder ein weiteres Wörterbuch ist (der Typ ist rekursiv: Er verweist auf sich selbst);
  • Zeilen 30–33: Die Übersetzungen speichern die aktuelle Sprache und ihr Wörterbuch in Variablen. Eine einfache Klasse, kein Service [@Injectable]: Jeder Nutzer erstellt sie mit seinem eigenen Präfix (Zeile 36; Beispiel 25 hat seine eigenen Wörterbücher, [ex25-fr.json] ...). Sie wird der Seite von einer „Factory“ bereitgestellt (wird später behandelt);
  • Zeile 36: [private readonly prefix] in den Parametern des Konstruktors deklariert UND initialisiert ein Feld: eine Abkürzung von [TypeScript];
  • Zeilen 40–44: die Ausgangssprache: die auf dem Gerät gespeicherte (das Plugin [@capacitor/preferences] aus Beispiel 20), andernfalls die Sprache des Telefons ([navigator.language]: „en-US“, wovon die ersten beiden Buchstaben behalten werden), sofern bekannt; andernfalls Englisch;
  • Zeilen 46–54: Sprache wechseln: das Wörterbuch mit [fetch] lesen, der Funktion von [JavaScript] , die eine Adresse liest (hier eine mit der Anwendung ausgelieferte Datei) und ein [Promise] zurückgibt, das die Antwort darstellt; deren JSON-Inhalt dekodieren ([response.json()], ein weiteres [Promise]); das Wörterbuch und die Sprache in den jeweiligen Feldern speichern; die Sprache der Seite aktualisieren (das Attribut [lang] des Tags [<html>], das für Screenreader nützlich ist); die Auswahl auf dem Gerät speichern. Wir hätten den HTTP-Client von [Angular] (Beispiel 22) verwenden können: [fetch] vermeidet die Abhängigkeit von ihm in einer einfachen Klasse;
  • Zeilen 57–63: Suche nach einem Schlüssel „HOME.HELLO“ im Wörterbuch: Wir steigen Teil für Teil ([split('.')]) durch die verschachtelten JSON-Objekte hinab. [typeof node === 'object'] ist eine Typprüfung, die den Typ der Variablen in dem Zweig, in dem sie wahr ist, „eingrenzt“: [TypeScript] weiß dann, dass [node] ein Wörterbuch ist. Das Lesen des Signals ([this._dictionary()], Zeile 58) ist unerlässlich: Ein Template, das [t()] aufruft, liest das Signal auf diese Weise und wird aktualisiert, wenn sich das Wörterbuch ändert;
  • Zeilen 65–79: die Übersetzung. Bei einem Plural (ein numerischer Parameter [count]) liefert [Intl.PluralRules] die Pluralform gemäß den Regeln der Sprache: [select(n)] ergibt [one] oder [other] (andere Sprachen kennen auch [two], [few], [many]). Im Französischen sind 0 und 1 Singular ([one]); im Englischen nur 1. Der Schlüssel [_zero] hat, falls vorhanden, Vorrang vor 0 (Zeile 72), genau wie bei [i18next]. Ein unbekannter Schlüssel wird unverändert angezeigt (Zeile 76): So sieht man sofort, was fehlt. Schließlich (Zeile 78) wird jedes [{{name}}] durch den Wert des Parameters ersetzt: ein regulärer Ausdruck [/\{\{(\w+)\}\}/g] und eine Funktion, die jeden Treffer ([all]) und den in Klammern erfassten Namen ([name]) erhält.

Warum nicht das offizielle [Angular]-Werkzeug verwenden? [Angular] hat ein eigenes Internationalisierungssystem ([@angular/localize]): Man markiert die Texte der Templates ([<p i18n>Hello</p>]), extrahiert die Übersetzungen in Dateien, und die Kompilierung erzeugt EINE Anwendung pro Sprache. Das ist die beste Lösung für eine Website, deren gesamte Texte im Voraus bekannt sind. Sie wechselt die Sprache jedoch nicht „im laufenden Betrieb“, und unser Server liefert Schlüssel („ERRORS.LOGIN_TAKEN“), die zur Laufzeit übersetzt werden müssen: Ein Wörterbuch, das über den Schlüssel abgefragt wird, eignet sich dafür weit besser und erlaubt es, Wörterbücher mit anderen Clients zu teilen. Es gibt dafür auch Bibliotheken für [Angular] ([ngx-translate], [Transloco]): Unser Service ist eine minimale Version davon.

7.1.3. Die übersetzte Seite

// =========================================================================
// src/app/ex21-i18n/ex21.page.ts - eine Anwendung in zwei Sprachen
// -------------------------------------------------------------------------
//   - die TEXTE der Anwendung: die Wörterbücher (translations.ts),
//     der Seite per Dependency Injection bereitgestellt (providers);
//   - die Datumsangaben und die Beträge: das Objekt Intl von JavaScript, in der
//     aktuellen Sprache (siehe Beispiel 09);
//   - die Texte von Ionic SELBST (der Kalender): das Attribut locale
//     von <ion-datetime> und seine Schaltflächen, übersetzt durch unsere Wörterbücher.
// Ein Sprachwechsel übersetzt den ganzen Bildschirm neu, ohne Neustart.
// =========================================================================

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';

// was der RdvMedecins-Server zurückgeben würde (siehe das Kapitel zur Blackbox)
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',
  // ein für die Seite SPEZIFISCHER Provider: die Übersetzungen der Wörterbücher 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();

  // Formatierung in der AKTUELLEN Sprache: wird neu berechnet, wenn sie sich ändert
  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),
  );
  // die Sprache von ion-datetime: ein vollständiges "Locale" (Sprache-Land)
  readonly locale = computed(() => (this.tr.language() === 'fr' ? 'fr-FR' : 'en-US'));

  constructor() {
    addIcons({ calendarOutline });
    this.tr.start();
    // der Titel des Dokuments (Browser-Tab), übersetzt: ein Effect,
    // der erneut ausgeführt wird, wenn sich die Sprache ändert
    const title = inject(Title);
    effect(() => title.setTitle(this.tr.t('APP.TITLE')));
  }

  // das Segment der oberen Leiste: Sein Wert (vom Typ SegmentValue: eine
  // Zeichenkette oder eine Zahl) ist die gewählte Sprache
  chooseLanguage(value: SegmentValue | undefined): void {
    this.tr.changeLanguage(String(value));
  }
}
<!-- ======================================================================
     ex21.page.html - eine Seite in zwei Sprachen
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('APP.TITLE') }}</ion-title>
    <!-- die Sprachen: ein "Segment", Schaltflächen, von denen nur eine gewählt ist -->
    <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: wählt die Pluralform und ersetzt {{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 />
      <!-- die Schaltfläche id="calendar" öffnet den modalen Dialog 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: Der Inhalt wird erst erzeugt, wenn sich der Dialog öffnet -->
        <ng-template>
          <!-- locale: die Monate und die Tage in der aktuellen Sprache (Intl);
               firstDayOfWeek: Montag (1) auf Französisch, Sonntag (0) auf Englisch -->
          <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>
      <!-- der Schlüssel des Servers IST ein Schlüssel des Wörterbuchs; params liefert seine Parameter -->
      @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>
  • Zeilen 25–28 (.ts): was der Server für [RdvMedecins] zurückgeben würde: ein HTTP-Code, ein Schlüssel und seine Parameter;
  • Zeile 38 (.ts): ein Provider, der SPEZIFISCH für die Seite gilt: [providers] im Dekorator [@Component] erstellt eine Instanz der Übersetzungen für diese Seite (und ihre Komponenten), die zusammen mit ihr zerstört wird. [useFactory] liefert die Funktion, die sie samt ihrem Präfix erstellt;
  • Zeilen 40–42 (.ts): die Größe der Sprachauswahl und die des Kalenderfensters (ein Dialogfeld, das auf seinen Inhalt zugeschnitten ist, statt einer ganzen Seite);
  • Zeile 47 (.ts): die Übersetzungen, als Service bezogen;
  • Zeilen 54–59 (.ts): Datum und Preis, in der aktuellen Sprache formatiert von [Intl.DateTimeFormat] ([dateStyle: 'full']: „Tuesday, October 6, 2026“, „mardi 6 octobre 2026“) und [Intl.NumberFormat] ([style: 'currency']: „€1,234.50“, „1 234,50 €“). Dies sind berechnete Signals: Sie erkennen die Sprache und werden bei deren Änderung neu berechnet. (Die Pipes [date] und [currency] von [Angular] akzeptieren ebenfalls eine Sprache als Parameter, doch dann müssen die Regeln jeder Sprache hinterlegt werden, wie es [main.ts] für Französisch tut.)
  • Zeile 61 (.ts): die Sprache des Kalenders im Format Sprache-Land, das von [<ion-datetime>] erwartet wird;
  • Zeile 65 (.ts): die Ausgangssprache;
  • Zeilen 68–69 (.ts): der Dokumenttitel (der Browser-Tab), übersetzt: der Service [Title] von [Angular], aufgerufen durch einen Effekt, der bei einem Sprachwechsel erneut ausgeführt wird;
  • Zeilen 74–76 (.ts): Sprachauswahl;
  • Zeile 10 (html): der Seitentitel, übersetzt;
  • Zeilen 12–16 (html): die Sprachauswahl in der oberen Leiste: ein [<ion-segment>], bestehend aus Schaltflächen, von denen nur eine ausgewählt ist ([value]), das Gegenstück zum [SegmentedButton] von [Flutter];
  • Zeilen 23–25 (HTML): parametrisierter Text. Datum und Preis, bereits formatiert, werden als Parameter übergeben;
  • Zeile 27 (html): [count] wählt die Pluralform aus und ersetzt [{{count}}];
  • Zeilen 34–47 (html): der Kalender in einem modalen Fenster ([<ion-modal>]), das von der Schaltfläche geöffnet wird, deren [id] von seinem Attribut [trigger] angegeben wird. Sein Inhalt in einem [<ng-template>] wird erst beim Öffnen des Fensters erstellt. [<ion-datetime>] formatiert die Monate und Tage mit [Intl] in der Sprache, die sein Attribut [[locale]] angibt; [[firstDayOfWeek]]: Die Woche beginnt im Französischen am Montag und im Englischen am Sonntag. Seine Schaltflächen („Done“, „Cancel“ standardmäßig) werden von [locale] nicht übersetzt: [[doneText]] und [[cancelText]] erhalten die Texte aus unseren Wörterbüchern. Das war das Paket [flutter_localizations] zusammen mit [Flutter];
  • Zeilen 58–61 (html): was der Server von [RdvMedecins] zurückgeben würde. Der Schlüssel des Servers IST ein Wörterbuchschlüssel; seine Parameter sind die des Textes.

7.1.4. Die Ausgabe

Auf Englisch (links); auf Französisch nach einem Hinzufügen (Mitte); der Kalender auf Französisch (rechts):

Ein Sprachwechsel übersetzt den gesamten Bildschirm neu, ohne Neustart und ohne Anfragen an den Server: Sprache und Wörterbuch sind Signals, und alles, was sie liest (Template-Texte, Datum, Preis, Titel), zieht nach. Die gewählte Sprache wird auf dem Gerät gespeichert: Starten Sie die App neu (im Browser: die Seite neu laden), und sie öffnet sich in der zuletzt gewählten Sprache.