Skip to main content

Der vollständige Leitfaden zur React-Internationalisierung

Von null bis mehrsprachig: Richten Sie i18n in Ihrer React-App ein und automatisieren Sie anschließend Übersetzungen mit KI.

1

Pakete installieren

Sie benötigen drei Pakete: react-i18next (die React-Bindings), i18next (die Kernbibliothek) und optional i18next-browser-languagedetector zur automatischen Erkennung der Locale.

react-i18next stellt React-Hooks und -Komponenten bereit. i18next ist die Kern-Engine für das Laden von Übersetzungen, die Interpolation und Pluralbildung. Das Spracherkennungs-Plug-in liest automatisch die Spracheinstellung des Browsers.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

i18n-Instanz konfigurieren

Erstellen Sie eine i18n-Konfigurationsdatei, die i18next mit Ihrer Standardsprache, den Übersetzungsressourcen und der Plug-in-Kette initialisiert. Diese Datei muss am Einstiegspunkt Ihrer App importiert werden, bevor eine Komponente gerendert wird.

src/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)  // Must come before .init()
  .init({
    fallbackLng: 'en',
    debug: process.env.NODE_ENV === 'development',
    interpolation: {
      escapeValue: false,  // React already escapes
    },
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },
  });

export default i18n;
Der Fehler „You will need to pass in an i18next instance by using initReactI18next“ bedeutet, dass Sie i18n.use(initReactI18next) nicht vor i18n.init() aufgerufen haben. Der Aufruf .use() muss vor .init() erfolgen.
3

App mit I18nextProvider umschließen

Importieren Sie Ihre i18n-Konfigurationsdatei im Stammverzeichnis der App und umschließen Sie Ihren Komponentenbaum mit I18nextProvider. Andernfalls gibt useTranslation() anstelle übersetzter Texte die unverarbeiteten Schlüssel zurück.

src/main.tsx
import React, { Suspense } from 'react';
import ReactDOM from 'react-dom/client';
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';  // Import your config
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Suspense fallback={<div>Loading...</div>}>
      <I18nextProvider i18n={i18n}>
        <App />
      </I18nextProvider>
    </Suspense>
  </React.StrictMode>
);
Wenn Übersetzungen unverarbeitete Schlüssel wie „welcome“ statt „Welcome to our app“ anzeigen, fehlt meist der I18nextProvider oder die i18n-Konfigurationsdatei wurde nicht importiert.
4

Übersetzungsdateien erstellen

Erstellen Sie für jede Sprache eine JSON-Datei. Gliedern Sie Zeichenfolgen mit verschachtelten Schlüsseln nach Funktion oder Seite. Verwenden Sie Ihre Ausgangssprache, üblicherweise Englisch, als einzige maßgebliche Quelle.

public/locales/en/translation.json
// public/locales/en/translation.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {{name}}!",
  "cart": {
    "itemCount_one": "{{count}} item",
    "itemCount_other": "{{count}} items"
  }
}

// public/locales/de/translation.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "itemCount_one": "{{count}} Artikel",
    "itemCount_other": "{{count}} Artikel"
  }
}
Benennen Sie Schlüssel nach ihrer Bedeutung und nicht nach ihrer Position: „cart.itemCount“ ist besser als „homepageCartLabel“. Schlüssel sollten eine Neugestaltung der Benutzeroberfläche überdauern.
5

Übersetzungen in Komponenten verwenden

Rufen Sie useTranslation() in einer beliebigen Komponente auf, um die Funktion t() zu erhalten. Verwenden Sie sie für einfache Zeichenfolgen, interpolierte Variablen und mit der Trans-Komponente in JSX eingebettete Übersetzungen.

Greeting.tsx
import { useTranslation } from 'react-i18next';

function Greeting({ userName }: { userName: string }) {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('greeting', { name: userName })}</h1>
      <nav>
        <a href="/">{t('nav.home')}</a>
        <a href="/about">{t('nav.about')}</a>
      </nav>
    </div>
  );
}
Trans component for JSX
import { Trans, useTranslation } from 'react-i18next';

// For JSX inside translations:
// "terms": "By signing up, you agree to our <link>Terms</link>."

function SignUp() {
  const { t } = useTranslation();
  return (
    <Trans i18nKey="terms" components={{
      link: <a href="/terms" className="underline" />
    }} />
  );
}
Dynamische Schlüssel wie t(`error.$'{code}'`) funktionieren zur Laufzeit, können von Werkzeugen wie i18next-scanner jedoch nicht statisch extrahiert werden. Wenn Sie Extraktionswerkzeuge verwenden, führen Sie dynamische Schlüssel ausdrücklich auf oder verwenden Sie einen Kommentarthinweis.
6

Pluralformen und Variablen verarbeiten

i18next verarbeitet Pluralformen anhand der CLDR-Regeln – nicht nur Singular und Plural. Arabisch hat sechs Formen (zero, one, two, few, many, other), Japanisch eine (other). Definieren Sie alle erforderlichen Formen in Ihren Übersetzungsdateien; i18next wählt automatisch die richtige aus.

Plural forms by language
// English: 2 forms (one, other)
{
  "itemCount_one": "{{count}} item",
  "itemCount_other": "{{count}} items"
}

// Arabic: 6 forms (zero, one, two, few, many, other)
{
  "itemCount_zero": "لا عناصر",
  "itemCount_one": "عنصر واحد",
  "itemCount_two": "عنصران",
  "itemCount_few": "{{count}} عناصر",
  "itemCount_many": "{{count}} عنصرًا",
  "itemCount_other": "{{count}} عنصر"
}

// Japanese: 1 form (other)
{
  "itemCount_other": "{{count}}個のアイテム"
}
Verwenden Sie zur Erkennung des Singulars niemals den fest codierten Vergleich count === 1. Sprachen wie Französisch behandeln 0 als Singular. Russisch, Arabisch und Polnisch besitzen Formen, die es im Englischen nicht gibt. Lassen Sie i18next die Pluralregeln verarbeiten.
7

Sprachwechsel und -erkennung hinzufügen

Erstellen Sie eine Sprachauswahl, die i18n.changeLanguage() aufruft. Kombinieren Sie sie mit der Spracherkennung des Browsers, um beim ersten Besuch automatisch die bevorzugte Sprache zu erkennen, und speichern Sie anschließend die ausdrückliche Auswahl.

LanguageSwitcher.tsx
import { useTranslation } from 'react-i18next';

const LANGUAGES = [
  { code: 'en', label: 'English' },
  { code: 'de', label: 'Deutsch' },
  { code: 'ja', label: '日本語' },
  { code: 'es', label: 'Español' },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  return (
    <select
      value={i18n.language}
      onChange={(e) => i18n.changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>{label}</option>
      ))}
    </select>
  );
}
Bei SSR (Next.js, Remix) erkennt der Server möglicherweise eine andere Sprache als der Client, da dem Server keine Browsereinstellungen vorliegen. Dadurch entsteht eine Abweichung bei der Hydration. Lösung: Übergeben Sie die erkannte Locale vom Server als Prop oder Cookie an den Client, damit beide dieselbe Sprache rendern.
8

Übersetzungen automatisieren

Wenn Ihre i18n-Einrichtung abgeschlossen ist, übersetzen Sie Ihre Locale-Dateien mit KI. Bitten Sie Ihren KI-Assistenten in Ihrer IDE, Ihre Ausgangsdatei zu übersetzen, oder verwenden Sie die CLI von i18n Agent in Ihrer CI/CD-Pipeline.

Terminal
# In your IDE, ask your AI assistant:
> Translate public/locales/en/translation.json to German, Japanese, and Spanish

✓ de/translation.json created (1.2s)
✓ ja/translation.json created (1.5s)
✓ es/translation.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate public/locales/en/translation.json --lang de,ja,es
Übersetzen Sie schrittweise: Wenn Sie Ihrer Ausgangsdatei neue Schlüssel hinzufügen, übersetzen Sie nur die Änderungen, statt alle Dateien neu zu erzeugen. So bleiben von Menschen geprüfte Übersetzungen erhalten.

Übersetzungsqualität automatisieren

Erkennen Sie mit i18n-validate fehlende Schlüssel und beschädigte Platzhalter vor der Veröffentlichung. Testen Sie Ihre Benutzeroberfläche mit i18n-pseudo und simulierten Übersetzungen, bevor echte Übersetzungen vorliegen.

Häufige Fallstricke

Übersetzungen zeigen unverarbeitete Schlüssel

Mögliche Ursachen: I18nextProvider fehlt, die i18n-Konfiguration wurde im Stammverzeichnis der App nicht importiert, der Namensraum ist nicht geladen oder Übersetzungen werden noch asynchron geladen. Suchen Sie bei debug: true in der Browserkonsole nach Hinweisen.

Suspense-Fehler ohne Fallback

„A component suspended while responding to synchronous input“ – fügen Sie um Ihre App eine '&lt;Suspense&gt;'-Grenze hinzu oder setzen Sie useSuspense: false in der Initialisierungskonfiguration von i18next.

Abweichung bei der SSR-Hydration

Der Server rendert in einer Locale, der Client führt die Hydration in einer anderen durch. Stellen Sie sicher, dass beide dieselbe Locale-Quelle verwenden: Übergeben Sie sie als Prop vom Server und verlassen Sie sich nicht allein auf die Browsererkennung.

Keine Autovervollständigung für Übersetzungsschlüssel

Erweitern Sie das i18next-Modul um Ihren Ressourcentyp: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Dadurch erhalten Sie typsichere t()-Aufrufe mit Autovervollständigung.

Empfohlene Dateistruktur

Project Structure
my-react-app/
├── public/
│   └── locales/
│       ├── en/
│       │   ├── translation.json    # Default namespace
│       │   ├── common.json         # Shared strings
│       │   └── dashboard.json      # Feature namespace
│       ├── de/
│       │   ├── translation.json
│       │   ├── common.json
│       │   └── dashboard.json
│       └── ja/
│           └── ...
├── src/
│   ├── i18n.ts                     # i18n configuration
│   ├── main.tsx                    # App entry with Provider
│   ├── App.tsx
│   └── components/
│       └── LanguageSwitcher.tsx
└── package.json

Auch übersetzen:

i18n Agent jetzt testen

Legen Sie Ihre Übersetzungsdatei hier ab

JSON, YAML, PO, XML, CSV, Markdown, Properties

oder zum Auswählen klicken

Zielsprachen

Keine Registrierung erforderlichSofortiges Angebot

Häufig gestellte Fragen