Migrasi dari next-intl ke Intlayer

Mengapa bermigrasi dari next-intl ke Intlayer?

Strategi Migrasi

Pendekatan yang direkomendasikan untuk aplikasi yang sudah ada adalah compat adapter: instal @intlayer/next-intl, yang mengekspos API yang persis sama seperti next-intl tetapi mendelegasikan semua pekerjaan terjemahan ke Intlayer di balik layar.

Anda tetap mempertahankan useTranslations, getTranslations, NextIntlClientProvider dan teman-temannya — satu-satunya perubahan adalah jalur impor. Tidak ada refactoring dari signature pemanggilan, bentuk prop, atau struktur komponen yang diperlukan.

Seiring waktu, Anda dapat secara opsional memigrasikan file individual ke format .content.ts yang lebih kaya dari Intlayer untuk membuka visual editor, CMS, dan scoping konten per-komponen — tetapi langkah tersebut sepenuhnya opsional dan dapat dilakukan secara bertahap.

Daftar Isi

Migrasi Cepat

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

1. 1

   Install Dependencies

   Instal paket inti Intlayer dan adapter kompatibilitas @intlayer/next-intl:

   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. Contohnya:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin

   Pertahankan next-intl yang terinstal — masih diperlukan untuk URL routing (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). Adapter kompatibilitas tidak menggantikan lapisan routing.

2. 2

   Konfigurasi Intlayer

   Perintah intlayer init membuat starter intlayer.config.ts. Perbarui untuk mencocokkan locale yang 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({
         // 'icu' cocok dengan sintaks placeholder ICU next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source memetakan locale ke jalur file JSON-nya. location memberitahu watcher Intlayer folder mana yang dipantau untuk perubahan. Opsi format: 'icu' memastikan placeholder ICU seperti {name} dan {count, plural, one {# item} other {# items}} diuraikan dengan benar.

   Untuk daftar lengkap opsi konfigurasi, lihat dokumentasi konfigurasi.

3. 3

   Tambahkan Plugin Intlayer ke Next.js

   Bungkus konfigurasi Next.js yang ada dengan createNextIntlPlugin dari @intlayer/next-intl/plugin. Wrapper ini mengomposisi withIntlayer dan mendaftarkan alias next-intl → @intlayer/next-intl untuk Anda:

   next.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* opsi konfigurasi yang sudah ada */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() membungkus withIntlayer, secara otomatis mendeteksi Webpack atau Turbopack, mengatur pengawasan konten, kompilasi kamus, dan — secara kritis — menyuntikkan alias modul sehingga panggilan import … from 'next-intl' yang sudah ada dialihkan secara transparan ke @intlayer/next-intl pada waktu build. Entri routing next-intl/routing dibiarkan menunjuk ke paket aslinya. Tidak ada perubahan file sumber yang diperlukan.

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

   Anda tidak lagi memerlukan getRequestConfig atau loadMessages. Dengan next-intl, Anda harus menulis file src/i18n.ts yang memuat bundle pesan JSON pada setiap permintaan melalui getRequestConfig. Intlayer mengkompilasi semua kamus pada waktu build, jadi tidak ada langkah loading runtime. Anda dapat menghapus file itu sepenuhnya (atau pertahankan hanya bagian routing jika Anda masih menggunakan createNavigation).

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

Kunci terjemahan yang diketik — otomatis. Setelah Intlayer mengkompilasi kamus Anda, useTranslations dan getTranslations 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 setup tambahan yang diperlukan.

tsx

Salin konten

Salin kode

Salin kode ke clipboard

// Komponen klien — 'about' adalah kunci kamus yang terdaftarconst t = useTranslations("about");t("counter.label"); // ✓ autocompletedt("does.not.exist"); // ✗ kesalahan TypeScript// Komponen serverconst t = await getTranslations("about");t("counter.label"); // ✓ diketik

Migrasi Lengkap

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

1. 4

   Explicit import renaming (optional)

   Opsional

   Wrapper createNextIntlPlugin() sudah menangani aliasing next-intl → @intlayer/next-intl di level bundler. Jika Anda lebih suka membuat dependensi eksplisit di file sumber Anda (dan menggunakan plugin withIntlayer biasa), 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

   Sebelum	Sesudah
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Selalu pertahankan routing imports dari next-intl yang asli — compat adapter tidak mengganti URL routing layer:

   ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   // ✅ Selalu pertahankan imports ini dari 'next-intl' yang asliimport { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Alternatifnya, Anda dapat menggunakan defineRouting dari @intlayer/next-intl/routing yang secara otomatis menggabungkan konfigurasi locale dari intlayer.config.ts Anda.

2. 5

   Enable AI-Powered Translation Automation

   Opsional

   Setelah Intlayer terhubung, Anda dapat menggunakan CLI-nya untuk mengisi terjemahan yang hilang secara otomatis menggunakan LLM pilihan Anda:

   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 OPENAI_API_KEY (atau kunci provider pilihan Anda) ke file .env Anda, kemudian perluas intlayer.config.ts 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],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 @intlayer/next-intl diterapkan, boilerplate next-intl 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 about.content.ts tepat di samping about/page.tsx Anda dan Intlayer akan mengambilnya pada waktu build tanpa konfigurasi tambahan — tidak ada imports, tidak ada registrasi, tidak ada file indeks terpusat yang diperlukan. Ini membuat co-locating translations dengan pages dan components menjadi sepenuhnya frictionless.

Konfigurasi TypeScript

Intlayer menggunakan module augmentation untuk memberikan full TypeScript intellisense untuk translation keys Anda. Pastikan tsconfig.json Anda mencakup jenis yang di-generate secara otomatis:

{  // ... Konfigurasi TypeScript yang sudah ada  "include": [    // ... Konfigurasi TypeScript yang sudah ada    ".intlayer/**/*.ts", // Sertakan jenis yang di-generate 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 — Externalize dan kelola konten dari jarak jauh: Intlayer CMS
• VS Code Extension — Dapatkan autocompletion dan deteksi error terjemahan real-time: Intlayer VS Code Extension
• CLI Reference — Daftar lengkap perintah CLI: Intlayer CLI
• Intlayer with Next.js — Panduan setup lengkap untuk Next.js: intlayerwithnextjs_16.md