Migration von next-intl zu Intlayer

Warum von next-intl zu Intlayer migrieren?

Migrationsstrategie

Der empfohlene Ansatz für bestehende Anwendungen ist der Kompatibilitätsadapter: Installieren Sie @intlayer/next-intl. Dieser Adapter bietet genau dieselbe API wie next-intl, delegiert jedoch die gesamte Übersetzungsarbeit im Hintergrund an Intlayer.

Sie behalten Ihre bestehenden useTranslations, getTranslations, NextIntlClientProvider und andere Komponenten bei — die einzige Änderung ist der Importpfad. Es ist kein Refactoring von Call-Signaturen, Props oder Komponentenstrukturen erforderlich.

Mit der Zeit können Sie optional einzelne Dateien in das reichhaltigere .content.ts-Format von Intlayer migrieren, um den visuellen Editor, das CMS und Inhalts-Scoping auf Komponentenebene freizuschalten — dieser Schritt ist jedoch völlig optional und kann schrittweise durchgeführt werden.

Inhaltsverzeichnis

Schnelle Migration

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

1. 1

   Abhängigkeiten installieren

   Installieren Sie die Intlayer-Kernpakete und den Kompatibilitätsadapter @intlayer/next-intl:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   Behalten Sie next-intl installiert — es wird weiterhin für URL-Routing (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter) benötigt. Der Kompatibilitätsadapter ersetzt die Routing-Schicht nicht.

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 Nachrichtendateien:

   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({
         // 'icu' entspricht der ICU-Platzhalter-Syntax von next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   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: 'icu' stellt sicher, dass ICU-Platzhalter wie {name} und {count, plural, one {# item} other {# items}} korrekt verarbeitet werden.

   Eine vollständige Liste der Konfigurationsoptionen finden Sie in der Konfigurations-Dokumentation.

3. 3

   Das Intlayer-Plugin in Next.js integrieren

   Kapseln Sie Ihre bestehende Next.js-Konfiguration mit createNextIntlPlugin aus @intlayer/next-intl/plugin. Dieser Wrapper wendet withIntlayer an und registriert den Alias next-intl → @intlayer/next-intl für Sie:

   next.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* Ihre bestehenden Konfigurationsoptionen */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() kapselt withIntlayer, erkennt automatisch Webpack oder Turbopack, verbindet die Inhaltsüberwachung, kompiliert die Wörterbücher und — entscheidend — injiziert Modul-Aliase, sodass Ihre bestehenden Aufrufe für import … from 'next-intl' zur Build-Zeit transparent auf @intlayer/next-intl umgeleitet werden. Der Routing-Einstiegspunkt next-intl/routing verweist weiterhin auf das eigentliche Paket. Es sind keine Änderungen an den Quelldateien erforderlich.

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

   Sie benötigen getRequestConfig oder loadMessages nicht mehr. Mit next-intl mussten Sie eine Datei src/i18n.ts schreiben, die JSON-Nachrichtenpakete bei jeder Anfrage über getRequestConfig lud. Intlayer kompiliert alle Wörterbücher zur Build-Zeit, daher entfällt das Laden zur Laufzeit. Sie können diese Datei vollständig löschen (oder nur die Routing-Teile behalten, falls Sie weiterhin createNavigation verwenden).

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

Typisierte Übersetzungsschlüssel — automatisch. Sobald Intlayer Ihre Wörterbücher kompiliert hat, sind useTranslations und getTranslations 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

// Client-Komponente — 'about' ist ein registrierter Dictionary-Schlüsselconst t = useTranslations("about");t("counter.label"); // ✓ autovervollständigtt("does.not.exist"); // ✗ TypeScript-Fehler// Server-Komponenteconst t = await getTranslations("about");t("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

   Der createNextIntlPlugin()-Wrapper übernimmt bereits das Aliasing next-intl → @intlayer/next-intl auf Bundler-Ebene. Wenn Sie die Abhängigkeit in Ihren Quelldateien explizit machen möchten (und stattdessen das einfache withIntlayer-Plugin verwenden), 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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Behalten Sie immer die Routing-Importe aus dem echten next-intl bei — der Kompatibilitätsadapter ersetzt die URL-Routing-Schicht nicht:

   ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   // ✅ Diese immer aus dem echten 'next-intl' importierenimport { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Alternativ können Sie defineRouting aus @intlayer/next-intl/routing verwenden, welches Ihre in intlayer.config.ts definierten Locale-Einstellungen automatisch zusammenführt.

2. 5

   Aktivieren der KI-gestützten Übersetzungsautomatisierung

   Optional

   Sobald Intlayer konfiguriert ist, können Sie die CLI verwenden, um fehlende Übersetzungen automatisch mithilfe des LLM Ihrer Wahl 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 einen OPENAI_API_KEY (oder den Schlüssel Ihres bevorzugten Anbieters) zu Ihrer .env-Datei hinzu und erweitern Sie Ihre intlayer.config.ts:

   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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 @intlayer/next-intl eingerichtet ist, kann der folgende Standard-next-intl-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 about.content.ts direkt neben Ihrer about/page.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 — Vollständige Einrichtungsanleitung für Next.js: intlayerwithnextjs_16.md