Autor:
    Aymeric PINEAU
    Data utworzenia:2026-06-05Ostatnia aktualizacja:2026-06-05

    Migracja z vue-i18n do Intlayer

    Dlaczego migrować z vue-i18n do Intlayer?

    Zamiast ładować ogromne pliki JSON do stron, ładuj tylko niezbędną zawartość. Intlayer pomaga zmniejszyć bundle i rozmiary stron nawet o 50%.

    Ograniczanie zawartości aplikacji ułatwia utrzymanie dużych aplikacji. Możesz zduplikować lub usunąć jeden folder funkcji bez konieczności przeglądania całej bazy kodu zawartości. Ponadto Intlayer jest w pełni wpisany aby zapewnić dokładność zawartości.

    Intlayer jest również rozwiązaniem z najaktywniejszym rozwojem w ekosystemie i18n — problemy są naprawiane szybko, nowe adaptery frameworku pojawiają się regularnie, a podstawowy API jest stale ulepsszany na podstawie opinii z produkcji.

    Umieszczanie zawartości razem zmniejsza kontekst potrzebny przez Duże Modele Języka (LLM). Intlayer zawiera również pakiet narzędzi, takich jak CLI do testowania brakujących tłumaczeń, LSP, MCP i agent skills, aby jeszcze bardziej gładka była doświadczenie dla programistów (DX) dla agentów AI.

    Użyj automatyzacji do tłumaczenia w pipeline CI/CD korzystając z wybranego LLM za koszt dostawcy AI. Intlayer oferuje również kompilator do automatycznego wyodrębniania zawartości, a także platforma internetowa aby pomóc tłumaczyć w tle.

    Łączenie dużych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Intlayer optymalizuje ładowanie zawartości w czasie budowania.

    Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia samodzielnie hostowany edytor wizualny i pełny CMS aby pomóc ci zarządzać multilingual zawartością w rzeczywistym czasie, czyniąc współpracę z tłumaczami, copywriterami i innymi członkami zespołu bezproblemową. Zawartość może być przechowywana lokalnie i/lub zdalnie.

    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. Zainstaluj zależności

      Zainstaluj pakiety rdzenia Intlayer i adapter compat:

      bash
      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
      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. 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
      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: "icu",
      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: 'icu' zapewnia, że symbole zastępcze są analizowane poprawnie dla vue-i18n.

    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
      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
      npm install nuxt-intlayer
      nuxt.config.ts
      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
    // '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. 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:

      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. 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
      # 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
      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",     // domyślnie
    // model: "gpt-4o-mini",   // domyślnie
  },
};

export default config;
      Aby uzyskać wszystkie dostępne opcje, zapoznaj się z 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:

    File / pattern Dlaczego nie jest już potrzebny
    createI18n() calls Provider Intlayer inicjalizuje wszystko automatycznie; nie ma kroku ładowania w czasie wykonywania.
    Vue plugin registration (app.use(i18n)) Plugin Intlayer obsługuje iniekcję i bootstrapping pod maską.
    JSON language bundles (locales/*.json) Pakiety JSON są potrzebne tylko jeśli nadal używasz pluginu syncJSON. Po migracji do plików .content.ts możesz usunąć folder JSON.

    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:

    tsconfig.json
    {
  // ... 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:

    .gitignore
    # Ignoruj pliki wygenerowane przez Intlayer
.intlayer

    Przejdź dalej

    Dlaczego Intlayer?