Migration von next-i18next zu Intlayer

Warum von next-i18next zu Intlayer migrieren?

Migrationsstrategien

Da next-i18next unter der Haube react-i18next und i18next kapselt, gibt es zwei ergänzende Strategien für die Migration zu Intlayer:

1. Kompatibilitätsadapter (empfohlen für bestehende Apps) — Installieren Sie @intlayer/next-i18next, @intlayer/react-i18next und @intlayer/i18next. Diese Pakete bieten genau dieselbe API wie ihre Gegenstücke, delegieren jedoch die gesamte Übersetzungsarbeit an Intlayer. Sie behalten Ihre bestehenden Aufrufe für useTranslation, appWithTranslation, serverSideTranslations und das Next.js-Seitenrouting unverändert bei — die einzige Änderung ist die Initialisierung.

2. Vollständige Migration — Ersetzen Sie schrittweise next-i18next-APIs durch native Intlayer-Hooks (useIntlayer) 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 Next.js Pages Router-App auf Intlayer laufen zu lassen, ohne Codeänderungen in Ihren Seiten und Komponenten vornehmen zu müssen.

1. 1

   Abhängigkeiten installieren

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

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Sie können next-i18next, react-i18next und i18next während der Migration sicher installiert lassen, obwohl Sie sie entfernen werden, sobald die Aliase eingerichtet sind.

2. 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 next-i18next-Nachrichtendateien (üblicherweise in public/locales):

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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 i18next: {{name}}
         format: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source ordnet ein Locale und einen Namespace (key) 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 für next-i18next korrekt verarbeitet werden.

3. 3

   Next.js-Konfiguration aktualisieren

   Kapseln Sie Ihre bestehende next.config.ts (oder .js) mit createNextI18nPlugin aus @intlayer/next-i18next/plugin. Dieser Wrapper wendet withIntlayer an und injiziert die Aliase next-i18next / react-i18next / i18next → @intlayer/*, sodass Ihre bestehenden Aufrufe für import { useTranslation } from 'next-i18next' zur Build-Zeit nahtlos umgeleitet werden. Es sind keine Änderungen an den Quelldateien erforderlich.

   next.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // Sie können die aus next-i18next.config.js importierte i18n-Konfiguration entfernen
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer übernimmt das Next.js i18n-Routing im Hintergrund,
     // daher müssen Sie hier nicht mehr das i18n-Objekt übergeben.
   };
   
   export default withIntlayer(nextConfig);

   Sie benötigen die Datei next-i18next.config.js nicht mehr. Intlayer kompiliert alle Wörterbücher zur Build-Zeit und übernimmt Locale-Erkennung, Routing und das Laden von Wörterbüchern nahtlos.

   Bevorzugen Sie das einfache withIntlayer aus next-intlayer/server? Es kompiliert Ihre Wörterbücher, fügt jedoch nicht die Aliase für next-i18next / react-i18next / i18next hinzu — dann müssten Sie Importe manuell in @intlayer/* umbenennen (siehe Schritt 4).

Das war's für die schnelle Migration. Ihre Next.js-App läuft nun auf Intlayer, während alle Aufrufe von useTranslation, serverSideTranslations und appWithTranslation 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

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

// Pages Router — 'about' ist ein registrierter Dictionary-Namespaceconst { t } = useTranslation("about");t("counter.label"); // ✓ autovervollständigtt("does.not.exist"); // ✗ TypeScript-Fehler// getStaticProps / getServerSideProps (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. 4

   Importe explizit umbenennen (Optional)

   Optional

   Das Intlayer-Plugin kümmert 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:

   Alle Tabellendaten anzeigen

   Alle Tabellendaten anzeigen

   Tabelle in einem Modal öffnen, um alle Daten übersichtlich anzuzeigen

   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'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

   Es handelt sich um direkte Ersetzungen (Drop-in Replacements) — Call-Signaturen, Argumente oder Rückgabetypen müssen nicht geändert werden.

2. 5

   Aktivieren der KI-gestützten Übersetzungsautomatisierung

   Optional

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

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   # 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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/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 der Kompatibilitätsadapter vorhanden ist, kann der folgende Standard-next-i18next-Code gelöscht werden:

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:

{  // ... 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:

# Intlayer-generierte Dateien ignorieren.intlayer

Weiterführende Themen

• Visueller Editor — Verwalten Sie Übersetzungen visuell in Ihrem Browser: Intlayer Visual Editor
• CMS — Externalisieren und verwalten Sie Inhalte remote: Intlayer CMS
• VS Code-Erweiterung — Erhalten Sie Autovervollständigung und Fehlererkennung für Übersetzungen in Echtzeit: Intlayer VS Code Extension
• CLI-Referenz — Vollständige Liste der CLI-Befehle: Intlayer CLI
• Intlayer mit Next.js (Pages Router) — Vollständige Einrichtungsanleitung für Next.js: intlayerwithnextjspagerouter.md