Migration von vue-i18n zu Intlayer

Warum von vue-i18n zu Intlayer migrieren?

Migrationsstrategien

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

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

2. Vollständige Migration — Ersetzen Sie schrittweise vue-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 vue-i18n-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 @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   Sie können vue-i18n 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 vue-i18n: {name}
         format: "icu",
         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: 'icu' stellt sicher, dass Platzhalter für vue-i18n korrekt verarbeitet werden.

3. 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 einen Modul-Alias, sodass Ihre bestehenden Aufrufe für import … from 'vue-i18n' zur Build-Zeit nahtlos auf @intlayer/vue-i18n umgeleitet werden. Es sind keine Änderungen an den Quelldateien erforderlich.

   Für Vite:

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin() kapselt das Plugin intlayer() von vite-intlayer und fügt automatisch den Alias vue-i18n 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/vue-i18n umbenennen (siehe Schritt 4).

   Für Nuxt:

   Wenn Sie @nuxtjs/i18n (Nuxt-Integration) verwenden, installieren Sie nuxt-intlayer und fügen Sie es zu Ihrer nuxt.config.ts hinzu:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install nuxt-intlayer

   nuxt.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // Sie können @nuxtjs/i18n aus Ihren Modulen sicher entfernen
   });

   Sie benötigen createI18n() 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 vue-i18n-APIs intakt bleiben.

Typisierte Übersetzungsschlüssel — automatisch. Sobald Intlayer Ihre Wörterbücher kompiliert hat, ist useI18n typisiert gegen Ihre tatsächlichen Inhalte, wenn Sie eine namespace-Option übergeben. 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.

ts

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

// 'about' ist ein registrierter Dictionary-Schlüsselconst { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ autovervollständigtt("does.not.exist"); // ✗ TypeScript-Fehler

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'
   import { createI18n } from 'vue-i18n'	import { createI18n } 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 }) => `./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-vue-i18n-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 Vue — Vollständige Einrichtungsanleitung für Vue: intlayerwithvite+vue.md
• Intlayer mit Nuxt — Vollständige Einrichtungsanleitung für Nuxt: intlayerwithnuxt.md