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 />→ {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.

Auf Englisch, nach dem Entfernen von zwei Terminen:

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.