React-Lokalisierung mit i18next

Die Entwicklung einer React-Anwendung für ein globales Publikum erfordert eine robuste Internationalisierungsstrategie (i18n). react-i18next ist die beliebteste React-Lokalisierungsbibliothek, die auf dem bewährten i18next-Framework basiert. Dieser Leitfaden führt Sie durch alles, was Sie für die Lokalisierung Ihrer React-App benötigen – von der Ersteinrichtung bis zur produktionsreifen Automatisierung mit KI-gestützter Übersetzung.

Warum react-i18next für die React-Lokalisierung wählen?

react-i18next ist der De-facto-Standard für die React-Internationalisierung, dem Tausende von Produktionsanwendungen weltweit vertrauen. Hier erfahren Sie, warum Entwickler sich dafür entscheiden:

• Hooks-First API - Der useTranslation()-Hook bietet eine saubere, idiomatische React-Integration mit automatischem Re-Rendering bei Sprachwechsel.
• Umfangreiches Ökosystem - Plugins für Spracherkennung, HTTP-Backends, Caching und mehr. Erweitern Sie die Funktionalität, ohne das Rad neu zu erfinden.
• JSON-Übersetzungsformat - Verwendet Standard-JSON-Dateien, die einfach zu bearbeiten, versionskontrolliert und in Übersetzungstools sowie KI-Dienste zu integrieren sind.
• Namespace-Unterstützung - Organisieren Sie Übersetzungen in logischen Gruppen (auth, dashboard, errors) für bessere Wartbarkeit und Lazy Loading.
• SSR & Next.js bereit - Funktioniert nahtlos mit Server-Side Rendering, React Server Components und dem Next.js App Router.
• TypeScript-Unterstützung - Volle Typsicherheit für Übersetzungsschlüssel mit Autocomplete, wodurch fehlende Schlüssel bereits zur Kompilierzeit erkannt werden.

Installation

Installieren Sie react-i18next und die i18next-Kernbibliothek:

npm install react-i18next i18next

Optionale Plugins

Diese beliebten Plugins erweitern Ihr i18next-Setup um automatische Spracherkennung und nachgeladene Übersetzungen:

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Empfohlene Projektstruktur

Eine gut organisierte Projektstruktur sorgt dafür, dass Ihre Übersetzungen wartbar bleiben, wenn Sie weitere Sprachen hinzufügen:

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

JSON-Dateiformat für Übersetzungen

react-i18next verwendet verschachtelte JSON-Dateien für Übersetzungen. Schlüssel unterstützen Punktnotation, Interpolation mit {{variables}} und integrierte Pluralisierung:

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Verschachtelte Schlüssel - Organisieren Sie Übersetzungen hierarchisch (z. B. welcome.title, nav.home) für eine klare Struktur.
• Interpolation - Verwenden Sie die {{variableName}}-Syntax für dynamische Werte, die zur Laufzeit eingefügt werden.
• Pluralisierung - Fügen Sie _one- und _other-Suffixe (oder _zero, _two, _few, _many für komplexe Sprachen) für die automatische Pluralbehandlung hinzu.
• Kontext - Verwenden Sie bei Bedarf _male- und _female-Suffixe für geschlechtsspezifische Übersetzungen.

Konfiguration von i18next

i18next unterstützt zwei Hauptansätze zum Laden von Übersetzungen: HTTP-Backend (Lazy Loading) und gebündelte Ressourcen. Wählen Sie basierend auf den Anforderungen Ihrer App.

HTTP-Backend (empfohlen für große Apps)

Laden Sie Übersetzungen bei Bedarf aus JSON-Dateien auf Ihrem Server. Dies hält Ihr anfängliches Bundle klein und ist ideal für Apps mit vielen Sprachen oder großen Übersetzungsdateien:

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

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Gebündelte Ressourcen (einfacher Ansatz)

Importieren Sie Übersetzungen direkt in das Bundle. Am besten für kleinere Apps geeignet oder wenn Sie Übersetzungen sofort ohne Netzwerkanfragen verfügbar haben müssen:

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Initialisierung in Ihrer App

Importieren Sie die i18n-Konfigurationsdatei in den Einstiegspunkt Ihrer App, bevor Sie Komponenten rendern. Dies stellt sicher, dass Übersetzungen geladen werden, bevor Ihre Benutzeroberfläche gerendert wird:

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Übersetzen von React-Komponenten

react-i18next bietet zwei primäre APIs für die Übersetzung von Komponenten: den useTranslation-Hook für den programmatischen Zugriff und die Trans-Komponente für Rich Text mit JSX.

useTranslation-Hook

Der useTranslation-Hook ist die gängigste Methode, um in funktionalen Komponenten auf Übersetzungen zuzugreifen. Er stellt die t()-Funktion bereit und rendert automatisch neu, wenn sich die Sprache ändert:

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Trans-Komponente für Rich Text

Wenn Übersetzungen HTML- oder JSX-Elemente (fett, Links usw.) enthalten, verwenden Sie die Trans-Komponente. Sie bewahrt Ihren React-Komponentenbaum innerhalb der Übersetzungen:

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Umgang mit Pluralisierung

i18next handhabt Pluralformen automatisch basierend auf den ICU-Pluralregeln für jede Sprache. Übergeben Sie einen count-Parameter, und i18next wählt die korrekte Pluralform aus:

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Fügen Sie für Englisch _one- und _other-Suffixe zu Ihren Übersetzungsschlüsseln hinzu
• Für Sprachen mit komplexen Pluralregeln (Arabisch, Polnisch, Russisch) fügen Sie bei Bedarf _zero-, _two-, _few-, _many-Suffixe hinzu
• i18next wählt automatisch die korrekte Form basierend auf den CLDR-Pluralregeln der Zielsprache aus

Organisieren mit Namespaces

Mit Namespaces können Sie Übersetzungen nach Funktion oder Domäne in separate Dateien aufteilen. Dies verbessert die Wartbarkeit und ermöglicht das Lazy Loading von Übersetzungs-Bundles:

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Dynamischer Sprachwechsel

react-i18next macht den Sprachwechsel nahtlos. Rufen Sie i18n.changeLanguage() auf, und alle Komponenten, die useTranslation verwenden, rendern automatisch mit der neuen Sprache neu:

import { useTranslation } from "react-i18next";

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

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

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense und Lazy Loading

react-i18next lässt sich in React Suspense integrieren, um das asynchrone Laden von Übersetzungen elegant zu handhaben. Bei Verwendung des HTTP-Backends bietet Suspense einen sauberen Ladestatus, während Übersetzungen abgerufen werden:

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

TypeScript-typsichere Übersetzungsschlüssel

i18next unterstützt eine vollständige TypeScript-Integration. Durch die Erweiterung des i18next-Moduls erhalten Sie Autocomplete und eine Prüfung zur Kompilierzeit für alle Übersetzungsschlüssel – was Tippfehler und fehlende Übersetzungen verhindert:

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Server-Side Rendering mit Next.js

Für Next.js-Anwendungen, die den App Router verwenden, können Sie i18next sowohl auf Server- als auch auf Client-Komponenten nutzen. Erstellen Sie eine separate i18next-Instanz für serverseitige Übersetzungen, um das Teilen von Status zwischen Anfragen zu vermeiden:

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Erstellen Sie pro Anfrage eine neue i18next-Instanz auf dem Server, um Status-Lecks zwischen Benutzern zu verhindern
• Verwenden Sie dieselben JSON-Übersetzungsdateien sowohl für das Server- als auch für das Client-Rendering
• Erwägen Sie i18next-resources-to-backend oder next-intl als Alternativen für komplexe Next.js-Setups

Beschleunigen Sie die Übersetzung mit KI

Die Einrichtung von react-i18next ist nur die halbe Miete – Sie benötigen immer noch hochwertige Übersetzungen für jede Zielsprache. Das manuelle Übersetzen von Dutzenden von JSON-Dateien ist langsam, teuer und fehleranfällig. KI-gestützte Übersetzung ändert alles.

Warum l10n.dev für React i18next verwenden?

l10n.dev wurde speziell für Lokalisierungs-Workflows von Entwicklern entwickelt. Es versteht Ihre JSON-Übersetzungsdateien nativ und erstellt Übersetzungen, die sich natürlich anfühlen und nicht maschinell generiert wirken:

• Native JSON-Unterstützung — Laden Sie Ihre translation.json hoch und erhalten Sie perfekt formatierte, gebrauchsfertige JSON-Dateien zurück
• Kontextbewusste KI — Versteht die Domäne Ihrer App und bewahrt Fachbegriffe sowie die Markenstimme über Sprachen hinweg
• Interpolationssicher — Bewahrt {{variables}}, Plural-Suffixe (_one, _other) und verschachtelte Schlüsselstrukturen
• Stapelübersetzung — Übersetzen Sie in Sekunden, nicht in Tagen, in mehr als 10 Sprachen gleichzeitig
• CI/CD-Integration — Automatisieren Sie Übersetzungen als Teil Ihrer Build-Pipeline mit dem ai-l10n npm-Paket

KI-Übersetzungs-Workflow

1. Schreiben Sie Ihre Quell-translation.json auf Englisch (oder Ihrer Basissprache)
2. Laden Sie sie auf l10n.dev hoch oder führen Sie das ai-l10n CLI zur Übersetzung aus
3. Die KI generiert kontextuell genaue Übersetzungen für alle Zielsprachen
4. Legen Sie die übersetzten JSON-Dateien in Ihr locales/-Verzeichnis und stellen Sie sie bereit

Automatisieren Sie Übersetzungen mit dem ai-l10n CLI

Das ai-l10n npm-Paket integriert KI-Übersetzungen direkt in Ihren Entwicklungs-Workflow. Übersetzen Sie Ihre JSON-Dateien über die Befehlszeile:

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Build-Integration

Fügen Sie die Übersetzungsautomatisierung zu Ihrer Build-Pipeline hinzu, damit Übersetzungen immer auf dem neuesten Stand sind:

package.json-Skripte

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Weitere Details zur CI/CD-Integration und Automatisierung finden Sie in unserem Leitfaden zur Lokalisierungsautomatisierung

VS Code-Erweiterung für JSON-Übersetzung

Übersetzen Sie Ihre React i18next JSON-Dateien direkt aus VS Code. Mit der l10n.dev-Erweiterung können Sie Dateien übersetzen, ohne Ihren Editor zu verlassen:

So funktioniert es

1. Installieren Sie die l10n.dev-Erweiterung aus dem VS Code Marketplace
2. Öffnen Sie Ihre Quell-translation.json-Datei
3. Klicken Sie mit der rechten Maustaste und wählen Sie 'Translate with l10n.dev'
4. Wählen Sie Ihre Zielsprachen aus und erhalten Sie sofort übersetzte Dateien

Beginnen Sie noch heute mit der Lokalisierung Ihrer React-App

Sie haben jetzt alles, was Sie brauchen, um eine vollständig lokalisierte React-Anwendung mit react-i18next zu erstellen. Kombinieren Sie die Stärke des ausgereiften i18next-Ökosystems mit KI-gestützter Übersetzung, um Ihre App schnell in jeder Sprache auszuliefern.