Cara membuat aplikasi Next.js yang sudah ada menjadi multibahasa (i18n) (Panduan i18n 2026)

Lihat Templat Aplikasi di GitHub.

Daftar Isi

Mengapa internasionalisasi aplikasi yang sudah ada itu sulit?

Jika Anda pernah mencoba menambahkan beberapa bahasa ke aplikasi yang hanya dibuat untuk satu bahasa, Anda pasti tahu tantangannya. Ini bukan sekadar "sulit" - ini melelahkan. Anda harus menelusuri setiap file, menemukan setiap string teks, dan memindahkannya ke file kamus (dictionary) yang terpisah.

Lalu bagian yang berisiko: mengganti semua teks tersebut dengan kait kode (code hooks) tanpa merusak tata letak atau logika. Ini adalah jenis pekerjaan yang menghentikan pengembangan fitur baru selama berminggu-minggu dan terasa seperti refactoring yang tak ada ujungnya.

Apa itu Intlayer Compiler?

Intlayer Compiler dibuat untuk melewati pekerjaan manual tersebut. Alih-alih memaksa Anda mengekstrak string secara manual, kompiler melakukannya untuk Anda. Ia memindai kode Anda, menemukan teks, dan menggunakan AI untuk menghasilkan kamus (dictionary) di latar belakang (background). Kemudian, ia memodifikasi kode sumber (source code) Anda selama langkah build untuk menyuntikkan i18n hooks yang diperlukan. Pada dasarnya, Anda tetap menulis aplikasi Anda seolah-olah dalam satu bahasa, dan kompiler akan menangani transformasi multibahasa secara asli.

Dokumentasi Kompiler: /id/doc/compiler

Keterbatasan

Karena kompiler melakukan analisis dan transformasi kode (menyuntikkan kait dan menghasilkan kamus) pada saat kompilasi (compile time), hal ini dapat memperlambat waktu build aplikasi Anda.

Untuk membatasi dampak ini selama pengembangan aktif (dev mode), Anda dapat mengatur kompiler ke mode 'build-only' atau menonaktifkannya saat tidak diperlukan.

Panduan selangkah demi selangkah untuk mengatur Intlayer dalam aplikasi Next.js

Langkah 1: Instal dependensi

Instal paket-paket yang diperlukan menggunakan pengelola paket favorit Anda:

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasi (transpilation), dan perintah CLI.

• next-intlayer

  Paket yang mengintegrasikan Intlayer dengan Next.js. Ia menyediakan penyedia konteks dan hook untuk internasionalisasi Next.js. Selain itu, paket ini mencakup plugin Next.js untuk mengintegrasikan Intlayer dengan Webpack atau Turbopack, serta middleware untuk mendeteksi preferensi bahasa pengguna, mengelola cookie, dan menangani pengalihan URL.

Langkah 2: Konfigurasi proyek Anda

Buat file konfigurasi untuk mendefinisikan bahasa aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.INDONESIAN],    defaultLocale: Locales.INDONESIAN,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Menunjukkan apakah kompiler harus diaktifkan.     */    enabled: true,    /**     * Direktori output untuk kamus yang dioptimalkan.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Masukkan konten saja dalam file yang dihasilkan, tanpa kunci.     */    noMetadata: false,    /**     * Awalan kunci kamus     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Menunjukkan apakah komponen harus disimpan setelah ditransformasi.     * Dengan begitu, kompiler hanya perlu dijalankan sekali untuk mentransformasi aplikasi, lalu dapat dihapus.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Ini adalah contoh sederhana aplikasi peta",  },};export default config;

Catatan: Pastikan Anda telah menetapkan OPEN_AI_API_KEY di variabel lingkungan Anda.

Melalui file konfigurasi ini, Anda dapat menyiapkan URL yang dilokalkan, pengalihan proxy, pemetaan cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, periksa dokumentasi konfigurasi.

Langkah 3: Integrasikan Intlayer ke dalam konfigurasi Next.js Anda

Konfigurasikan pengaturan Next.js Anda untuk menggunakan Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* Opsional konfigurasi Next.js tambahan di sini */};export default withIntlayer(nextConfig);

Plugin Next.js withIntlayer() digunakan untuk mengintegrasikan Intlayer dengan Next.js. Ini memastikan pembuatan file kamus dan memantaunya dalam mode dev. Ini mendefinisikan variabel lingkungan Intlayer di dalam lingkungan Webpack atau Turbopack. Terlebih lagi, ini menyediakan alias untuk mengoptimalkan kinerja dan bekerja secara menyeluruh dengan Komponen Server.

Konfigurasi Babel

Kompilator Intlayer memerlukan Babel untuk mengekstrak dan mengoptimalkan konten Anda. Perbarui babel.config.js (atau babel.config.json) Anda untuk menyertakan plugin Intlayer:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Langkah 4: Deteksi Bahasa di Halaman Anda

Kosongkan konten RootLayout Anda dan ganti dengan contoh di bawah ini:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Langkah 5: Deklarasikan Konten Anda (Otomatis)

Dengan Kompiler diaktifkan, Anda tidak lagi perlu mendeklarasikan kamus konten (misalnya file .content.ts) secara manual.

Sebagai gantinya, Anda cukup menulis konten sebagai string yang dikodekan secara keras di kode Anda. Intlayer akan memindai kode sumber, menghasilkan terjemahan menggunakan penyedia AI yang dikonfigurasi, dan secara diam-diam mengganti string tersebut dengan konten yang dilokalkan selama langkah kompilasi build. Semuanya benar-benar otomatis.

Cukup tulis komponen Anda dengan string hardcoded dalam bahasa default Anda dan biarkan Intlayer Compiler menangani sisanya.

Contoh tampilan page.tsx Anda:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Mulai dengan mengedit ini!</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditingThis: "Get started by editing this!",    },    fr: {      getStartedByEditingThis: "Commencez par éditer ceci !",    },    id: {      getStartedByEditingThis: "Mulai dengan mengedit ini!",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditingThis}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider digunakan untuk menyediakan bahasa ke komponen sisi klien.

• Sementara IntlayerServerProvider digunakan untuk menyediakan bahasa ke anak-anak server.

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(Opsional) Langkah 7: Isi terjemahan yang hilang

Intlayer menyediakan alat CLI untuk membantu Anda mengisi terjemahan yang hilang. Anda dapat menggunakan perintah intlayer untuk menguji dan mengisi terjemahan yang hilang dari kode Anda.

npx intlayer test         # Uji apakah ada terjemahan yang hilang

npx intlayer fill         # Isi terjemahan yang hilang

Untuk detail lebih lanjut, silakan merujuk ke dokumentasi CLI

(Opsional) Langkah 8: Middleware Proxy Rute Lokal

Jika Anda ingin secara otomatis mengalihkan pengguna ke bahasa pilihan mereka, buat middleware proxy:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

intlayerProxy digunakan untuk mendeteksi bahasa pilihan pengguna dan mengalihkannya ke URL yang sesuai seperti yang ditentukan dalam pengaturan file konfigurasi. Selain itu, ini memungkinkan penyimpanan bahasa pilihan pengguna di cookie.

(Opsional) Langkah 9: Ubah Bahasa Konten

Cara paling direkomendasikan untuk mengubah bahasa konten Anda di Next.js adalah dengan menggunakan komponen Link untuk mengalihkan pengguna ke rute dengan bahasa yang sesuai. Ini memanfaatkan fitur prefetch Next.js dan menghindari penyegaran halaman secara paksa.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Bahasa - contoh: ID */}              {localeItem}            </span>            <span>              {/* Bahasa dalam bahasanya sendiri - contoh: Bahasa Indonesia */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Bahasa dalam bahasa saat ini - contoh: Francés (jika bahasa saat ini adalah Locales.SPANISH) */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Bahasa dalam bahasa Inggris - contoh: Indonesian */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Secara alternatif, Anda dapat menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini tidak mengizinkan prefetch halaman. Periksa dokumentasi hook useLocale untuk detail lebih lanjut.

(Opsional) Langkah 10: Optimalkan Ukuran Bundle

Saat menggunakan next-intlayer, kamus disertakan dalam bundle untuk setiap halaman secara default. Untuk mengoptimalkan ukuran bundle, Intlayer menyediakan plugin SWC opsional yang secara cerdas mengganti panggilan useIntlayer menggunakan makro. Ini memastikan bahwa kamus hanya disertakan dalam bundle halaman yang benar-benar menggunakannya.

Untuk mengaktifkan optimasi ini, instal paket @intlayer/swc. Setelah diinstal, next-intlayer akan secara otomatis mendeteksi dan menggunakan plugin tersebut:

npm install @intlayer/swc --save-dev

Catatan: Optimasi ini hanya tersedia untuk Next.js 13 ke atas.

Catatan: Paket ini tidak diinstal secara default karena plugin SWC masih eksperimental di Next.js. Ini mungkin berubah di masa depan.

Catatan: Jika Anda menyetel opsi sebagai importMode: 'dynamic' atau importMode: 'fetch' (dalam konfigurasi kamus), ini akan bergantung pada Suspense, jadi Anda perlu membungkus panggilan useIntlayer Anda dalam batas Suspense. Ini berarti Anda tidak dapat menggunakan useIntlayer secara langsung di tingkat atas komponen Halaman / Layout Anda.

Konfigurasi TypeScript

Intlayer menggunakan augmentasi modul untuk memanfaatkan keunggulan TypeScript dan membuat basis kode Anda lebih kuat.

Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis.

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

Konfigurasi Git

Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda untuk menghindari mengunggahnya ke repositori Git Anda.

Untuk melakukan ini, Anda dapat menambahkan instruksi berikut ke file .gitignore Anda:

# Abaikan file yang dihasilkan oleh Intlayer.intlayer

Ekstensi VS Code

Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat menginstal Ekstensi VS Code resmi Intlayer.

Instal dari VS Code Marketplace

Ekstensi ini menyediakan:

• Autocomplete untuk kunci terjemahan.
• Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
• Pratinjau inline dari konten yang diterjemahkan.
• Quick actions untuk membuat dan memperbarui terjemahan dengan mudah.

Baca dokumentasi Ekstensi VS Code Intlayer untuk instruksi mendetail tentang penggunaan ekstensi.

(Opsional) Langkah 1 : Ekstrak konten komponen Anda

Jika Anda memiliki basis kode yang ada, mengubah ribuan file bisa memakan waktu lama.

Untuk memudahkan proses ini, Intlayer mengusulkan compiler / extractor untuk mengubah komponen Anda dan mengekstrak kontennya.

Untuk mengaturnya, Anda dapat menambahkan bagian compiler di file intlayer.config.ts Anda:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Sisa konfigurasi Anda
  compiler: {
    /**
     * Menunjukkan apakah compiler harus diaktifkan.
     */
    enabled: true,

    /**
     * Menentukan jalur file output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Menunjukkan apakah komponen harus disimpan setelah diubah. Dengan begitu, compiler dapat dijalankan satu kali saja untuk mengubah aplikasi, lalu dapat dihapus.
     */
    saveComponents: false,

    /**
     * Prefiks kunci kamus
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Ekstrak konten dari komponen ke dalam kamus   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Atau npm run dev

Melangkah Lebih Jauh

Untuk melangkah lebih jauh, Anda dapat mengimplementasikan editor visual atau mengeksternalisasikan konten Anda menggunakan CMS.