Migration von @nuxtjs/i18n zu Intlayer

Warum von @nuxtjs/i18n zu Intlayer migrieren?

Migrationsstrategien

Da @nuxtjs/i18n unter der Haube von vue-i18n betrieben wird, gibt es zwei ergänzende Strategien für die Migration zu Intlayer:

1. Kompatibilitätsadapter (empfohlen für bestehende Apps) — Installieren Sie @intlayer/vue-i18n und nuxt-intlayer. Dies bietet genau dieselbe API wie vue-i18n, delegiert jedoch die gesamte Übersetzungsarbeit an Intlayer. Sie behalten Ihre bestehenden Aufrufe für $t, useI18n() und das Nuxt-Routing unverändert bei — die einzige Änderung ist die Initialisierung.

2. Vollständige Migration — Ersetzen Sie schrittweise @nuxtjs/i18n-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 Nuxt-App auf Intlayer laufen zu lassen, ohne Codeänderungen in Ihren Komponenten 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 vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   Sie können @nuxtjs/i18n während der Migration sicher installiert lassen, obwohl Sie es in Kürze aus Ihrer Nuxt-Konfiguration entfernen werden.

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 vue-i18n: {name}
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "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: 'icu' stellt sicher, dass Platzhalter für vue-i18n korrekt verarbeitet werden.

3. 3

   Nuxt-Konfiguration aktualisieren

   Ersetzen Sie das Modul @nuxtjs/i18n in Ihrer nuxt.config.ts durch nuxt-intlayer. Das Intlayer-Plugin injiziert automatisch Modul-Aliase, was bedeutet, dass Ihre bestehenden Aufrufe von import { useI18n } from 'vue-i18n' nahtlos auf @intlayer/vue-i18n umgeleitet werden.

   nuxt.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   export default defineNuxtConfig({
     // '@nuxtjs/i18n' entfernen
     modules: ["nuxt-intlayer"],
   });

   Sie müssen keine Nuxt i18n-Konfigurationsobjekte mehr definieren. Intlayer kompiliert alle Wörterbücher zur Build-Zeit und übernimmt die Locale-Erkennung, das Routing und das Laden von Wörterbüchern nahtlos.

Das war's für die schnelle Migration. Ihre Nuxt-App läuft nun auf Intlayer, während alle $t-Aufrufe und useI18n() 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

   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:

   Alle Tabellendaten anzeigen

   Alle Tabellendaten anzeigen

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

   Vorher	Nachher
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   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: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "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-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.vue 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 Nuxt — Vollständige Einrichtungsanleitung für Nuxt: intlayerwithnuxt.md
• Intlayer mit Vue — Vollständige Einrichtungsanleitung für Vue: intlayerwithvite+vue.md