Cara membuat multibahasa (i18n) pada aplikasi Vite dan React yang sudah ada setelahnya (panduan i18n 2026)

Lihat Templat Aplikasi di GitHub.

Daftar Isi

Mengapa sulit untuk menginternasionalisasi aplikasi yang sudah ada?

Jika Anda pernah mencoba menambahkan banyak bahasa ke aplikasi yang dibuat hanya untuk satu bahasa, Anda pasti tahu betapa sulitnya itu. Bukan hanya "sulit", tetapi membosankan. Anda harus menyisir setiap file, memburu setiap untaian teks, dan memindahkannya ke file kamus terpisah.

Kemudian datanglah bagian yang berisiko: mengganti semua teks tersebut dengan hook kode tanpa merusak tata letak atau logika Anda. Ini adalah jenis pekerjaan yang menghentikan pengembangan fitur baru selama berminggu-minggu dan terasa seperti refactoring tanpa akhir.

Apa itu Intlayer Compiler?

Intlayer Compiler dibuat untuk melewati pekerjaan manual yang membosankan itu. Alih-alih Anda mengekstrak string secara manual, kompilator melakukannya untuk Anda. Ia memindai kode Anda, menemukan teks, dan menggunakan AI untuk menghasilkan kamus di balik layar. Kemudian, ia memodifikasi kode Anda selama proses build untuk menyuntikkan hook i18n yang diperlukan. Pada dasarnya, Anda terus menulis aplikasi seolah-olah hanya satu bahasa, dan kompilator menangani transformasi multibahasa secara otomatis.

Dok Kompilator: /id/doc/compiler

Batasan

Karena kompilator melakukan analisis dan transformasi kode (memasukkan hook dan menghasilkan kamus) pada waktu kompilasi, hal ini dapat memperlambat proses build aplikasi Anda.

Untuk mengurangi dampak ini selama pengembangan, Anda dapat mengonfigurasi kompilator agar berjalan dalam mode 'build-only' atau menonaktifkannya saat tidak diperlukan.

Panduan Langkah-demi-Langkah untuk Menyiapkan Intlayer dalam Aplikasi Vite dan React

Langkah 1: Instal Dependensi

Instal paket-paket yang diperlukan menggunakan npm:

npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasi, dan perintah CLI.

• react-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi React. Ini menyediakan penyedia konteks dan hook untuk internasionalisasi React.

• vite-intlayer Termasuk plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi lokal pilihan pengguna, mengelola cookie, dan menangani pengalihan URL.

Langkah 2: Konfigurasi Proyek Anda

Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.INDONESIAN, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  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: "Aplikasi ini adalah aplikasi peta", // Catatan: Anda dapat menyesuaikan deskripsi aplikasi ini  },};export default config;

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

Melalui file konfigurasi ini, Anda dapat mengatur URL yang dilokalkan, pengalihan middleware, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

Langkah 3: Integrasikan Intlayer dalam Konfigurasi Vite Anda

Tambahkan plugin intlayer ke dalam konfigurasi Anda.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerCompiler()],});

Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Ini memastikan pembangunan file deklarasi konten dan memantaunya dalam mode pengembangan. Ini mendefinisikan variabel lingkungan Intlayer dalam aplikasi Vite. Selain itu, ia menyediakan alias untuk mengoptimalkan kinerja.

Plugin Vite intlayerCompiler() digunakan untuk mengekstrak konten dari komponen dan menulis file .content.

Langkah 4: Kompilasi kode Anda

Cukup tulis komponen Anda dengan string yang dikodekan secara keras dalam lokal default Anda. Kompilator menangani sisanya.

Contoh bagaimana tampilan halaman Anda mungkin terlihat:

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt="Vite logo" />       </a>       <a href="https://react.dev" target="_blank">         <img src={reactLogo} className="logo react" alt="React logo" />       </a>     </div>     <h1>Vite + React</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         count is {count}       </button>       <p>         Edit <code>src/App.tsx</code> and save to test HMR       </p>     </div>     <p className="read-the-docs">       Click on the Vite and React logos to learn more     </p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

{ key: "app-content", content: {   nodeType: "translation",   translation: {     en: {       viteLogo: "Vite logo",       reactLogo: "React logo",       title: "Vite + React",       countButton: "count is",       editMessage: "Edit",       hmrMessage: "and save to test HMR",       readTheDocs: "Click on the Vite and React logos to learn more",     },     id: {       viteLogo: "Logo Vite",       reactLogo: "Logo React",       title: "Vite + React",       countButton: "hitungan adalah",       editMessage: "Ubah",       hmrMessage: "dan simpan untuk menguji HMR",       readTheDocs: "Klik pada logo Vite dan React untuk mempelajari lebih lanjut",     },   } }}

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app-content"); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt={content.viteLogo.value} />       </a>       <a href="https://react.dev" target="_blank">         <img           src={reactLogo}           className="logo react"           alt={content.reactLogo.value}         />       </a>     </div>     <h1>{content.title}</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         {content.countButton} {count}       </button>       <p>         {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}       </p>     </div>     <p className="read-the-docs">{content.readTheDocs}</p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

• IntlayerProvider digunakan untuk menyediakan lokal ke komponen bersarang.

(Opsional) Langkah 6: Ubah bahasa konten Anda

Untuk mengubah bahasa konten Anda, Anda dapat menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini memungkinkan Anda untuk mengatur lokal aplikasi dan memperbarui konten yang sesuai.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Ubah Bahasa ke Inggris    </button>  );};

Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

(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) Sitemap dan robots.txt (generate saat build)

Intlayer menyediakan generateSitemap dan getMultilingualUrls untuk memformat sitemap.xml multibahasa dan robots.txt yang siap untuk crawler, lalu menulisnya secara otomatis ke public/. Biasanya skrip Node kecil dijalankan sebelum Vite (misalnya hook npm predev / prebuild).

Sitemap

Generator sitemap Intlayer menghormati konfigurasi locale dan menambahkan metadata untuk crawler.

Sitemap mendukung namespace xhtml:link (hreflang). Alih-alih hanya daftar URL datar, Intlayer menghubungkan semua varian bahasa setiap halaman secara dua arah (mis. /about, /fr/about, atau /about?lang=fr tergantung mode routing).

Robots.txt

Gunakan getMultilingualUrls agar aturan Disallow mencakup semua varian URL jalur sensitif.

1. Buat generate-seo.mjs di root proyek

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Paket intlayer harus terpasang. Setel SITE_URL di lingkungan produksi (misalnya di CI).

Disarankan generate-seo.mjs untuk ESM Node. Jika memakai generate-seo.js, pastikan "type": "module" di package.json atau aktifkan ESM lainnya.

2. Jalankan skrip sebelum Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Sesuaikan perintah jika memakai pnpm atau yarn. Skrip juga bisa dipanggil dari CI.

Konfigurasi Git

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

Untuk melakukannya, 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 Intlayer VS Code resmi.

Instal dari VS Code Marketplace

Ekstensi ini menyediakan:

• Autocompletion untuk kunci terjemahan.
• Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
• Pratinjau sebaris dari konten yang diterjemahkan.
• Tindakan cepat untuk membuat dan memperbarui terjemahan dengan mudah.

Untuk detail lebih lanjut tentang cara menggunakan ekstensi, lihat dokumentasi Ekstensi Intlayer VS Code.

Melangkah Lebih Jauh

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