Creation:2026-06-05Last update:2026-06-05

    Migration von react-i18next / i18next zu Intlayer

    Warum von react-i18next / i18next zu Intlayer migrieren?

    Anstatt riesige JSON-Dateien in Ihre Seiten zu laden, laden Sie nur die benötigten Inhalte. Intlayer hilft Ihnen, die Größe Ihres Bundles und Ihrer Seiten um bis zu 50 % zu reduzieren.

    Das Scopen Ihrer Anwendungsinhalte erleichtert die Wartung für große Anwendungen. Sie können einen ganzen Feature-Ordner duplizieren oder löschen, ohne den mentalen Aufwand betreiben zu müssen, Ihre gesamte Inhalts-Codebase zu überprüfen. Darüber hinaus ist Intlayer vollständig typisiert, um die Richtigkeit Ihrer Inhalte sicherzustellen.

    Intlayer ist zudem die Lösung mit der aktivsten Entwicklung im i18n-Ökosystem — Probleme werden schnell behoben, neue Framework-Adapter kommen regelmäßig hinzu und die Kern-API wird kontinuierlich auf Basis echter Produktionserfahrungen verfeinert.

    Die Kollokation von Inhalten reduziert den für Large Language Models (LLMs) erforderlichen Kontext. Intlayer verfügt außerdem über eine Reihe von Werkzeugen, wie eine CLI zum Testen fehlender Übersetzungen, LSP, MCP und Agenten-Fähigkeiten (Agent Skills), um die Entwicklererfahrung (DX) für KI-Agenten noch reibungsloser zu gestalten.

    Nutzen Sie Automatisierung zur Übersetzung in Ihrer CI/CD-Pipeline unter Verwendung des LLM Ihrer Wahl zum Preis Ihres KI-Anbieters. Intlayer bietet auch einen Compiler zur Automatisierung der Inhaltsextraktion sowie eine Web-Plattform, die Übersetzungen im Hintergrund unterstützt.

    Das Verknüpfen riesiger JSON-Dateien mit Komponenten kann zu Leistungs- und Reaktivitätsproblemen führen. Intlayer optimiert das Laden Ihrer Inhalte zur Build-Zeit.

    Mehr als nur eine i18n-Lösung bietet Intlayer einen selbst gehosteten visuellen Editor und ein vollständiges CMS, das Ihnen hilft, Ihre mehrsprachigen Inhalte in Echtzeit zu verwalten. Dies ermöglicht eine nahtlose Zusammenarbeit mit Übersetzern, Textern und anderen Teammitgliedern. Die Inhalte können lokal und/oder remote gespeichert werden.

    Migrationsstrategien

    Es gibt zwei ergänzende Strategien für die Migration von react-i18next / i18next zu Intlayer:

    1. Kompatibilitätsadapter (empfohlen für bestehende Apps) — Installieren Sie @intlayer/react-i18next (für React-Komponenten) und/oder @intlayer/i18next (für die Kern-i18n-Instanz). Diese Pakete bieten genau dieselbe API wie react-i18next / i18next, delegieren jedoch die gesamte Übersetzungsarbeit an Intlayer. Sie behalten Ihre bestehenden Aufrufe für useTranslation, Trans, withTranslation, i18next.t() bei — die einzige Änderung ist der Importpfad.

    2. Vollständige Migration — Ersetzen Sie schrittweise react-i18next-APIs durch native Intlayer-Hooks (useIntlayer, IntlayerProvider) und platzieren Sie Inhalte lokal in .content.ts-Dateien neben Ihren Komponenten.

    Dieser Leitfaden behandelt zuerst Strategie 1 (schneller Kompatibilitätsadapter) und geht dann auf die optionale vollständige Migration ein.

    Inhaltsverzeichnis

    Schnelle Migration

    Die folgenden Schritte sind das Minimum, das erforderlich ist, um Ihre bestehende react-i18next-App auf Intlayer laufen zu lassen, ohne Codeänderungen vornehmen zu müssen.

    1. Abhängigkeiten installieren

      Installieren Sie die Intlayer-Kernpakete und die Kompatibilitätsadapter:

      bash
      npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init
      Sie können react-i18next und i18next installiert lassen — die Kompatibilitätsadapter verwenden sie als optionale devDependencies / peerDependencies für TypeScript-Typen. Sie müssen keine Peers in der package.json ändern.

    2. Intlayer konfigurieren

      Der Befehl intlayer init erstellt eine initiale Datei intlayer.config.ts. Aktualisieren Sie sie so, dass sie Ihren bestehenden Locales (Sprachen) entspricht, und verweisen Sie das syncJSON-Plugin auf Ihre Nachrichtendateien:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";
import { syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Fügen Sie hier alle Ihre bestehenden Locales hinzu
    ],
    defaultLocale: Locales.ENGLISH,
  },
  plugins: [
    syncJSON({
      // Entspricht der Platzhalter-Syntax von react-i18next: {{name}}
      format: "i18next",
      source: ({ locale }) => `./src/locales/${locale}.json`,
      location: "src/locales",
    }),
  ],
};

export default config;
      source ordnet ein Locale dem Dateipfad seiner JSON-Datei zu. location gibt dem Intlayer-Watcher an, welcher Ordner auf Änderungen überwacht werden soll. Die Option format: 'i18next' stellt sicher, dass Platzhalter wie {{name}} korrekt verarbeitet werden.

    3. Das Intlayer-Plugin zu Ihrem Bundler hinzufügen

      Kapseln Sie Ihre bestehende Bundler-Konfiguration mit dem Kompatibilitäts-Plugin. Dieses integriert das Kern-Intlayer-Plugin, verbindet die Inhaltsüberwachung und — entscheidend — injiziert Modul-Aliase, sodass Ihre bestehenden Aufrufe für import … from 'react-i18next' (und 'i18next') zur Build-Zeit nahtlos auf @intlayer/react-i18next / @intlayer/i18next umgeleitet werden. Es sind keine Änderungen an den Quelldateien erforderlich.

      Für Vite:

      vite.config.ts
      import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";

export default defineConfig({
  plugins: [react(), reactI18nextVitePlugin()],
});
      reactI18nextVitePlugin() kapselt das Plugin intlayer() von vite-intlayer und fügt automatisch die Aliase für react-i18next / i18next hinzu. Wenn Sie das normale intlayer()-Plugin von vite-intlayer verwenden, werden die Wörterbücher zwar kompiliert, die Aliase jedoch nicht hinzugefügt — dann müssten Sie Importe manuell in @intlayer/* umbenennen (siehe Schritt 4).

      Für Next.js:

      Wenn Sie next-i18next (Pages Router-Integration) verwenden, installieren Sie @intlayer/next-i18next und next-intlayer:

      bash
      npm install @intlayer/next-i18next next-intlayer

      Fügen Sie dann das Kompatibilitäts-Plugin zu Ihrer next.config.ts hinzu (es injiziert die Aliase für next-i18next / react-i18next / i18next):

      next.config.ts
      import type { NextConfig } from "next";
import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";

const withIntlayer = createNextI18nPlugin();

const nextConfig: NextConfig = {
  /* Ihre Optionen */
};

export default withIntlayer(nextConfig);
      Sie benötigen i18next.init() oder manuelles Provider-Bootstrapping nicht mehr. Intlayer kompiliert alle Wörterbücher zur Build-Zeit, daher entfällt das Laden zur Laufzeit. Der aliasierte Provider übernimmt die Initialisierung für Sie.

    Das war's für die schnelle Migration. Ihre App läuft nun auf Intlayer, während alle Importe und react-i18next-APIs intakt bleiben.

    Typisierte Übersetzungsschlüssel — automatisch. Sobald Intlayer Ihre Wörterbücher kompiliert hat, sind useTranslation und getFixedT typisiert gegen Ihre tatsächlichen Inhalte. Die Schlüssel werden in Ihrer IDE autovervollständigt und ungültige Pfade führen zu TypeScript-Fehlern zur Build-Zeit — ohne zusätzliche Konfiguration.

    tsx
    // 'about' ist ein registrierter Dictionary-Schlüssel → t() akzeptiert nur gültige Pfadeconst { t } = useTranslation("about");t("counter.label"); // ✓ autovervollständigtt("does.not.exist"); // ✗ TypeScript-Fehler// Serverseite (i18next Instanz)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ typisiert

    Vollständige Migration

    Die folgenden Schritte sind optional und können inkrementell durchgeführt werden. Sie schalten die volle Funktionalität von Intlayer frei: visueller Editor, CMS, typisierte Inhaltsdateien, KI-gestützte Übersetzung und mehr.

    1. Importe explizit umbenennen (Optional)

      Optional

      Die Intlayer-Plugins kümmern sich bereits um das Aliasing auf Bundler-Ebene. Wenn Sie die Abhängigkeit in Ihren Quelldateien explizit machen möchten, können Sie die Importe manuell umbenennen:

      Vorher Nachher
      import { useTranslation } from 'react-i18next' import { useTranslation } from '@intlayer/react-i18next'
      import { Trans } from 'react-i18next' import { Trans } from '@intlayer/react-i18next'
      import { withTranslation } from 'react-i18next' import { withTranslation } from '@intlayer/react-i18next'
      import { I18nextProvider } from 'react-i18next' import { I18nextProvider } from '@intlayer/react-i18next'
      import { initReactI18next } from 'react-i18next' import { initReactI18next } from '@intlayer/react-i18next'
      import i18next from 'i18next' import i18next from '@intlayer/i18next'
      import { createInstance } from 'i18next' import { createInstance } from '@intlayer/i18next'
      import { t } from 'i18next' import { t } from '@intlayer/i18next'

      Für Next.js (next-i18next):

      Vorher Nachher
      import { serverSideTranslations } from 'next-i18next/serverSideTranslations' import { serverSideTranslations } from '@intlayer/next-i18next'
      import { appWithTranslation } from 'next-i18next' import { appWithTranslation } from '@intlayer/next-i18next'
      import { useTranslation } from 'next-i18next' import { useTranslation } from '@intlayer/next-i18next'

    2. Aktivieren der KI-gestützten Übersetzungsautomatisierung

      Optional

      Sobald Intlayer konfiguriert ist, können Sie die CLI verwenden, um fehlende Übersetzungen automatisch aufzufüllen:

      bash
      # Fehlende Übersetzungen testen (zu CI hinzufügen)npx intlayer test# Fehlende Übersetzungen mit KI auffüllennpx intlayer fill

      Fügen Sie die KI-Konfiguration zu intlayer.config.ts hinzu:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";
import { syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  plugins: [
    syncJSON({
      format: "i18next",
      source: ({ locale }) => `./src/locales/${locale}.json`,
      location: "src/locales",
    }),
  ],
  ai: {
    apiKey: process.env.OPENAI_API_KEY,
    // provider: "openai",     // default
    // model: "gpt-4o-mini",   // default
  },
};

export default config;
      Sehen Sie sich die Intlayer CLI-Dokumentation an, um alle verfügbaren Optionen zu erkunden.

    Was Sie nach der Migration löschen können

    Sobald die Kompatibilitätsadapter vorhanden sind, kann der folgende Standard-react-i18next / i18next-Code gelöscht werden:

    Datei / Muster Warum er nicht mehr benötigt wird
    Aufrufe von i18next.init() Der Intlayer-Provider initialisiert alles automatisch; es gibt keinen Ladeschritt zur Laufzeit.
    I18nextProvider / initReactI18next Das Intlayer-Plugin verarbeitet Injection und Bootstrapping intern.
    JSON-Sprachpakete (locales/*.json) JSON-Pakete werden nur benötigt, wenn Sie weiterhin das syncJSON-Plugin verwenden. Sobald Sie zu .content.ts-Dateien migrieren, können Sie den JSON-Ordner löschen.

    Wenn Sie bereit sind, weiterzugehen, erkennt Intlayer automatisch alle .content.ts- und .content.json-Dateien überall in Ihrer Codebasis (standardmäßig überall innerhalb von ./src). Sie können eine Datei my-component.content.ts direkt neben Ihrer MyComponent.tsx platzieren, und Intlayer wird sie zur Build-Zeit ohne zusätzliche Konfiguration erkennen — keine Importe, keine Registrierung, keine zentrale Index-Datei erforderlich. Dies macht die Kollokation von Übersetzungen mit Seiten und Komponenten völlig nahtlos.

    TypeScript einrichten

    Intlayer nutzt Modul-Erweiterungen, um volles TypeScript-Intellisense für Ihre Übersetzungsschlüssel bereitzustellen. Stellen Sie sicher, dass Ihre tsconfig.json die automatisch generierten Typen enthält:

    tsconfig.json
    {  // ... Ihre bestehenden TypeScript-Konfigurationen  "include": [    // ... Ihre bestehenden TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Fügen Sie die automatisch generierten Typen hinzu  ],}

    Git-Konfiguration

    Fügen Sie das von Intlayer generierte Verzeichnis zu Ihrer .gitignore hinzu:

    .gitignore
    # Intlayer-generierte Dateien ignorieren.intlayer

    Weiterführende Themen

    Warum Intlayer?