Skip to content

6. Internationalisierung

6.1. Beispiel 21: Eine zweisprachige Anwendung

[React] hat kein Übersetzungssystem. Die am häufigsten verwendete Bibliothek ist [i18next], die über [react-i18next] mit [React] verbunden wird.

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, datetime(dateStyle: full)}}.",
    "PRICE": "Une consultation coûte {{price, currency(EUR)}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} 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, datetime(dateStyle: full)}}.",
    "PRICE": "A consultation costs {{price, currency(EUR)}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} 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 aus verschachtelten Namen: [HOME.HELLO]. Es sind dieselben Wörterbücher wie in den vorherigen Lektionen, mit zwei Besonderheiten von [i18next]:

  • Parameter werden als [{{name}}] geschrieben; ein Parameter kann sprachabhängig formatiert werden: [{{date, datetime(dateStyle: full)}}] (ein Datum, mit den Optionen von [Intl.DateTimeFormat]), [{{price, currency(EUR)}}] (ein Betrag in Euro);
  • Plurale: [i18next] wählt die Form automatisch anhand des Parameters [count] und der Sprachregeln aus: [APPOINTMENTS_one] oder [APPOINTMENTS_other] sowie [APPOINTMENTS_zero] für null, falls vorhanden. Polnisch, Arabisch und andere Sprachen haben abweichende Formen ([_few], [_many]), die [i18next] erkennt.

6.1.2. Die Konfiguration

// =========================================================================
// 21-i18n/src/i18n/i18n.ts - die Konfiguration von i18next
// -------------------------------------------------------------------------
// i18next ist die meistverwendete Übersetzungsbibliothek in JavaScript;
// react-i18next verbindet sie mit React. Wir übergeben ihr:
//   - ein WÖRTERBUCH pro Sprache (fr.json, en.json), in dem jeder Text einen
//     SCHLÜSSEL hat ("HOME.HELLO"); die Parameter werden {{name}} geschrieben;
//     {{date, datetime(...)}} und {{price, currency(EUR)}} formatieren
//     ein Datum oder einen Betrag gemäß der Sprache (mit der Intl-API);
//   - die Anfangssprache (die in localStorage gespeicherte, sonst die
//     des Browsers, sonst Englisch) und die Ersatzsprache.
// In einer Komponente liefert t('HOME.HELLO', { name: 'Marie' }) den Text
// der AKTUELLEN Sprache; ein Sprachwechsel ruft die Komponenten, die
// t verwenden, erneut auf, und die ganze Seite wird neu übersetzt.
//
// 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 vom Server nichts mehr.
// =========================================================================

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';

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

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

// bei jedem Sprachwechsel: Sie wird gespeichert, und das Attribut lang
// der Seite wird aktualisiert (nützlich für Screenreader und Rechtschreibprüfungen)
i18n.on('languageChanged', (language) => {
  localStorage.setItem(LANGUAGE_KEY, language);
  document.documentElement.lang = language;
});

// use(initReactI18next): i18next benachrichtigt React über Sprachwechsel
i18n.use(initReactI18next).init({
  // die Wörterbücher sind Teil des Codes der Anwendung: keine Anfrage
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: initialLanguage(),
  fallbackLng: 'en', // ein im Französischen fehlender Schlüssel: Es wird der englische verwendet
  // React maskiert bereits alles, was es anzeigt: i18next muss das nicht tun
  interpolation: { escapeValue: false },
});

export default i18n;
  • Zeilen 23–24: Die Wörterbücher sind Teil des Anwendungscodes: Es sind JSON-Module, die als Objekte importiert werden ([resolveJsonModule], siehe [tsconfig.json]);
  • Zeilen 30–36: die Ausgangssprache: die in [localStorage] gespeicherte, andernfalls Französisch, wenn die Sprache des Browsers Französisch ist, sonst Englisch;
  • Zeilen 40–43: Bei jedem Sprachwechsel wird die Sprache gespeichert und das Attribut [lang] der Seite aktualisiert (nützlich für Screenreader und Rechtschreibprüfungen);
  • Zeilen 46–53: die Konfiguration: die Wörterbücher ([translation] ist der Name des standardmäßigen Schlüsselraums), die Ausgangssprache, die Ausweichsprache (fehlt ein Schlüssel im Französischen, wird Englisch verwendet) und [escapeValue: false]: [React] maskiert bereits alles, was es anzeigt.
// =========================================================================
// 21-i18n/src/main.tsx - der Import von i18n/i18n.ts genügt, um i18next zu konfigurieren,
// vor der ersten Anzeige
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import './i18n/i18n';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

Der Import von [i18n/i18n.ts] genügt, um [i18next] vor der ersten Anzeige zu konfigurieren.

6.1.3. Die übersetzte Seite

// =========================================================================
// 21-i18n/src/App.tsx - eine übersetzte Seite
// -------------------------------------------------------------------------
//   - const { t, i18n } = useTranslation(): die Übersetzungsfunktion und
//     das i18next-Objekt (i18n.language: die aktuelle Sprache);
//   - t('KEY')                        ein Text;
//   - t('KEY', { name: ... })         ein Text mit Parametern;
//   - t('KEY', { count: n })          ein Text im Plural: i18next wählt
//                                     den Schlüssel KEY_zero, KEY_one oder KEY_other;
//   - i18n.changeLanguage('fr')       wechselt die Sprache: Die ganze Seite wird
//                                     neu übersetzt.
// =========================================================================

import { useEffect, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from './i18n/i18n';

// was der RdvMedecins-Server zurückliefern würde (vgl. Kapitel über die Blackbox)
const SERVER_RESPONSES = [
  { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
  { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
];

export default function App() {
  const { t, i18n } = useTranslation();
  const [count, setCount] = useState(2);
  const [today] = useState(() => new Date());

  // der Titel des Tabs folgt der Sprache
  useEffect(() => {
    document.title = t('APP.TITLE');
  }, [t]);

  return (
    <div className="container py-4" style={{ maxWidth: 720 }}>
      <div className="d-flex justify-content-between align-items-center mb-3">
        <h1 className="h3 mb-0">{t('APP.TITLE')}</h1>
        <div className="btn-group btn-group-sm" role="group" aria-label={t('APP.LANGUAGE')}>
          {LANGUAGES.map((l) => (
            <button key={l} className={`btn ${i18n.language === l ? 'btn-primary' : 'btn-outline-primary'}`}
                    onClick={() => i18n.changeLanguage(l)}>
              {l.toUpperCase()}
            </button>
          ))}
        </div>
      </div>

      <div className="card p-3 mb-3">
        <p>{t('HOME.HELLO', { name: 'Marie' })}</p>
        {/* das Datum und der Betrag werden vom Wörterbuch in der aktuellen Sprache formatiert */}
        <p>{t('HOME.TODAY', { date: today })}</p>
        <p>{t('HOME.PRICE', { price: 1234.5 })}</p>
        {/* count: wählt die Pluralform und ersetzt {{count}} */}
        <p className="fw-bold">{t('HOME.APPOINTMENTS', { count })}</p>
        <div className="d-flex gap-2">
          <button className="btn btn-sm btn-outline-success" onClick={() => setCount(count + 1)}>{t('HOME.ADD')}</button>
          <button className="btn btn-sm btn-outline-secondary" disabled={count === 0} onClick={() => setCount(count - 1)}>
            {t('HOME.REMOVE')}
          </button>
        </div>
      </div>

      <div className="card p-3">
        <h2 className="h6">{t('SERVER.TITLE')}</h2>
        <p>{t('SERVER.EXPLANATION')}</p>
        <ul className="mb-0">
          {SERVER_RESPONSES.map((r) => (
            // der Schlüssel des Servers IST ein Schlüssel des Wörterbuchs; params liefert dessen Parameter
            <li key={r.key}>
              <code>{r.statusCode} {r.key}</code>
              <br />&rarr; {t(r.key, r.params)}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}
  • Zeile 25: der Hook von [react-i18next]: [t], die Übersetzungsfunktion, und [i18n], das [i18next]-Objekt ([i18n.language] ist die aktuelle Sprache). Die Komponente wird beim Sprachwechsel aufgerufen;
  • Zeilen 30–32: Der Titel des Tabs folgt der Sprache: Die Funktion [t] ändert sich mit der Sprache;
  • Zeile 41: Sprache wechseln: Die gesamte Seite wird neu übersetzt, ohne dass Anfragen an den Server gesendet werden;
  • Zeile 49: Text mit Parametern;
  • Zeilen 51–52: ein Datum und ein Betrag, vom Wörterbuch in der aktuellen Sprache formatiert;
  • Zeile 54: eine Pluralform;
  • Zeile 71: Der vom Server [RdvMedecins] gesendete Schlüssel IST ein Schlüssel des Wörterbuchs (siehe nächstes Kapitel); [params] liefert seine Parameter.

Image

Auf Englisch, nach dem Entfernen von zwei Terminen:

Image

Auf der Client-Seite funktioniert dies nach demselben Prinzip wie im [NestJS]-Kurs (Wörterbücher [i18n/*.json] + Hilfsfunktion [{{t}}]); die Übersetzung findet jedoch nun im Browser statt, und der Sprachwechsel erfordert keinerlei Interaktion mit dem Server mehr.