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.

Zainstaluj pakiety rdzenia Intlayer i adapter compat:

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ą AInpx 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