Bermigrasi dari next-i18next ke Intlayer

Mengapa migrasi dari next-i18next ke Intlayer?

Strategi Migrasi

Karena next-i18next membungkus react-i18next dan i18next di bawah tenda, ada dua strategi pelengkap untuk migrasi ke Intlayer:

1. Compat adapter (direkomendasikan untuk aplikasi yang sudah ada) — Instal @intlayer/next-i18next, @intlayer/react-i18next, dan @intlayer/i18next. Paket-paket ini mengekspos API yang persis sama seperti rekan-rekan mereka tetapi mendelegasikan semua pekerjaan terjemahan ke Intlayer di bawah tenda. Anda menjaga panggilan useTranslation, appWithTranslation, serverSideTranslations yang ada, dan routing Next.js Pages tetap tidak berubah — satu-satunya perubahan adalah inisialisasi.

2. Migrasi penuh — Secara bertahap ganti API next-i18next dengan hook Intlayer native (useIntlayer) dan co-locate content dalam file .content.ts bersama komponen Anda.

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

Daftar Isi

Migrasi Cepat

Langkah-langkah berikut adalah persyaratan minimum untuk menjalankan aplikasi Next.js Pages Router Anda yang sudah ada di Intlayer tanpa perubahan kode di halaman dan komponen Anda.

1. 1

   Install Dependencies

   Pasang paket inti 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 memasang paket yang diperlukan. Contohnya:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   Anda dapat dengan aman menyimpan next-i18next, react-i18next, dan i18next yang terinstal selama migrasi, meskipun Anda akan menghapusnya setelah dialias.

2. 2

   Configure Intlayer

   Perintah intlayer init membuat file intlayer.config.ts pemula. Perbarui untuk mencocokkan lokal yang ada dan arahkan plugin syncJSON ke file pesan next-i18next Anda (biasanya di dalam public/locales):

   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 lokal yang sudah ada di sini
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // cocok dengan sintaks placeholder i18next: {{name}}
         format: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source memetakan lokal dan namespace (key) ke jalur file JSON-nya. location memberi tahu pengawas Intlayer folder mana yang akan dipantau untuk perubahan. Opsi format: 'i18next' memastikan placeholder diurai dengan benar untuk next-i18next.

3. 3

   Update Next.js Configuration

   Bungkus next.config.ts (atau .js) yang sudah ada dengan createNextI18nPlugin dari @intlayer/next-i18next/plugin. Wrapper ini membuat withIntlayer dan menyuntikkan alias next-i18next / react-i18next / i18next → @intlayer/*, sehingga panggilan import { useTranslation } from 'next-i18next' yang sudah ada dialihkan secara transparan saat build. Tidak ada perubahan file sumber yang diperlukan.

   next.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // Anda dapat menghapus konfigurasi i18n yang diimpor dari next-i18next.config.js
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer mengelola rute i18n Next.js di balik layar,
     // jadi Anda tidak perlu lagi meneruskan objek i18n di sini.
   };
   
   export default withIntlayer(nextConfig);

   Anda tidak lagi memerlukan next-i18next.config.js. Intlayer mengkompilasi semua kamus pada waktu build, menangani deteksi lokal, rute, dan pemuatan kamus dengan mulus.

   Lebih suka withIntlayer biasa dari next-intlayer/server? Ini mengkompilasi kamus Anda tetapi tidak menambahkan alias next-i18next / react-i18next / i18next — Anda kemudian dapat mengganti nama impor ke @intlayer/* secara manual (lihat Langkah 4).

Itulah migrasi cepat. Aplikasi Next.js Anda sekarang berjalan di Intlayer sambil menjaga setiap panggilan useTranslation, serverSideTranslations, dan appWithTranslation tetap utuh.

Kunci terjemahan yang diketik — otomatis. Setelah Intlayer mengkompilasi kamus Anda, useTranslation dan getFixedT diketik terhadap konten aktual Anda. Kunci secara otomatis dilengkapi di IDE Anda dan jalur yang tidak valid menyebabkan kesalahan TypeScript pada waktu build — tidak ada pengaturan tambahan yang diperlukan.

tsx

Salin konten

Salin kode

Salin kode ke clipboard

// Pages Router — 'about' adalah kunci kamus yang terdaftarconst { t } = useTranslation("about");t("counter.label"); // ✓ autocompletedt("does.not.exist"); // ✗ TypeScript error// getStaticProps / getServerSideProps (instans i18next)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ typed

Migrasi Lengkap

Langkah-langkah di bawah ini bersifat opsional dan dapat dilakukan secara bertahap. Langkah-langkah ini membuka fitur Intlayer lengkap: visual editor, CMS, typed content files, AI-powered translation, dan banyak lagi.

1. 4

   Explicit import renaming (optional)

   Opsional

   Plugin Intlayer sudah menangani aliasing di tingkat bundler. Jika Anda lebih suka membuat dependensi eksplisit di file sumber Anda, Anda dapat mengganti nama import secara manual:

   Tampilkan semua isi tabel

   Tampilkan semua isi tabel

   Buka tabel dalam modal untuk melihat semua isi data dengan jelas

   Sebelum	Sesudah
   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'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-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 untuk terjemahan yang hilang (tambahkan ke CI)npx intlayer test# Isi terjemahan yang hilang dengan 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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/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 diterapkan, boilerplate next-i18next berikut dapat dihapus:

Ketika Anda siap untuk melangkah lebih jauh, Intlayer secara otomatis menemukan semua file .content.ts dan .content.json di mana pun dalam codebase Anda (secara default, di mana pun di dalam ./src). Anda dapat menempatkan file my-component.content.ts tepat di sebelah MyComponent.tsx Anda dan Intlayer akan mengambilnya pada waktu build tanpa konfigurasi tambahan — tidak ada imports, registrasi, atau file index terpusat yang diperlukan. Ini membuat co-locating terjemahan dengan halaman dan komponen sepenuhnya tanpa hambatan.

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 Intlayer ke .gitignore Anda:

# Ignore the files generated by Intlayer.intlayer

Selanjutnya

• Visual Editor — Kelola terjemahan secara visual di browser Anda: Intlayer Visual Editor
• CMS — Externalisasi dan kelola konten dari jarak jauh: Intlayer CMS
• VS Code Extension — Dapatkan autokompletion dan deteksi kesalahan terjemahan real-time: Intlayer VS Code Extension
• CLI Reference — Daftar lengkap perintah CLI: Intlayer CLI
• Intlayer with Next.js (Pages Router) — Panduan setup lengkap untuk Next.js: intlayerwithnextjspagerouter.md