Migrasi dari i18next ke Intlayer

Mengapa bermigrasi dari i18next ke Intlayer?

Strategi Migrasi

Ada dua strategi komplementer untuk migrasi dari i18next ke Intlayer:

1. Compat adapter (direkomendasikan untuk aplikasi yang sudah ada) — Install @intlayer/i18next. Package ini mengekspos API yang sama persis dengan i18next namun mendelegasikan semua pekerjaan terjemahan ke Intlayer di balik layar. Anda menyimpan panggilan i18next.t(), i18next.changeLanguage(), dan createInstance() yang sudah ada — satu-satunya perubahan adalah jalur import dan inisialisasi.

2. Migrasi penuh — Secara bertahap ganti API i18next dengan tools native Intlayer dan co-locate konten dalam file .content.ts.

Panduan ini mencakup Strategi 1 terlebih dahulu (drop-in compat adapter), kemudian menjelaskan migrasi penuh yang bersifat opsional.

Daftar Isi

Migrasi Cepat

Langkah-langkah berikut adalah minimum yang diperlukan untuk menjalankan aplikasi i18next yang sudah ada di Intlayer tanpa perubahan kode sama sekali.

1. 1

   Install Dependencies

   Install paket core Intlayer dan adapter kompatibilitas:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   npx intlayer-cli init --interactive

   flag --interactive bersifat opsional. Gunakan intlayer-cli init jika Anda adalah agen AI.

   Perintah ini akan mendeteksi lingkungan Anda dan menginstal paket yang diperlukan. Misalnya:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   Anda dapat menjaga i18next tetap terpasang — adapter kompatibilitas menggunakannya sebagai devDependency / peerDependency untuk tipe TypeScript.

2. 2

   Configure Intlayer

   Perintah intlayer init membuat file intlayer.config.ts pemula. Perbarui untuk mencocokkan locale yang sudah ada dan arahkan plugin syncJSON ke file pesan Anda:

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Tambahkan semua locale yang sudah ada di sini
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // cocok dengan sintaks placeholder i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source memetakan locale ke jalur file JSON-nya. location memberitahu Intlayer watcher folder mana yang harus dipantau untuk perubahan. Opsi format: 'i18next' memastikan bahwa placeholder seperti {{name}} diurai dengan benar.

3. 3

   Update Bundler Aliases (Optional)

   Jika Anda menggunakan bundler (Vite, Webpack, esbuild), Anda dapat menyuntikkan alias modul sehingga import ... from 'i18next' secara otomatis diselesaikan ke @intlayer/i18next. Ini menghilangkan kebutuhan untuk mengubah impor apa pun di codebase Anda secara manual.

   Untuk Vite:

   vite.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   i18nextVitePlugin() membungkus plugin intlayer() dari vite-intlayer dan menambahkan alias i18next → @intlayer/i18next untuk Anda. Menggunakan plugin intlayer() biasa dari vite-intlayer mengompilasi kamus tetapi tidak menambahkan alias itu — Anda kemudian harus mengganti nama impor ke @intlayer/i18next secara manual (lihat langkah berikutnya).

Itu saja untuk migrasi cepat. Aplikasi Anda sekarang berjalan di Intlayer sambil mempertahankan setiap impor dan API i18next.

Migrasi Lengkap

Langkah-langkah di bawah ini bersifat opsional dan dapat dilakukan secara bertahap. Mereka membuka akses ke rangkaian fitur Intlayer yang lengkap: editor visual, CMS, file konten yang diketik, terjemahan bertenaga AI, dan lainnya.

1. 4

   Explicit import renaming (optional)

   Opsional

   Jika Anda lebih suka membuat dependensi eksplisit dalam file sumber Anda, atau jika Anda tidak menggunakan plugin bundler untuk alias imports, Anda dapat mengganti nama imports secara manual:

   Tampilkan semua isi tabel

   Tampilkan semua isi tabel

   Buka tabel dalam modal untuk melihat semua isi data dengan jelas

   Before	After
   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'

   Ini adalah drop-in replacements — tidak ada perubahan yang diperlukan pada call signatures, arguments, atau return types.

2. 5

   Enable AI-Powered Translation Automation

   Opsional

   Setelah Intlayer terhubung, gunakan CLI-nya untuk mengisi terjemahan yang hilang secara otomatis:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   Tambahkan konfigurasi AI ke intlayer.config.ts:

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   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",     // default
       // model: "gpt-4o-mini",   // default
     },
   };
   
   export default config;

   Lihat dokumentasi Intlayer CLI untuk semua opsi yang tersedia.

Apa yang dapat Anda hapus setelah migrasi

Setelah adapter kompatibilitas sudah tersedia, boilerplate i18next berikut dapat dihapus:

Ketika Anda siap untuk melangkah lebih jauh, Intlayer secara otomatis menemukan semua file .content.ts dan .content.json di mana saja dalam codebase Anda (secara default, di mana saja di dalam ./src). Anda dapat menempatkan file my-component.content.ts tepat di sebelah logika Anda dan Intlayer akan mengambilnya pada saat build tanpa konfigurasi tambahan — tidak ada impor, tidak ada pendaftaran, tidak ada file indeks terpusat yang diperlukan. Ini membuat co-locating translations menjadi sepenuhnya lancar.

Konfigurasi TypeScript

Intlayer menggunakan module augmentation untuk memberikan intellisense TypeScript lengkap untuk kunci terjemahan Anda. Pastikan tsconfig.json Anda menyertakan tipe yang dibuat secara otomatis:

{  // ... Konfigurasi TypeScript yang sudah ada  "include": [    // ... Konfigurasi TypeScript yang sudah ada    ".intlayer/**/*.ts", // Sertakan tipe yang dibuat secara otomatis  ],}

Konfigurasi Git

Tambahkan direktori yang dihasilkan oleh Intlayer ke .gitignore Anda:

# Abaikan file yang dihasilkan oleh Intlayer.intlayer

Lanjutkan Lebih Jauh

• Visual Editor — Kelola terjemahan secara visual di browser Anda: Intlayer Visual Editor
• CMS — Eksternal dan kelola konten dari jarak jauh: Intlayer CMS
• VS Code Extension — Dapatkan autocompletion dan deteksi kesalahan terjemahan real-time: Intlayer VS Code Extension
• CLI Reference — Daftar lengkap perintah CLI: Intlayer CLI