Migracja z react-i18next / i18next do Intlayer

Dlaczego migrować z react-i18next / i18next do Intlayer?

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

Strategie migracji

Istnieją dwie komplementarne strategie migracji z react-i18next / i18next do Intlayer:

1. Adapter compat (rekomendowany dla istniejących aplikacji): Zainstaluj @intlayer/react-i18next (dla komponentów React) i/lub @intlayer/i18next (dla instancji i18n). Te pakiety ujawniają dokładnie ten sam API co react-i18next / i18next, ale delegują całą pracę tłumaczenia do Intlayer za kulisami. Zachowujesz istniejące useTranslation, Trans, withTranslation, i18next.t(), jedyną zmianą jest ścieżka importu.

2. Pełna migracja: Stopniowo zastępuj API react-i18next natywnymi hakami Intlayer (useIntlayer, IntlayerProvider) 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

Poniższe kroki to minimum wymagane, aby uruchomić istniejącą aplikację react-i18next na Intlayer bez żadnych zmian w kodzie.

1. 1

   Instalacja zależności

   Zainstaluj pakiety rdzenia Intlayer i adaptery kompatybilności:

   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.

   Ta komenda wykryje twoje środowisko i zainstaluje wymagane pakiety. Na przykład:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   

   Możesz zachować zainstalowane react-i18next i i18next, adaptery kompatybilności używają ich jako devDependencies / opcjonalne peerDependencies dla typów TypeScript. Nie musisz zmieniać żadnych peers w package.json.

2. 2

   Konfiguracja Intlayer

   Komenda intlayer init tworzy starter intlayer.config.ts. Zaktualizuj go, aby dopasować się 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 twoje istniejące lokalizacje tutaj
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // pasuje do składni placeholderów react-i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;
   

   source mapuje lokalizację na ścieżkę pliku JSON. location mówi obserwatorowi Intlayer, który folder monitorować pod kątem zmian. Opcja format: 'i18next' zapewnia, że placeholdery takie jak {{name}} są analizowane prawidłowo.

3. 3

   Dodaj wtyczkę Intlayer do twojego bundlera

   Opakuj istniejącą konfigurację bundlera wtyczką kompatybilności. Kompiluje rdzeń wtyczki Intlayer, podłącza obserwowanie treści i, co krityczne, wstrzykuje aliasy modułów, aby twoje istniejące wywołania import … from 'react-i18next' (i 'i18next') były przezroczyście przekierowywane do @intlayer/react-i18next / @intlayer/i18next w czasie budowania. Żadne zmiany pliku źródłowego nie są potrzebne.

   Dla Vite:

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

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

   reactI18nextVitePlugin() opakuje wtyczkę intlayer() z vite-intlayer i dodaje aliasy react-i18next / i18next. Użycie zwykłej wtyczki intlayer() z vite-intlayer kompiluje słowniki, ale nie dodaje tych aliasów, musiałbyś wtedy ręcznie zmienić nazwy importów na @intlayer/* (patrz Krok 4).

   Dla Next.js:

   Jeśli używasz next-i18next (integracja Pages Router), zainstaluj @intlayer/next-i18next i next-intlayer:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install @intlayer/next-i18next next-intlayer
   

   Następnie dodaj wtyczkę kompatybilności do twojego next.config.ts (wstrzykuje aliasy next-i18next / react-i18next / i18next):

   next.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {/* twoje opcje */};
   
   export default withIntlayer(nextConfig);
   

   Nie potrzebujesz już i18next.init() ani ręcznego bootstrappingu providera. Intlayer kompiluje wszystkie słowniki w czasie budowania, więc nie ma kroku ładowania w czasie wykonania. Aliasowany provider obsługuje inicjalizację za ciebie.

To wszystko w kwestii szybkiej migracji. Twoja aplikacja teraz działa na Intlayer, zachowując każdy import i API react-i18next.

Wpisane klucze translacji, automatycznie. Gdy Intlayer skompiluje twoje słowniki, useTranslation i getFixedT są wpisane względem twojej faktycznej treści. Klucze są auto-uzupełniane w twoim IDE, a nieprawidłowe ścieżki powodują błędy TypeScript w czasie budowania, żadna dodatkowa konfiguracja nie jest wymagana.

tsx

Kopiuj zawartość

Kopiuj kod

Skopiuj kod do schowka

// 'about' to zarejestrowany klucz słownika → t() akceptuje tylko prawidłowe ścieżki z kropkami
const { t } = useTranslation("about");
t("counter.label"); // ✓ auto-uzupełniane
t("does.not.exist"); // ✗ błąd TypeScript

// Po stronie serwera (instancja i18next)
const tAbout = i18n.getFixedT(null, "about");
tAbout("counter.label"); // ✓ wpisane

Kompletna migracja

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

1. 4

   Jawne zmieniane nazw importów (opcjonalnie)

   Opcjonalne

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

   Pokaż całą zawartość tabeli

   Pokaż całą zawartość tabeli

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

   Przed	Po
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   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'

   Dla Next.js (next-i18next):

   Pokaż całą zawartość tabeli

   Pokaż całą zawartość tabeli

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

   Przed	Po
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   Włącz automatyzację tłumaczenia wspomaganą przez AI

   Opcjonalne

   Gdy Intlayer jest podłączony, użyj jego CLI, aby automatycznie wypełnić brakujące tłumaczenia:

   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 zapoznać się ze wszystkimi dostępnymi opcjami.

   dokumentacją CLI Intlayer

Co możesz usunąć po migracji

Po umieszczeniu adapterów kompatybilności można usunąć następujący boilerplate react-i18next / i18next:

Gdy będziesz gotowy do dalszych kroków, Intlayer automatycznie odkrywa wszystkie pliki .content.ts i .content.json gdziekolwiek w twojej bazie kodu (domyślnie gdziekolwiek wewnątrz ./src). Możesz umieścić plik my-component.content.ts bezpośrednio obok MyComponent.tsx a Intlayer odbierze go podczas budowania bez dodatkowej konfiguracji, brak importów, rejestracji, brak scentralizowanego pliku indeksu. To sprawia, że współlokalizowanie tłumaczeń ze stronami i komponentami jest całkowicie bezproblemowe.

Konfiguracja TypeScript

Intlayer używa module augmentation, aby zapewnić pełny intellisense TypeScript dla Twoich kluczy tłumaczenia. Upewnij się, że Twój plik tsconfig.json zawiera automatycznie wygenerowane typy:

{
  // ... Twoje istniejące konfiguracje TypeScript
  "include": [
    // ... Twoje istniejące konfiguracje TypeScript
    ".intlayer/**/*.ts", // Dołącz automatycznie wygenerowane typy
  ],
}

Konfiguracja Git

Dodaj wygenerowany przez Intlayer katalog do .gitignore:

# Ignoruj pliki wygenerowane przez Intlayer
.intlayer

Idź dalej