Lokalisasi React dengan i18next

Membangun aplikasi React untuk audiens global memerlukan strategi internasionalisasi (i18n) yang tangguh. react-i18next adalah pustaka lokalisasi React paling populer, yang dibangun di atas kerangka kerja i18next yang telah teruji. Panduan ini menuntun Anda melalui semua yang Anda perlukan untuk melokalisasi aplikasi React Anda—mulai dari pengaturan awal hingga otomatisasi siap produksi dengan terjemahan berbasis AI.

Mengapa Memilih react-i18next untuk Lokalisasi React?

react-i18next adalah standar de facto untuk internasionalisasi React, yang dipercaya oleh ribuan aplikasi produksi di seluruh dunia. Inilah alasan pengembang memilihnya:

• API Berbasis Hook - Hook useTranslation() menyediakan integrasi React yang bersih dan idiomatik dengan rendering ulang otomatis saat bahasa diubah.
• Ekosistem yang Kaya - Plugin untuk deteksi bahasa, backend HTTP, caching, dan banyak lagi. Perluas fungsionalitas tanpa harus membuat ulang dari nol.
• Format Terjemahan JSON - Menggunakan file JSON standar yang mudah diedit, dikontrol versinya, serta diintegrasikan dengan alat terjemahan dan layanan AI.
• Dukungan Namespace - Atur terjemahan ke dalam kelompok logis (auth, dashboard, errors) agar lebih mudah dipelihara dan dimuat secara malas (lazy loading).
• Siap untuk SSR & Next.js - Bekerja dengan mulus bersama server-side rendering, React Server Components, dan Next.js App Router.
• Dukungan TypeScript - Keamanan tipe penuh untuk kunci terjemahan dengan pelengkapan otomatis, yang mendeteksi kunci yang hilang saat kompilasi.

Instalasi

Instal react-i18next dan pustaka inti i18next:

npm install react-i18next i18next

Plugin Opsional

Plugin populer ini meningkatkan pengaturan i18next Anda dengan deteksi bahasa otomatis dan terjemahan yang dimuat secara malas:

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Struktur Proyek yang Disarankan

Struktur proyek yang terorganisir dengan baik menjaga terjemahan Anda tetap mudah dipelihara seiring bertambahnya bahasa:

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

Format File JSON Terjemahan

react-i18next menggunakan file JSON bersarang untuk terjemahan. Kunci mendukung notasi titik, interpolasi dengan {{variables}}, dan pluralisasi bawaan:

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Kunci Bersarang - Atur terjemahan secara hierarkis (misalnya, welcome.title, nav.home) untuk struktur yang jelas.
• Interpolasi - Gunakan sintaks {{variableName}} untuk nilai dinamis yang dimasukkan saat runtime.
• Pluralisasi - Tambahkan akhiran _one dan _other (atau _zero, _two, _few, _many untuk bahasa yang kompleks) untuk penanganan jamak otomatis.
• Konteks - Gunakan akhiran _male, _female untuk terjemahan spesifik gender jika diperlukan.

Mengonfigurasi i18next

i18next mendukung dua pendekatan utama untuk memuat terjemahan: HTTP backend (lazy loading) dan sumber daya yang dibundel. Pilih berdasarkan kebutuhan aplikasi Anda.

HTTP Backend (Disarankan untuk Aplikasi Besar)

Muat terjemahan sesuai permintaan dari file JSON di server Anda. Ini menjaga ukuran bundel awal Anda tetap kecil dan ideal untuk aplikasi dengan banyak bahasa atau file terjemahan yang besar:

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Sumber Daya yang Dibundel (Pendekatan Sederhana)

Impor terjemahan langsung ke dalam bundel. Terbaik untuk aplikasi yang lebih kecil atau saat Anda membutuhkan terjemahan tersedia segera tanpa permintaan jaringan:

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Inisialisasi di Aplikasi Anda

Impor file konfigurasi i18n di titik masuk aplikasi Anda sebelum merender komponen apa pun. Ini memastikan terjemahan dimuat sebelum UI Anda dirender:

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Menerjemahkan Komponen React

react-i18next menyediakan dua API utama untuk menerjemahkan komponen: hook useTranslation untuk akses terprogram dan komponen Trans untuk teks kaya dengan JSX.

Hook useTranslation

Hook useTranslation adalah cara paling umum untuk mengakses terjemahan dalam komponen fungsional. Hook ini menyediakan fungsi t() dan secara otomatis merender ulang saat bahasa berubah:

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Komponen Trans untuk Teks Kaya

Saat terjemahan berisi elemen HTML atau JSX (tebal, tautan, dll.), gunakan komponen Trans. Komponen ini mempertahankan pohon komponen React Anda di dalam terjemahan:

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Menangani Pluralisasi

i18next menangani bentuk jamak secara otomatis berdasarkan aturan jamak ICU untuk setiap bahasa. Berikan parameter count, dan i18next akan memilih bentuk jamak yang benar:

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Tambahkan akhiran _one dan _other ke kunci terjemahan Anda untuk bahasa Inggris
• Untuk bahasa dengan aturan jamak yang kompleks (Arab, Polandia, Rusia), tambahkan akhiran _zero, _two, _few, _many sesuai kebutuhan
• i18next secara otomatis memilih bentuk yang benar berdasarkan aturan jamak CLDR bahasa target

Mengatur dengan Namespace

Namespace memungkinkan Anda membagi terjemahan ke dalam file terpisah berdasarkan fitur atau domain. Ini meningkatkan kemudahan pemeliharaan dan memungkinkan pemuatan malas bundel terjemahan:

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Peralihan Bahasa Dinamis

react-i18next membuat peralihan bahasa menjadi mulus. Panggil i18n.changeLanguage() dan semua komponen yang menggunakan useTranslation akan secara otomatis merender ulang dengan bahasa baru:

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense dan Lazy Loading

react-i18next terintegrasi dengan React Suspense untuk menangani pemuatan terjemahan asinkron dengan baik. Saat menggunakan HTTP backend, Suspense menyediakan status pemuatan yang bersih saat terjemahan sedang diambil:

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

Kunci Terjemahan Aman-Tipe TypeScript

i18next mendukung integrasi TypeScript penuh. Dengan menambah modul i18next, Anda mendapatkan pelengkapan otomatis dan pemeriksaan waktu kompilasi untuk semua kunci terjemahan—mencegah kesalahan ketik dan terjemahan yang hilang:

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Server-Side Rendering dengan Next.js

Untuk aplikasi Next.js yang menggunakan App Router, Anda dapat menggunakan i18next pada komponen server dan klien. Buat instance i18next terpisah untuk terjemahan sisi server agar tidak berbagi status antar permintaan:

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Buat instance i18next baru per permintaan di server untuk mencegah kebocoran status antar pengguna
• Gunakan file JSON terjemahan yang sama untuk rendering sisi server dan klien
• Pertimbangkan i18next-resources-to-backend atau next-intl sebagai alternatif untuk pengaturan Next.js yang kompleks

Percepat Terjemahan dengan AI

Menyiapkan react-i18next hanyalah setengah dari perjuangan—Anda masih memerlukan terjemahan berkualitas tinggi untuk setiap bahasa target. Menerjemahkan lusinan file JSON secara manual itu lambat, mahal, dan rentan kesalahan. Terjemahan berbasis AI mengubah segalanya.

Mengapa Menggunakan l10n.dev untuk React i18next?

l10n.dev dibuat khusus untuk alur kerja lokalisasi pengembang. Alat ini memahami file terjemahan JSON Anda secara asli dan menghasilkan terjemahan yang terasa alami, bukan hasil mesin:

• Dukungan JSON asli — Unggah translation.json Anda dan dapatkan kembali file JSON yang diformat dengan sempurna dan siap digunakan
• AI yang sadar konteks — Memahami domain aplikasi Anda, menjaga istilah teknis dan suara merek di berbagai bahasa
• Aman terhadap interpolasi — Mempertahankan {{variables}}, akhiran jamak (_one, _other), dan struktur kunci bersarang
• Terjemahan batch — Terjemahkan ke 10+ bahasa secara bersamaan dalam hitungan detik, bukan hari
• Integrasi CI/CD — Otomatiskan terjemahan sebagai bagian dari pipeline build Anda dengan paket npm ai-l10n

Alur Kerja Terjemahan AI

1. Tulis translation.json sumber Anda dalam bahasa Inggris (atau bahasa dasar Anda)
2. Unggah ke l10n.dev atau jalankan CLI ai-l10n untuk menerjemahkan
3. AI menghasilkan terjemahan yang akurat secara kontekstual untuk semua bahasa target
4. Masukkan file JSON yang telah diterjemahkan ke direktori locales/ Anda dan lakukan deploy

Otomatiskan Terjemahan dengan CLI ai-l10n

Paket npm ai-l10n mengintegrasikan terjemahan AI langsung ke dalam alur kerja pengembangan Anda. Terjemahkan file JSON Anda dari baris perintah:

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Integrasi Build

Tambahkan otomatisasi terjemahan ke pipeline build Anda agar terjemahan selalu diperbarui:

Skrip package.json

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Untuk detail lebih lanjut tentang integrasi CI/CD dan otomatisasi, lihat Panduan Otomatisasi Lokalisasi

Ekstensi VS Code untuk Terjemahan JSON

Terjemahkan file JSON react-i18next Anda langsung dari VS Code. Ekstensi l10n.dev memungkinkan Anda menerjemahkan file tanpa meninggalkan editor Anda:

Cara Kerjanya

1. Instal ekstensi l10n.dev dari VS Code Marketplace
2. Buka file translation.json sumber Anda
3. Klik kanan dan pilih 'Translate with l10n.dev'
4. Pilih bahasa target Anda dan dapatkan file terjemahan secara instan

Mulai Lokalisasi Aplikasi React Anda Hari Ini

Anda sekarang memiliki semua yang diperlukan untuk membangun aplikasi React yang sepenuhnya terlokalisasi dengan react-i18next. Gabungkan kekuatan ekosistem i18next yang matang dengan terjemahan berbasis AI untuk merilis aplikasi Anda dalam bahasa apa pun, dengan cepat.