PTC
Registrieren Upgrade auf Pro Ihr Konto

Wie man eine React-App mit react-i18next übersetzt

Richten Sie react-i18next ein, übersetzen Sie en.json mit KI in über 40 Sprachen und lassen Sie dann die Browser-Erweiterung der PTC (Private Translation Cloud) die laufende React-App bei jedem Release überprüfen. Dieser Leitfaden behandelt die React-Internationalisierung von Anfang bis Ende: die Einrichtung von react-i18next, den Umgang mit Pluralformen und dynamischen Inhalten, die Übersetzung von en.json in über 40 Sprachen mit der PTC und den Wechsel zwischen Sprachen zur Laufzeit. Am Ende werden Sie ein funktionierendes React-Lokalisierungs-Setup haben, das bereit zur Veröffentlichung ist. Für eine Übersicht über das eigenständige JSON-Übersetzungs-Tool siehe JSON-Dateien online mit KI übersetzen.

Wie eine lokalisierte React-App aussieht

Eine React-App, bei der:

  • Alle benutzerseitigen Strings in JSON-Übersetzungsdateien unter src/i18n/locales/ (oder public/locales/) liegen.
  • Ein Sprachumschalter zwischen Englisch, Spanisch, Französisch und Deutsch wechselt.
  • Dynamische Inhalte (Benutzernamen, Anzahlen, Daten) je nach Locale korrekt eingesetzt werden.
  • Pluralformen den Regeln der jeweiligen Zielsprache folgen.
  • Die übersetzten .json-Dateien von der PTC erstellt und nicht von Hand geschrieben werden.

Schritt 1: Eine React + TypeScript-App mit Vite erstellen

Dieser Leitfaden verwendet eine mit Vite erstellte React + TypeScript-App. Wenn Sie react-i18next zu einer bestehenden App hinzufügen, überspringen Sie diesen Schritt und gehen Sie direkt zu Schritt 2.

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

Dies startet einen Entwicklungsserver und öffnet die Standardseite von Vite + React in Ihrem Browser.

Schritt 2: react-i18next installieren und hardcodierte Strings durch t() ersetzen

npm install i18next react-i18next

Erstellen Sie Ihre i18n-Ordnerstruktur für React:

src/
  i18n/
    locales/
      en.json

Fügen Sie Ihre englischen Strings zu src/i18n/locales/en.json hinzu:

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Eine typische React-Komponente mit hardcodierten Strings:

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

Ersetzen Sie den hardcodierten Text durch den useTranslation-Hook:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

useTranslation() gibt Folgendes zurück:

  • t() – sucht einen String anhand seines Keys.
  • i18n – ermöglicht es Ihnen, Sprachen programmgesteuert zu ändern.

Schritt 3: Jedes Locale-JSON automatisch mit import.meta.glob laden

Erstellen Sie src/i18n/index.ts, um i18next zu konfigurieren und Übersetzungsdateien automatisch zu laden. Das import.meta.glob-Muster bedeutet, dass jede .json-Datei, die Sie zu src/i18n/locales/ hinzufügen, automatisch erkannt wird. Keine manuellen Importe mehr, wenn Sie neue Sprachen hinzufügen:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources =
  | string
  | { [k: string]: TranslationResources }
  | TranslationResources[];

const modules = import.meta.glob<{ default: Record<string, TranslationResources> }>(
  './locales/*.json',
  { eager: true }
);

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};
for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Importieren Sie i18n, bevor Ihre App gerendert wird. Öffnen Sie src/main.tsx und fügen Sie den Import hinzu:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import './i18n'; // <- add this

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

Wenn Sie diesen Schritt überspringen, gibt t() Übersetzungs-Keys anstelle von übersetztem Text zurück.

Variablen mit {{variableName}} einsetzen

Verwenden Sie die {{variableName}}-Syntax in Ihrem JSON und übergeben Sie den Wert an t(). Aktualisieren Sie en.json:

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}
const user = { firstName: 'Sarah' };
<p>{t('userGreeting', { firstName: user.firstName })}</p>

Das zweite Argument für t() ist ein Objekt mit den Werten, die Sie einsetzen möchten. So viele Variablen, wie Sie benötigen.

Pluralformen mit den Key-Suffixen _one / _other bilden

Verwenden Sie das Suffix-Muster _one / _other. Die Variable muss count heißen:

{
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}
<p>{t('newMessages', { count: messageCount })}</p>

i18next wählt automatisch die richtige Pluralform aus. Es unterstützt auch Sprachen mit mehr als zwei Pluralformen (Polnisch, Arabisch, Russisch) ohne zusätzliche Konfiguration.

Für Übersetzungen, die HTML-Elemente wie Links oder fetten Text enthalten, verwenden Sie die Trans-Komponente:

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

Die Tags <1> und <3> sind indexbasierte Platzhalter, die auf untergeordnete Elemente abgebildet werden (gezählt ab 0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
  I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
</Trans>

Dadurch bleiben Ihre JSX-Elemente in der Komponente, während Übersetzer den umgebenden Text weiterhin natürlich umstellen können.

Daten, Zahlen und Währungen mit Intl formatieren

Verwenden Sie Intl-Formatierer, anstatt Format-Strings in Ihre Übersetzungen einzubetten:

const formatDate = (date: Date, locale: string) =>
  new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);

const formatCurrency = (amount: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);

const { i18n } = useTranslation();
<p>{formatDate(new Date(), i18n.language)}</p>
<p>{formatCurrency(199.99, i18n.language, 'EUR')}</p>

Schritt 5: Übersetzen Sie die JSON-Dateien mit PTC in 5 Schritten

Sie haben nun en.json und müssen es.json, fr.json, de.json usw. erstellen. Die PTC ist genau dafür konzipiert.

  1. Starten Sie ein PTC-Projekt und wählen Sie Englisch als Quelle. Die 30-Tage-Testphase umfasst 20.000 Wörter in 2 Sprachen, keine Kreditkarte erforderlich.
  2. Laden Sie en.json hoch. Die PTC parst die verschachtelte Struktur, erkennt i18next-Platzhalter ({{name}}, {{count}}) und erfasst die Plural-Suffixe (_one, _other).
  3. Fügen Sie eine kurze Beschreibung Ihrer React-App und deren Zielgruppe hinzu. Die PTC nutzt diesen Kontext, um Tonalität und Terminologie in jeder Sprache passend abzustimmen.
  4. Wählen Sie die Zielsprachen aus und bestätigen Sie. Die PTC erstellt pro Zielsprache eine übersetzte .json, die strukturell identisch mit der Quelle ist. Gleiche Keys, gleiche Verschachtelung, gleiche Platzhalter. Übersetzte Werte.
  5. Legen Sie die Dateien in src/i18n/locales/ ab. Dank des in Schritt 3 eingerichteten Auto-Loadings über import.meta.glob funktionieren die neuen Dateien sofort und ohne Codeänderungen.

Sobald Sie Ihre erste Datei mit der PTC übersetzt haben, können Sie zu einem automatisierten Prozess übergehen. Verbinden Sie Ihr GitHub-, GitLab- oder Bitbucket-Repository über die Git-Integration oder nutzen Sie die PTC-API, um die Übersetzung in Ihre CI/CD-Pipeline einzubinden. Neue Strings in en.json lösen eine automatische Übersetzung aus. Die PTC öffnet einen Merge Request mit aktualisierten zielsprachlichen Dateien.

Schritt 6: Überprüfen Sie das Setup mit einem Sprachumschalter

Fügen Sie Sprach-Buttons hinzu, um zu überprüfen, ob Ihr react-i18next-Setup funktioniert:

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

i18n.changeLanguage() löst ein erneutes Rendern jeder Komponente aus, die useTranslation() verwendet, sodass die gesamte UI sofort aktualisiert wird. Kein Neuladen der Seite.

Erkennen Sie die Sprache des Benutzers mit i18next-browser-languagedetector automatisch

Installieren Sie i18next-browser-languagedetector, um automatisch die richtige Sprache aus den Browsereinstellungen, der URL oder den gespeicherten Präferenzen des Benutzers zu laden:

npm install i18next-browser-languagedetector
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'de', 'ar'],
    interpolation: { escapeValue: false },
    detection: {
      order: ['querystring', 'localStorage', 'cookie', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

Laden Sie Übersetzungen mit i18next-http-backend per Lazy-Load

Standardmäßig werden alle Übersetzungsdateien zur Build-Zeit gebündelt. Verwenden Sie für Apps mit vielen Sprachen i18next-http-backend, um nur die Sprache abzurufen, die der Benutzer tatsächlich benötigt:

npm install i18next-http-backend
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr'],
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

Verschieben Sie Ihre Übersetzungsdateien nach public/locales/, damit sie als statische Assets bereitgestellt werden:

public/
  locales/
    en/translation.json
    fr/translation.json

Ein Wechsel zu Französisch ruft nun /locales/fr/translation.json bei Bedarf ab, anstatt es zu bündeln. Das anfängliche Bundle bleibt schlank, unabhängig davon, wie viele Sprachen Sie unterstützen.

Visuelle Übersetzungsprüfung Ihrer laufenden React-App – veröffentlichen Sie ohne manuelle QA pro Release

Nachdem die PTC Ihre en.json übersetzt hat, müssen Sie die laufende React-App noch überprüfen. Ein übersetztes Label könnte im Deutschen bei einem Button einen Überlauf verursachen. „Save“ (Speichern) könnte im Französischen als Substantiv übersetzt werden, wenn die UI ein Verb benötigt. Ein hardcodierter englischer String außerhalb von t() wird unübersetzt dargestellt, unabhängig davon, wie viele Sprachen Sie veröffentlichen.

Die AI Visual QA der PTC ersetzt den manuellen QA-Durchlauf. Für browserbasierte Apps wie React ist die Browser-Erweiterung die richtige Variante. Installieren Sie sie einmal und zeichnen Sie einen kurzen Rundgang durch die kritischen Benutzer-Workflows Ihrer React-App auf (Anmeldung, Hauptfunktion, Einstellungen). Von da an spielt die PTC die Aufzeichnung nach jedem Übersetzungsupdate in jeder Zielsprache ab, erfasst jeden Bildschirm und prüft das gerenderte Ergebnis:

  • Korrekturen in den Übersetzungsdateien, wenn die PTC diese kontrolliert. Die PTC übersetzt eine falsche Wortart neu, wählt ein kürzeres Synonym, das auf einen Button passt, und generiert eine Pluralform neu.
  • Prompts für Cursor / Claude Code, wenn der Fehler in Ihrem Komponenten-Code liegt. Ein hardcodierter englischer String außerhalb von t(), ein durch String-Verkettung anstelle von t('key', { var }) gebildeter Satz, eine fehlende Trans-Komponente für Rich-Text-Übersetzungen.

Das Ergebnis: Review-als-CI-Schritt. Jedes Release wird mit visueller Überprüfung in jeder Zielsprache veröffentlicht, ganz ohne menschlichen Engpass.

Übersetzen Sie Release Notes, Marketingseiten und Kunden-E-Mails

Ihre Release Notes, Marketingseiten, Landingpages und Kunden-E-Mails befinden sich außerhalb von en.json. Die Paste to Translate der PTC verarbeitet diese Texte im selben Projekt. Fügen Sie den Ausgangstext in das PTC-Dashboard ein, wählen Sie die Zielsprachen aus und erhalten Sie Übersetzungen zurück, die dasselbe Glossar und dieselbe Markenstimme verwenden wie Ihre React-UI-Strings.

Übersetzen Sie Benutzerkommentare, Beiträge und Suchergebnisse mit der PTC-API

Benutzerkommentare, Beiträge, Suchergebnisse und alle anderen nutzergenerierten Inhalte, die Ihre React-App verarbeitet, müssen bei ihrem Eintreffen übersetzt werden. Die PTC-REST-API übersetzt diese Inhalte bei Bedarf mit Bearer-Token-Authentifizierung und verwendet dabei dasselbe Glossar und dieselbe Markenstimme wie Ihre en.json-Übersetzungen.

Übersetzen Sie nun Ihre en.json-Datei

Starten Sie Ihre 30-Tage-Testphase – 20.000 Wörter in 2 Sprachen, keine Kreditkarte erforderlich. Zwei Wege:

  • Manuell: Laden Sie src/i18n/locales/en.json auf der JSON-Übersetzungsseite hoch.
  • CI-gesteuert: Verbinden Sie Ihr Git-Repo über die PTC-API, und ein Push, der Ihre Quellstrings ändert, kommt übersetzt zurück.

So oder so, installieren Sie die Browser-Erweiterung und lassen Sie die AI Visual QA Ihre laufende React-App in jeder Sprache überprüfen, bevor Sie sie veröffentlichen.