Migracja z i18next do Intlayer

Dlaczego migrować z i18next do Intlayer?

Strategie migracji

Istnieją dwie komplementarne strategie migracji z i18next do Intlayer:

1. Adapter compat (rekomendowany dla istniejących aplikacji) — Zainstaluj @intlayer/i18next. Ten pakiet ujawnia dokładnie ten sam API co i18next, ale deleguje całą pracę tłumaczenia do Intlayer za kulisami. Zachowujesz istniejące i18next.t(), i18next.changeLanguage() i createInstance() — jedyną zmianą jest ścieżka importu i inicjalizacja.

2. Pełna migracja — Stopniowo zastępuj API i18next natywnymi narzędziami Intlayer i umieszczaj zawartość w plikach .content.ts.

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ę i18next na Intlayer bez zmian kodu.

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 @intlayer/i18next @intlayer/sync-json-plugin
   

   Możesz zachować zainstalowany i18next — adapter kompatybilności używa go jako devDependency / peerDependency dla typów TypeScript.

2. 2

   Skonfiguruj Intlayer

   Polecenie intlayer init tworzy starter intlayer.config.ts. Zaktualizuj go, aby odpowiadał Twoim istniejącym lokalizacjom i wskaż wtyczkę syncJSON na Twoje pliki komunikatów:

   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 tutaj wszystkie istniejące lokalizacje
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // pasuje do składni placeholdera i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;
   

   source mapuje locale na ścieżkę pliku JSON. location informuje watcher Intlayera, który folder monitorować pod kątem zmian. Opcja format: 'i18next' zapewnia, że placeholdery takie jak {{name}} są poprawnie parsowane.

3. 3

   Zaktualizuj aliasy bundlera (opcjonalnie)

   Jeśli używasz bundlera (Vite, Webpack, esbuild), możesz wstrzyknąć alias modułu, aby import ... from 'i18next' automatycznie rozpoznawał @intlayer/i18next. To eliminuje potrzebę ręcznej zmiany jakichkolwiek importów w Twoim codebase.

   Dla Vite:

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

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

   i18nextVitePlugin() opakowuje plugin intlayer() z vite-intlayer i dodaje alias i18next → @intlayer/i18next dla Ciebie. Użycie zwykłego pluginu intlayer() z vite-intlayer kompiluje słowniki, ale nie dodaje tego aliasu — musisz wtedy ręcznie zmienić nazwy importów na @intlayer/i18next (zobacz następny krok).

To jest szybka migracja. Twoja aplikacja teraz działa na Intlayer, zachowując wszystkie i18next importy i API w niezmienionej formie.

Pełna migracja

Poniższe kroki są opcjonalne i można je wykonywać stopniowo. Odblokowują one pełny zestaw funkcji Intlayer: edytor wizualny, CMS, pliki zawartości z typami, automatyczne tłumaczenie oparte na AI i wiele więcej.

1. 4

   Jawne zmiana nazwy importu (opcjonalnie)

   Opcjonalne

   Jeśli wolisz uczynić zależność jawną w swoich plikach źródłowych lub jeśli nie używasz wtyczki bundlera do aliasowania importów, 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 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'

   Są to drop-in replacements — nie wymagane są żadne zmiany w sygnaturach funkcji, argumentach ani typach zwracanych.

2. 5

   Włącz automatyzację tłumaczenia opartą na AI

   Opcjonalne

   Gdy Intlayer jest już skonfigurowany, użyj jego CLI do automatycznego wypełnienia brakujących tłumaczeń:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   # Test brakujących tłumaczeń (dodaj do CI)
   npx intlayer test
   
   # Wypełnij brakujące tłumaczenia za pomocą 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: "i18next",
         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;
   

   Zapoznaj się z dokumentacją CLI Intlayer, aby uzyskać wszystkie dostępne opcje.

Co możesz usunąć po migracji

Po umieszczeniu adaptera kompatybilności można usunąć poniższe boilerplate'y i18next:

Gdy będziesz gotów do dalszych kroków, Intlayer automatycznie odkrywa wszystkie pliki .content.ts i .content.json znajdujące się wszędzie w twojej bazie kodu (domyślnie wszędzie wewnątrz ./src). Możesz umieścić plik my-component.content.ts obok swojej logiki, a Intlayer podejmie go podczas kompilacji bez dodatkowej konfiguracji — bez importów, rejestracji ani scentralizowanego pliku indeksu. To sprawia, że współlokowanie tłumaczeń jest całkowicie bezproblemowe.

Konfiguracja TypeScript

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

{
  // ... Twoje istniejące konfiguracje TypeScript
  "include": [
    // ... Twoje istniejące konfiguracje TypeScript
    ".intlayer/**/*.ts", // Załącz auto-generowane typy
  ],
}

Konfiguracja Git

Dodaj wygenerowany katalog Intlayer do .gitignore:

# Ignoruj pliki wygenerowane przez Intlayer
.intlayer

Idź dalej

• Visual Editor — Zarządzaj tłumaczeniami wizualnie w przeglądarce: Intlayer Visual Editor
• CMS — Externalizuj i zarządzaj zawartością zdalnie: Intlayer CMS
• VS Code Extension — Uzyskaj autouzupełnianie i wykrywanie błędów tłumaczenia w czasie rzeczywistym: Intlayer VS Code Extension
• CLI Reference — Pełna lista poleceń CLI: Intlayer CLI