Lokalisasi React dengan react-i18next

Membangun aplikasi React untuk audiens global memerlukan strategi internasionalisasi (i18n) yang kuat. react-i18next adalah pustaka lokalisasi React paling populer, dibangun di atas kerangka kerja i18next yang telah teruji. Panduan ini memandu Anda melalui semua yang Anda butuhkan untuk melokalkan 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, 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 perenderan ulang otomatis saat bahasa berubah.
• Ekosistem yang Kaya - Plugin untuk deteksi bahasa, backend HTTP, caching, dan banyak lagi. Perluas fungsionalitas tanpa harus membuat ulang dari awal.
• Format Terjemahan JSON - Menggunakan file JSON standar yang mudah diedit, dikontrol versinya, dan diintegrasikan dengan alat penerjemahan serta layanan AI.
• Dukungan Namespace - Atur terjemahan ke dalam grup logis (auth, dasbor, kesalahan) untuk pemeliharaan yang lebih baik dan pemuatan malas (lazy loading).
• Siap SSR & Next.js - Bekerja dengan mulus dengan perenderan sisi server, Komponen Server React, dan Router Aplikasi Next.js.
• Dukungan TypeScript - Keamanan tipe penuh untuk kunci terjemahan dengan pelengkapan otomatis, menangkap kunci yang hilang pada waktu 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 Direkomendasikan

Struktur proyek yang terorganisir dengan baik menjaga terjemahan Anda tetap dapat dipelihara saat Anda menambahkan lebih banyak 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 {{variabel}}, 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 disisipkan saat runtime.
• Pluralisasi - Tambahkan akhiran _one dan _other (atau _zero, _two, _few, _many untuk bahasa kompleks) untuk penanganan jamak otomatis.
• Konteks - Gunakan akhiran _male, _female untuk terjemahan khusus gender saat diperlukan.

Mengonfigurasi i18next

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

Backend HTTP (Direkomendasikan untuk Aplikasi Besar)

Muat terjemahan sesuai permintaan dari file JSON di server Anda. Ini menjaga 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 memerlukan terjemahan yang 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;

Menginisialisasi 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. 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. Ini melestarikan pohon komponen React Anda 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 hitungan, dan i18next 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 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 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 Pemuatan Malas

react-i18next terintegrasi dengan React Suspense untuk menangani pemuatan terjemahan asinkron dengan anggun. Saat menggunakan backend HTTP, Suspense menyediakan status pemuatan yang bersih saat terjemahan 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

Perenderan Sisi Server dengan Next.js

Untuk aplikasi Next.js yang menggunakan Router Aplikasi, Anda dapat menggunakan i18next pada komponen server maupun klien. Buat instance i18next terpisah untuk terjemahan sisi server guna menghindari 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 perenderan sisi server maupun 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 puluhan 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 buatan mesin:

• Dukungan JSON asli — Unggah translation.json Anda dan dapatkan kembali file JSON yang diformat dengan sempurna dan siap digunakan
• AI sadar konteks — Memahami domain aplikasi Anda, melestarikan istilah teknis dan suara merek di seluruh bahasa
• Aman interpolasi — Melestarikan {{variabel}}, 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 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 mutakhir:

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 Marketplace VS Code
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 Lokalkan Aplikasi React Anda Hari Ini

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