React-Übersetzung mit react-i18next: Ein vollständiger Leitfaden

Erfahren Sie, wie Sie eine React-App mit react-i18next übersetzen – einschließlich React-Internationalisierung, Pluralformen, dynamischer Inhalte und der Übersetzung von JSON-Dateien.

Am Ende dieses Leitfadens verfügen Sie über ein funktionierendes React-Lokalisierungs-Setup, das Sprachen in Echtzeit umschaltet und für so viele Sprachen bereit ist, wie Sie benötigen.

React-Internationalisierungsbeispiel

Die folgenden Schritte führen Sie durch ein vollständiges React-i18n-Beispiel – einschließlich der Initialisierung von i18next, dem Übersetzen von Text, dem Umgang mit Pluralisierung und dem Hinzufügen eines Sprachumschalters.

Sie können der vollständigen React-Lokalisierungs-Demo auf GitHub folgen.

Richten Sie Ihre React-App ein

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

Um eine neue React + TypeScript-App zu erstellen, führen Sie Folgendes aus:

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

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 von Vite + React in Ihrem Browser geöffnet.

Installieren und konfigurieren Sie react-i18next

Installieren Sie die Bibliotheken:

npm install i18next react-i18next

npm install i18next react-i18next

Erstellen Sie Ihre React-i18n-Ordnerstruktur:

src/
 i18n/
 locales/
 en.json

src/
  i18n/
    locales/
      en.json

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

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

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

Jeder Schlüssel (welcome, description, clickMe) wird dem Text zugeordnet, der in der Benutzeroberfläche angezeigt werden soll.

Bereiten Sie Ihre React-Komponenten für die Übersetzung vor

Hier ist eine typische React-Komponente mit fest codierten Strings:

function App() {
  return (
    <div>
      <h1>Willkommen</h1>
      <p>Dies ist eine Lokalisierungsdemo.</p>
      <button onClick={() => alert('Click me')}>Klick mich</button>
    </div>
  );
}

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 fest codierten Text durch den useTranslation Hook in src/App.tsx:

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;

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() ermöglicht Ihrer Komponente Zugriff auf:

t() – sucht eine Zeichenfolge anhand des Schlüssels
i18n – ermöglicht es Ihnen, Sprachen programmgesteuert zu ändern

Initialisieren Sie i18next in Ihrer React-App

Erstellen Sie src/i18n/index.ts, um i18next zu konfigurieren und Übersetzungsdateien automatisch zu laden.

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;

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;

Das Muster import.meta.glob bedeutet, dass jede .json-Datei, die Sie zu src/i18n/locales/ hinzufügen, automatisch erkannt wird. Wenn Sie später neue Sprachen hinzufügen, sind keine manuellen Imports erforderlich.

Importieren Sie i18n, bevor Ihre App gerendert wird

Öffnen Sie src/main.tsx und importieren Sie die i18n-Konfiguration:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n' // ← Diesen Import hinzufügen!

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

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n'  // ← Add this import!

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

Wenn Sie diesen Schritt überspringen, gibt t() nur Übersetzungsschlüssel anstelle von übersetztem Text zurück.

Dynamische Inhalte in React-Übersetzungen handhaben

Echte Apps brauchen mehr als statische Strings. So verarbeitet react-i18next die gängigsten Muster für dynamische Inhalte.

Interpolation (Variablen) in i18next

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

Aktualisieren Sie src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "userGreeting": "Willkommen zurück, {{firstName}}!",
 "description": "Dies ist eine Lokalisierungsdemo.",
 "clickMe": "Klick mich"
}

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

Verwenden Sie es in Ihrer Komponente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

Das zweite Argument von t() ist ein Objekt mit den Werten, die Sie ersetzen möchten. Sie können so viele Variablen verwenden, wie Sie benötigen. Stellen Sie nur sicher, dass jede in Ihren Übersetzungen vorkommt.

React-i18next-Pluralisierung

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

Aktualisieren Sie src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "userGreeting": "Willkommen zurück, {{firstName}}!",
 "description": "Dies ist eine Lokalisierungsdemo.",
 "clickMe": "Klick mich",
 "newMessages_one": "Sie haben {{count}} neue Nachricht.",
 "newMessages_other": "Sie haben {{count}} neue Nachrichten."
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me",
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}

Verwenden Sie es in Ihrer Komponente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };
 const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
 setMessageCount(messageCount + 1);
 };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };
  const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
    setMessageCount(messageCount + 1);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

i18next wählt automatisch die korrekte Pluralform aus. Außerdem unterstützt es Sprachen mit mehr als zwei Pluralformen (wie Polnisch oder Arabisch) ohne zusätzliche Konfiguration.

Links und HTML mit der Trans-Komponente übersetzen

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

{
 "termsText": "Ich stimme den <1>Nutzungsbedingungen1> und der <3>Datenschutzerklärung3> zu."
}

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

Die Tags <1> und <3> sind indexbasierte Placeholder, die auf Kindelemente abbilden (gezählt ab 0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
 Ich stimme den <a href="/terms">Nutzungsbedingungen</a> und
  <a href="/privacy">Datenschutzerklärung</a> zu.
</Trans>

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>

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

Übersetzen Sie die JSON-Dateien Ihrer React-App

Ihre React-App ist jetzt für Internationalisierung eingerichtet. Der nächste Schritt ist, die eigentlichen Übersetzungsdateien für jede Sprache zu erstellen.

PTC ist genau dafür konzipiert. Dieses KI-Lokalisierungstool integriert sich direkt in Ihr GitHub-, GitLab– oder Bitbucket-Repository. Es liest Ihr Quell-en.json, und erstellt einen Pull Request mit übersetzten Dateien für jede Sprache, die Sie benötigen.

Dank der Auto-Loading-Konfiguration, die Sie in Schritt 3 eingerichtet haben, funktionieren diese neuen Dateien sofort – ganz ohne Codeänderungen.

PTC startet mit einer kostenlosen 30-tägigen Testversion, mit der Sie 20.000 Wörter in 2 Sprachen übersetzen können. Danach zahlen Sie nach Verbrauch – ohne Abonnement.

Für PTC anmelden

Wenn Sie Ihr Repository lieber nicht integrieren möchten, können Sie alternativ:

die PTC API verwenden, um Continuous Localization einzurichten
eine JSON-Datei manuell hochladen und eine übersetzte Datei zurückerhalten

React-Übersetzungen mit einem Sprachumschalter testen

Fügen Sie Sprach-Buttons zu src/App.tsx hinzu und prüfen Sie, ob Ihr react-i18next-Setup funktioniert:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
  Ich stimme den  <a href="/terms">Nutzungsbedingungen</a> und der  <a href="/privacy">Datenschutzrichtlinie</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

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

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
          I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

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

Führen Sie npm run dev aus und klicken Sie auf die Sprach-Buttons. Der Text sollte sich sofort ohne Neuladen der Seite aktualisieren. Wenn das der Fall ist, funktioniert Ihr React-i18n-Setup korrekt.

React app in English

React app in French

Nächste Schritte: Optimieren Sie Ihr React-Lokalisierungs-Setup

Ihre React-App unterstützt jetzt vollständig mehrere Sprachen. Bevor Sie in Produktion gehen, sind einige Ergänzungen sinnvoll:

Sprache des Nutzers automatisch erkennen

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

npm install i18next-browser-languagedetector

npm install i18next-browser-languagedetector

Aktualisieren Sie src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

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(LanguageDetector) // Browser/localStorage/etc. erkennen
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: "en",
 supportedLngs: ["en", "fr", "de", "ar"], // an Ihre Sprachen anpassen
 interpolation: { escapeValue: false },
 detection: {
 order: ["querystring", "localStorage", "cookie", "navigator"],
 caches: ["localStorage", "cookie"],
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

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(LanguageDetector) // detect browser/localStorage/etc.
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ar"], // adjust to your languages
    interpolation: { escapeValue: false },
    detection: {
      order: ["querystring", "localStorage", "cookie", "navigator"],
      caches: ["localStorage", "cookie"],
    }
  });

export default i18n;

Lazy-Load-Übersetzungen

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

npm install i18next-http-backend

npm install i18next-http-backend

Aktualisieren Sie src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

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

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

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

export default i18n;

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

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

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

Mit dieser Struktur wird beim Wechsel zu Französisch /locales/fr/common.json bei Bedarf nachgeladen, statt es mit Ihrer App zu bündeln. So bleibt Ihr initiales Bundle schlank – unabhängig davon, wie viele Sprachen Sie unterstützen.

React mit PTC übersetzen

Ihre React-App ist bereit für Internationalisierung. Jetzt übernimmt PTC die Übersetzungen.

Ihre ersten 20.000 Wörter sind kostenlos – kein Abonnement erforderlich.

Testen Sie PTC jetzt