React-Lokalisierung mit i18next

Der Aufbau 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 zur 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 ist der Grund, warum Entwickler es wählen:

• Hooks-First API - Der useTranslation()-Hook bietet eine saubere, idiomatische React-Integration mit automatischem Neu-Rendering bei Sprachwechsel.
• Reiches Ö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 und KI-Dienste zu integrieren sind.
• Namespace-Unterstützung - Organisieren Sie Übersetzungen in logische Gruppen (auth, dashboard, errors) für bessere Wartbarkeit und Lazy Loading.
• SSR & Next.js bereit - Funktioniert nahtlos mit serverseitigem Rendering, React Server Components und dem Next.js App Router.
• TypeScript-Unterstützung - Volle Typsicherheit für Übersetzungsschlüssel mit Autovervollständigung, wodurch fehlende Schlüssel 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 lazy-geladene Ü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 hält Ihre Übersetzungen wartbar, während 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 _male- und _female-Suffixe für geschlechtsspezifische Übersetzungen, wenn nötig.

i18next konfigurieren

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 oder wenn Sie Übersetzungen sofort ohne Netzwerkanfragen benötigen:

// 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 Ihren App-Einstiegspunkt, bevor Sie Komponenten rendern. Dies stellt sicher, dass Übersetzungen geladen werden, bevor Ihre UI rendert:

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

React-Komponenten übersetzen

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

useTranslation-Hook

Der useTranslation-Hook ist der gebräuchlichste Weg, 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, etc.) enthalten, verwenden Sie die Trans-Komponente. Sie bewahrt Ihren React-Komponentenbaum innerhalb von Ü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."

Pluralisierung handhaben

i18next behandelt Pluralformen automatisch basierend auf den ICU-Pluralregeln für jede Sprache. Übergeben Sie einen Zählparameter, 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 Ihren Übersetzungsschlüsseln für Englisch _one- und _other-Suffixe 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

Namespaces ermöglichen es Ihnen, Übersetzungen nach Funktion oder Domäne in separate Dateien aufzuteilen. Dies verbessert die Wartbarkeit und ermöglicht das Lazy Loading von Übersetzungsbundles:

// 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 integriert sich in React Suspense, um asynchrones 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 die vollständige TypeScript-Integration. Durch die Erweiterung des i18next-Moduls erhalten Sie Autovervollständigung und Kompilierzeit-Prüfung 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

Serverseitiges 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 verwenden. 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 Statusverluste zwischen Benutzern zu verhindern
• Verwenden Sie dieselben JSON-Übersetzungsdateien sowohl für serverseitiges als auch für clientseitiges Rendering
• Ziehen Sie i18next-resources-to-backend oder next-intl als Alternativen für komplexe Next.js-Setups in Betracht

Übersetzung mit KI beschleunigen

Das Einrichten von react-i18next ist nur die halbe Miete – Sie benötigen immer noch qualitativ 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 das Spiel.

Warum l10n.dev für React i18next verwenden?

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

• 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 technische Begriffe und Markenstimme über Sprachen hinweg
• Interpolationssicher — Bewahrt {{variables}}, Pluralsuffixe (_one, _other) und verschachtelte Schlüsselstrukturen
• Stapelübersetzung — Übersetzen Sie in Sekundenschnelle in über 10 Sprachen, nicht in Tagen
• CI/CD-Integration — Automatisieren Sie Übersetzungen als Teil Ihrer Build-Pipeline mit dem ai-l10n npm-Paket

KI-Übersetzungsworkflow

1. Schreiben Sie Ihre translation.json-Quelle auf Englisch (oder Ihrer Basissprache)
2. Laden Sie sie auf l10n.dev hoch oder führen Sie die ai-l10n CLI zum Übersetzen aus
3. 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

Übersetzungen mit ai-l10n CLI automatisieren

Das ai-l10n npm-Paket integriert KI-Übersetzung direkt in Ihren Entwicklungsworkflow. Ü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 Ü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. Die l10n.dev-Erweiterung lässt Sie Dateien übersetzen, ohne Ihren Editor zu verlassen:

Wie es funktioniert

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

Starten 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 Kraft des ausgereiften Ökosystems von i18next mit KI-gestützter Übersetzung, um Ihre App schnell in jeder Sprache auszuliefern.