Skip to content

6. Internationalisierung

6.1. Beispiel 21: Eine zweisprachige Anwendung

Die Anwendung [RdvMedecins] ist auf Französisch und Englisch verfügbar. Im [NestJS]-Kurs übersetzte der Server die Seiten, bevor er sie sendete. Jetzt werden die Seiten im Browser erzeugt: Der Client übersetzt sie, und der Sprachwechsel erfordert keinerlei Interaktion mehr mit dem Server.

[Angular] hat ein eigenes Übersetzungssystem, [@angular/localize], das für jede Sprache eine kompilierte Anwendung erzeugt: Der Sprachwechsel besteht daher einfach im Laden einer anderen Anwendung. Wir verwenden stattdessen die Bibliothek [ngx-translate], die am häufigsten eingesetzte neben [Angular], die zur Laufzeit übersetzt: Ein einziger Klick genügt, um die gesamte Seite neu zu übersetzen.

1
2
3
4
5
6
7
8
21-i18n/src/app/
├── i18n/
│   ├── fr.json          the French dictionary
│   ├── en.json          the English dictionary
│   ├── i18n.ts          the configuration of ngx-translate
│   └── plural.pipe.ts   the choice of the plural
├── app.ts
└── app.html

Die Bibliothek wird in der Datei [package.json] des Workspace deklariert:

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

6.1.1. Wörterbücher

{
  "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:"
  }
}
  • Jeder Text hat einen Schlüssel , der aus den Namen der aufeinanderfolgenden Ebenen besteht: [HOME.HELLO], [ERRORS.LOGIN_TAKEN] ... Der Code und die Templates enthalten keinen Text mehr, nur noch Schlüssel;
  • Zeile 7: Parameter werden zwischen doppelten geschweiften Klammern geschrieben: [{{name}}];
  • Zeilen 10–14: Pluralformen, unter demselben Schlüssel zusammengefasst (siehe unten);
  • Zeilen 18–21: Die Schlüssel [ERRORS.*] sind diejenigen, die der Server [RdvMedecins] in seinen Fehlerantworten zurückgibt (nächstes Kapitel). Der Server gibt keinen Text zurück, sondern einen Schlüssel; der Client übersetzt ihn in die Sprache des Benutzers.

6.1.2. Die Konfiguration

// =========================================================================
// 21-i18n/src/app/i18n/i18n.ts - die Konfiguration von ngx-translate
// -------------------------------------------------------------------------
// ngx-translate ist die am weitesten verbreitete Übersetzungsbibliothek für
// Angular. Wir versorgen sie mit:
//   - einem WÖRTERBUCH pro Sprache (fr.json, en.json), in dem jeder Text einen
//     SCHLÜSSEL hat ("HOME.HELLO"); die Parameter werden {{name}} geschrieben;
//   - einem LOADER (TranslateLoader), der das Wörterbuch einer
//     Sprache liefert. Unserer holt sie aus dem Code der Anwendung (Import von
//     JSON-Dateien); ein anderer könnte sie herunterladen;
//   - der Startsprache (die in localStorage gespeicherte, sonst die
//     des Browsers, sonst Englisch) und der Ersatzsprache.
// In den Templates zeigt {{ 'HOME.HELLO' | translate: { name: 'Marie' } }}
// den Text der AKTUELLEN Sprache an; ein Sprachwechsel aktualisiert
// die gesamte Seite.
//
// Es ist auf der Client-Seite dasselbe Prinzip wie im NestJS-Kurs (Wörterbücher
// i18n/*.json + Helper {{t}}) - aber die Übersetzung erfolgt jetzt im
// Browser, und ein Sprachwechsel verlangt dem Server nichts mehr ab.
//
// (Angular hat auch ein eigenes System, @angular/localize, das EINE
// kompilierte Anwendung pro Sprache erstellt: Die Sprache lässt sich dann nur
// durch einen Seitenwechsel ändern. ngx-translate dagegen übersetzt zur Laufzeit.)
// =========================================================================

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

// der Loader der Wörterbücher
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', // ein auf Französisch fehlender Schlüssel: der englische wird verwendet
    lang: initialLanguage(),
  });
}
  • Zeilen 29–30: Die Wörterbücher werden als Module importiert; sie sind Teil des Anwendungscodes. Dies ermöglicht die Option [resolveJsonModule] in der Datei [tsconfig.json];
  • Zeile 34: der Schlüssel, unter dem die gewählte Sprache in [localStorage] gespeichert wird (Beispiel 20);
  • Zeilen 37–41: der Loader für die Wörterbücher: [ngx-translate] ruft ihn auf, um das Wörterbuch einer Sprache in Form eines Observables abzurufen. Unser Loader holt sie aus dem Code; ein anderer könnte sie vom Server herunterladen;
  • Zeilen 43–49: die Ausgangssprache: die, die der Benutzer zuletzt gewählt hat, andernfalls Französisch, wenn die Sprache des Browsers Französisch ist, sonst Englisch;
  • Zeilen 51–57: [provideTranslateService] stellt die Services von [ngx-translate] in der gesamten Anwendung bereit. [fallbackLang]: die Sprache, die für einen Schlüssel verwendet wird, der im aktuellen Wörterbuch fehlt.
// =========================================================================
// 21-i18n/src/main.ts
// -------------------------------------------------------------------------
// provideI18n(): ngx-translate (siehe app/i18n/i18n.ts).
// registerLocaleData(localeFr): die französischen Regeln der Pipes für Datum,
// Währung... (Englisch ist immer verfügbar).
// =========================================================================

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));
  • Zeile 15: Die Pipes [date] und [currency] (Beispiel 09) kennen die Regeln für Englisch; die für Französisch müssen registriert werden;
  • Zeile 17: Die Services von [ngx-translate] werden der Anwendung hinzugefügt.

6.1.3. Plurale

[ngx-translate] unterstützt keine Plurale. Eine kleine Pipe wählt die richtige Form aus:

// =========================================================================
// 21-i18n/src/app/i18n/plural.pipe.ts - die Pluralform wählen
// -------------------------------------------------------------------------
// ngx-translate behandelt keine Plurale. Das Wörterbuch liefert die
// Formen unter demselben Schlüssel ("APPOINTMENTS": { "zero", "one", "other" }) und
// diese Pipe wählt die richtige aus, abhängig von der Zahl und der Sprache:
//     {{ 'HOME.APPOINTMENTS' | plural: n : language | translate: { n } }}
// Intl.PluralRules kennt die Regeln jeder Sprache ("one" oder "other" im
// Englischen wie im Französischen, aber andere Formen im Polnischen, im Arabischen...).
// =========================================================================

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)}`;
  }
}
  • Zeilen 16–21: Die Pipe erhält einen Schlüssel ([HOME.APPOINTMENTS]), eine Zahl und eine Sprache; sie gibt den Schlüssel in der richtigen Form zurück ([HOME.APPOINTMENTS.one], zum Beispiel);
  • Zeile 18: Null hat ein eigenes Format („no appointment“);
  • Zeile 20: [Intl.PluralRules], vom Browser bereitgestellt, folgt den Regeln jeder Sprache: [one] oder [other] im Französischen und Englischen, aber andere Formen im Polnischen oder Arabischen. (Hinweis: Im Französischen ist 1,5 Singular; im Englischen ist es Plural.)

6.1.4. Die übersetzte Seite

// =========================================================================
// 21-i18n/src/app/app.ts - eine übersetzte Seite
// -------------------------------------------------------------------------
//   - 'KEY' | translate                    ein Text;
//   - 'KEY' | translate: { name: ... }     ein Text mit Parametern;
//   - date / currency with the language    ein Datum, ein Betrag, im Format
//                                          der aktuellen Sprache;
//   - translate.use('fr')                  wechselt die Sprache: die gesamte
//                                          Seite wird neu übersetzt.
// TranslateService.currentLang ist ein SIGNAL: die aktuelle Sprache.
// =========================================================================

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();

  // was der RdvMedecins-Server zurückgeben würde (siehe das Kapitel über die Blackbox)
  protected readonly serverResponses = [
    { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
    { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
  ];

  // translate.translate(key): ein SIGNAL, das der aktuellen Sprache folgt
  private readonly title = this.translate.translate('APP.TITLE');

  constructor() {
    // bei jedem Sprachwechsel: wir speichern sie und aktualisieren
    // das Attribut lang der Seite (nützlich für Screenreader, Rechtschreibprüfungen)
    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);
  }
}
  • Zeile 21: [TranslatePipe]: die Pipe [translate];
  • Zeile 25: [TranslateService]: der Hauptservice von [ngx-translate];
  • Zeile 26: [currentLang]: die aktuelle Sprache als Signal;
  • Zeilen 32–35: zwei Fehlerantworten, so wie der Server sie zurückgeben würde: ein Schlüssel und Parameter;
  • Zeile 38: [translate.translate(key)] gibt ein Signal zurück, das der Übersetzung des Schlüssels entspricht und der aktuellen Sprache folgt;
  • Zeilen 43–50: eine Aktion, die bei jedem Sprachwechsel ausgeführt wird: Die Sprache wird gespeichert (Zeile 46), das Attribut [lang] der Seite wird aktualisiert (Zeile 47; es wird von Screenreadern und Rechtschreibprüfungen verwendet) sowie der Titel des Tabs (Zeile 49);
  • Zeile 54: [use] ändert die aktuelle Sprache: Die gesamte Seite wird neu übersetzt.
<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>
    <!-- ein Parameter, der von einer anderen Pipe in der aktuellen Sprache berechnet wird -->
    <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 wählt den Schlüssel (zero, one, other), translate übersetzt ihn -->
    <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) {
        <!-- der Schlüssel des Servers IST ein Schlüssel des Wörterbuchs; params liefert seine Parameter -->
        <li><code>{{ r.statusCode }} {{ r.key }}</code><br>&rarr; {{ r.key | translate: r.params }}</li>
      }
    </ul>
  </div>
</div>
  • Zeile 3: ['APP.TITLE' | translate]: die Übersetzung des Schlüssels in der aktuellen Sprache;
  • Zeile 6: Die Schaltfläche der aktuellen Sprache wird hervorgehoben;
  • Zeile 14: ein parametrisierter Text: Die Pipe erhält ein Objekt, das den Wert jedes Parameters liefert;
  • Zeilen 16–17: Der Wert eines Parameters kann von einer anderen Pipe berechnet werden. Das letzte Argument von [date] und [currency] ist die Sprache: Datum und Betrag werden im französischen oder englischen Stil geschrieben;
  • Zeile 19: zwei verkettete Pipes: [plural] wählt den Schlüssel aus, und [translate] übersetzt ihn;
  • Zeile 34: Der vom Server zurückgegebene Schlüssel wird samt seinen Parametern übersetzt.

[npm start 21-i18n]; mit einem auf Französisch eingestellten Browser ist die Seite auf Französisch:

Image

Klicken Sie auf [EN] und dann auf „Remove one“:

Image

Laden Sie die Seite neu: Sie bleibt auf Englisch; die Sprache wurde gespeichert.