Migracja z vue-i18n do Intlayer

Dlaczego migrować z vue-i18n do Intlayer?

Aby zrozumieć, skąd wzięły się te biblioteki, przeczytaj historię i18n w JavaScript.

Strategie migracji

Istnieją dwie komplementarne strategie migracji z vue-i18n do Intlayer:

1. Adapter compat (rekomendowany dla istniejących aplikacji): Zainstaluj @intlayer/vue-i18n (dla komponentów Vue). Ten pakiet ujawnia dokładnie ten sam API co vue-i18n, ale deleguje całą pracę tłumaczenia do Intlayer za kulisami. Zachowujesz istniejące $t, useI18n() i <i18n-t>, jedyną zmianą jest ścieżka importu i inicjalizacja.

2. Pełna migracja: Stopniowo zastępuj API vue-i18n natywnymi hakami Intlayer (useIntlayer) i umieszczaj zawartość w plikach .content.ts obok komponentów.

Ten przewodnik obejmuje Strategię 1 najpierw (adapter compat drop-in), a następnie przechodzi przez opcjonalną pełną migrację.

Spis treści

Szybka migracja

Następujące kroki są minimalne wymagane aby uruchomić istniejącą aplikację vue-i18n na Intlayer bez zmian kodu w komponentach.

1. 1

   Zainstaluj zależności

   Zainstaluj pakiety rdzenia Intlayer i adapter compat:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npx intlayer init --interactive
   

   flaga --interactive jest opcjonalna. Użyj intlayer-cli init, jeśli jesteś agentem AI.

   To polecenie wykryje Twoje środowisko i zainstaluje wymagane pakiety. Na przykład:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   

   Możesz zachować vue-i18n zainstalowany, adapter kompatybilności używa go jako devDependency / peerDependency dla typów TypeScript.

2. 2

   Konfiguruj Intlayer

   Polecenie intlayer init tworzy plik startowy intlayer.config.ts. Zaktualizuj go, aby pasował do twoich istniejących lokalizacji i wskaż wtyczkę syncJSON na twoje pliki wiadomości:

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Dodaj wszystkie istniejące lokale tutaj
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // pasuje do składni placeholdera vue-i18n: {name}
         format: "vue-i18n",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;
   

   source mapuje ustawienie regionalne na ścieżkę pliku JSON. location informuje obserwatora Intlayer, które foldery monitorować w poszukiwaniu zmian. Opcja format: 'vue-i18n' zapewnia, że symbole zastępcze są analizowane poprawnie dla vue-i18n.

3. 3

   Dodaj wtyczkę Intlayer do swojego bundlera

   Zawiń istniejącą konfigurację bundlera za pomocą wtyczki compat. Komponuje core'owy plugin Intlayer, podłącza obserwację zawartości i, co krytyczne, wstrzykuje alias modułu tak aby istniejące wywołania import … from 'vue-i18n' były transparentnie przekierowywane do @intlayer/vue-i18n w czasie budowania. Nie są wymagane żadne zmiany plików źródłowych.

   Dla Vite:

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

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

   vueI18nVitePlugin() otacza plugin intlayer() z vite-intlayer i dodaje alias vue-i18n. Używając zwykłego pluginu intlayer() z vite-intlayer, kompiluje słowniki, ale nie dodaje aliasu, wtedy musisz ręcznie zmienić nazwy importów na @intlayer/vue-i18n (patrz Krok 4).

   Dla Nuxt:

   Jeśli używasz @nuxtjs/i18n (integracja Nuxt), zainstaluj nuxt-intlayer i dodaj go do swojego nuxt.config.ts:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install nuxt-intlayer
   

   nuxt.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // Możesz bezpiecznie usunąć @nuxtjs/i18n ze swoich modułów
   });
   

   Nie potrzebujesz już createI18n() ani ręcznego inicjowania providera. Intlayer kompiluje wszystkie słowniki w czasie buildowania, więc nie ma kroku ładowania w runtime. Aliasowany provider obsługuje inicjalizację za Ciebie.

To koniec szybkiej migracji. Twoja aplikacja działa teraz na Intlayer, zachowując każdy import vue-i18n i API bez zmian.

Wpisane klucze tłumaczeń, automatycznie. Po skompilowaniu słowników przez Intlayer, useI18n jest typizowany względem rzeczywistej zawartości, gdy przekażesz opcję namespace. Klucze są autocompleted w twoim IDE, a nieprawidłowe ścieżki powodują błędy TypeScript w czasie budowania, nie jest wymagana żadna dodatkowa konfiguracja.

ts

Kopiuj zawartość

Kopiuj kod

Skopiuj kod do schowka

// 'about' to zarejestrowany klucz słownika
const { t } = useI18n({ namespace: "about" });
t("counter.label"); // ✓ autocompleted
t("does.not.exist"); // ✗ TypeScript error

Pełna migracja

Poniższe kroki są opcjonalne i mogą być wykonywane stopniowo. Odblokowują pełny zestaw funkcji Intlayer: edytor wizualny, CMS, pliki zawartości z typami, tłumaczenie wspierane przez AI i wiele więcej.

1. 4

   Jawne zmianę nazwy importu (opcjonalnie)

   Opcjonalne

   Wtyczki Intlayer już obsługują aliasing na poziomie bundlera. Jeśli wolisz uczynić zależność jawną w plikach źródłowych, możesz zmienić nazwy importów ręcznie:

   Pokaż całą zawartość tabeli

   Pokaż całą zawartość tabeli

   Otwórz tabelę w oknie modalnym, aby wyraźnie zobaczyć całą zawartość

   Przed	Po
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   Są to zamiany plug-and-play, nie są wymagane żadne zmiany w sygnaturach funkcji, argumentach ani typach zwracanych.

2. 5

   Włącz automatyczne tłumaczenie wspierane przez AI

   Opcjonalne

   Po połączeniu Intlayer, użyj jego CLI, aby automatycznie uzupełnić brakujące tłumaczenia:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   # Test for missing translations (add to CI)
   npx intlayer test
   
   # Fill missing translations with AI
   npx intlayer fill
   

   Dodaj konfigurację AI do intlayer.config.ts:

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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: "vue-i18n",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // domyślnie
       // model: "gpt-4o-mini",   // domyślnie
     },
   };
   
   export default config;
   

   Aby uzyskać wszystkie dostępne opcje, zapoznaj się z dokumentacją CLI Intlayer.

   dokumentacją CLI Intlayer

Co możesz usunąć po migracji

Gdy adaptery kompatybilności będą na miejscu, możesz usunąć następujący boilerplate vue-i18n:

Gdy będziesz gotowy pójść dalej, Intlayer automatycznie odkrywa wszystkie pliki .content.ts i .content.json gdziekolwiek w twoim codebase (domyślnie gdziekolwiek wewnątrz ./src). Możesz umieścić plik my-component.content.ts bezpośrednio obok twojego MyComponent.vue, a Intlayer podejmie go w czasie budowania bez dodatkowej konfiguracji, bez importów, bez rejestracji, bez scentralizowanego pliku indeksu. To sprawia, że co-lokowanie tłumaczeń ze stronami i komponentami jest całkowicie bezproblemowe.

Konfiguruj TypeScript

Intlayer używa module augmentation, aby zapewnić pełną intellisense TypeScript dla twoich kluczy tłumaczeń. Upewnij się, że twój tsconfig.json zawiera auto-generowane typy:

{
  // ... Twoje istniejące konfiguracje TypeScript
  "include": [
    // ... Twoje istniejące konfiguracje TypeScript
    ".intlayer/**/*.ts", // Uwzględnij auto-generowane typy
  ],
}

Konfiguracja Git

Dodaj wygenerowany przez Intlayer katalog do .gitignore:

# Ignoruj pliki wygenerowane przez Intlayer
.intlayer

Przejdź dalej