Migration von i18next zu Intlayer

Warum von i18next zu Intlayer migrieren?

Migrationsstrategien

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

1. Kompatibilitätsadapter (empfohlen für bestehende Apps) — Installieren Sie @intlayer/i18next. Dieses Paket bietet genau dieselbe API wie i18next, delegiert aber die gesamte Übersetzungsarbeit im Hintergrund an Intlayer. Sie behalten Ihre bestehenden Aufrufe für i18next.t(), i18next.changeLanguage() und createInstance() bei — die einzige Änderung ist der Importpfad und die Initialisierung.

2. Vollständige Migration — Ersetzen Sie schrittweise i18next-APIs durch native Intlayer-Werkzeuge und platzieren Sie Inhalte lokal in .content.ts-Dateien.

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

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

   Sie können i18next installiert lassen — der Kompatibilitätsadapter verwendet es als devDependency / peerDependency für TypeScript-Typen.

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({
         // Entspricht der Platzhalter-Syntax von 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. 3

   Bundler-Aliase aktualisieren (Optional)

   Wenn Sie einen Bundler verwenden (Vite, Webpack, esbuild), können Sie einen Modul-Alias einfügen, sodass import ... from 'i18next' automatisch auf @intlayer/i18next aufgelöst wird. Dadurch entfällt die Notwendigkeit, Importe in Ihrer Codebasis manuell zu ändern.

   Für Vite:

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() kapselt das Plugin intlayer() von vite-intlayer und fügt automatisch den Alias i18next → @intlayer/i18next für Sie hinzu. Wenn Sie das normale intlayer()-Plugin von vite-intlayer verwenden, werden die Wörterbücher zwar kompiliert, der Alias wird jedoch nicht hinzugefügt — dann müssten Sie Importe manuell in @intlayer/i18next umbenennen (siehe nächster Schritt).

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

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

   Wenn Sie die Abhängigkeit in Ihren Quelldateien explizit machen möchten oder keinen Bundler-Plugin zur Aliasbildung von Importen 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 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'

   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: ({ 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 der Kompatibilitätsadapter vorhanden ist, kann der folgende Standard-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 Logik 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 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