PTC
Registrieren Upgrade auf Pro Ihr Konto

Eine React-App mit react-i18next übersetzen

Richten Sie react-i18next ein, übersetzen Sie en.json mit KI in 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 Internationalisierung von React von Anfang bis Ende: die Einrichtung von react-i18next, den Umgang mit Pluralformen und dynamischen Inhalten, die Übersetzung Ihrer en.json in 40+ Sprachen mit der PTC und den Sprachwechsel zur Laufzeit. Am Ende verfügen Sie über ein funktionierendes Setup für die React-Lokalisierung, das bereit zur Veröffentlichung ist. Einen Überblick über das eigenständige JSON-Übersetzungstool finden Sie unter JSON-Dateien online mit KI übersetzen.

Wie eine lokalisierte React-App aussieht

Eine React-App, in 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) pro Locale korrekt eingesetzt werden.
  • Pluralformen den Regeln jeder Zielsprache folgen.
  • Die übersetzten .json-Dateien von der PTC erstellt und nicht von Hand geschrieben werden.

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

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

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

Dadurch wird ein Entwicklungsserver gestartet und die Standardseite für Vite + React in Ihrem Browser geöffnet.

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

npm install i18next react-i18next

Erstellen Sie Ihre React-i18n-Ordnerstruktur:

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 nach Schlüssel heraus.
  • i18n – ermöglicht es Ihnen, Sprachen programmatisch zu wechseln.

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

Erstellen Sie src/i18n/index.ts, um i18next zu konfigurieren und Übersetzungsdateien automatisch zu laden. Das Muster import.meta.glob bedeutet, dass jede .json-Datei, die Sie zu src/i18n/locales/ hinzufügen, automatisch erkannt wird. Keine manuellen Importe, 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() Übersetzungsschlüssel anstelle von übersetztem Text zurück.

Variablen mit {{variableName}} einsetzen

Verwenden Sie die Syntax {{variableName}} in Ihrer 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 ersetzen möchten. So viele Variablen, wie Sie benötigen.

Pluralbildung mit den Suffix-Schlüsseln _one / _other

Verwenden Sie das Suffix-Muster _one / _other. Die Variable muss count genannt werden:

{
  "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 verarbeitet 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 den untergeordneten Elementen zugeordnet werden (beginnend bei 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 Formatierungs-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: Die JSON-Dateien mit der PTC in 5 Schritten übersetzen

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 Ausgangssprache. Die Testphase umfasst 20.000 Wörter in 2 Sprachen, keine Kreditkarte.
  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 ihrer Zielgruppe hinzu. Die PTC nutzt diesen Kontext, um Tonalität und Terminologie über alle Sprachen hinweg abzustimmen.
  4. Wählen Sie die Zielsprachen aus und bestätigen Sie. Die PTC erstellt eine übersetzte .json pro Zielsprache, die strukturell mit der Quelle identisch ist. Gleiche Schlüssel, gleiche Verschachtelung, gleiche Platzhalter. Übersetzte Werte.
  5. Legen Sie die Dateien in src/i18n/locales/ ab. Dank des automatischen Ladens mit import.meta.glob, das Sie in Schritt 3 eingerichtet haben, funktionieren die neuen Dateien sofort 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 den aktualisierten Dateien der Zielsprachen.

Schritt 6: Das Setup mit einem Sprachumschalter überprüfen

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 sich die gesamte Benutzeroberfläche sofort aktualisiert. Kein Neuladen der Seite.

Die Sprache des Benutzers mit i18next-browser-languagedetector automatisch erkennen

Installieren Sie i18next-browser-languagedetector, um automatisch die richtige Sprache anhand der Browser-Einstellungen des Benutzers, der URL oder gespeicherter Präferenzen 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'],
    },
  });

Lazy-Loading von Übersetzungen mit i18next-http-backend

Standardmäßig werden alle Übersetzungsdateien zur Build-Zeit gebündelt. Für Apps mit vielen Sprachen verwenden Sie 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

Beim Wechsel zu Französisch wird /locales/fr/translation.json nun bei Bedarf abgerufen, 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 – ohne manuelle QA pro Release veröffentlichen

Nachdem die PTC Ihre en.json übersetzt hat, müssen Sie die laufende React-App weiterhin überprüfen. Ein übersetztes Label könnte im Deutschen über einen Button hinausragen. „Save“ könnte im Französischen als Substantiv übersetzt werden, wenn die Benutzeroberfläche ein Verb benötigte. Ein hardcodierter englischer String außerhalb von t() wird unübersetzt dargestellt, unabhängig davon, in wie vielen 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, sofern 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 Verifizierung in jeder Zielsprache veröffentlicht, ohne menschlichen Engpass.

Release Notes, Marketingseiten und Kunden-E-Mails übersetzen

Ihre Release Notes, Marketingseiten, Landingpages und Kunden-E-Mails befinden sich außerhalb von en.json. Paste to Translate von der PTC handhabt 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.

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

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. 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 die Übersetzungen erfolgen automatisch bei jedem Push.

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 veröffentlichen.