Lokalisasi Lingui.js: File PO, i18n React & Otomatisasi

Lingui.js adalah framework internasionalisasi (i18n) yang ringan namun canggih untuk aplikasi JavaScript dan React. Framework ini menggunakan file PO (Portable Object) standar industri untuk katalog terjemahan, makro waktu kompilasi yang canggih untuk pengalaman pengembang yang bersih, dan menghasilkan bundel teroptimasi di bawah 2 kB. Panduan ini mencakup segalanya mulai dari pengaturan proyek hingga alur kerja file PO, penjamakan, dan otomatisasi terjemahan dengan l10n.dev.

Mengapa Lingui.js untuk i18n?

Lingui.js menonjol di antara pustaka i18n JavaScript karena kombinasi pengalaman pengembang, performa, dan alur kerja terjemahan profesional:

• Bersih dan Mudah Dibaca: Tulis terjemahan secara alami menggunakan makro JSX - pustaka ini mengompilasinya ke ICU MessageFormat di balik layar.
• Universal: @lingui/core berfungsi di proyek JavaScript apa pun, sementara @lingui/react menambahkan komponen khusus React termasuk dukungan React Server Components (RSC).
• Dukungan Rich-Text Penuh: Gunakan komponen React di dalam pesan yang dapat diterjemahkan dengan mulus - tautan, teks tebal, ikon, dan JSX apa pun didukung sepenuhnya.
• Format File PO: Menggunakan format PO standar industri yang didukung oleh hampir semua alat terjemahan, TMS, dan alur kerja penerjemah profesional.
• Ringan dan Teroptimasi: Pustaka inti berukuran di bawah 2 kB (gzipped), komponen React hanya menambah 1,3 kB. Data yang tidak penting dihapus saat waktu kompilasi.
• Siap untuk Terjemahan AI: Deskripsi pesan dan komentar konteks Lingui memberikan informasi yang dibutuhkan penerjemah AI untuk menghasilkan terjemahan yang akurat dan sadar konteks.

Instalasi

Instal paket inti dan alat pengembangan Lingui. Paket runtime (@lingui/core dan @lingui/react) diperlukan dalam produksi, sementara CLI, plugin Vite, dan makro Babel hanya untuk pengembangan:

npm install @lingui/core @lingui/react
npm install --save-dev @lingui/cli @lingui/vite-plugin @lingui/babel-plugin-lingui-macro

Konfigurasi

Lingui memerlukan dua file konfigurasi: konfigurasi Lingui (mendefinisikan lokal dan jalur katalog) dan konfigurasi alat build Anda (untuk mengaktifkan makro waktu kompilasi).

Konfigurasi Lingui

Buat file lingui.config.js di root proyek Anda. Ini mendefinisikan lokal sumber, lokal target, tempat menyimpan katalog PO, dan format katalog. Format PO adalah pilihan default dan yang direkomendasikan:

// lingui.config.js
import { defineConfig } from "@lingui/cli";
import { formatter } from "@lingui/format-po";

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "fr", "de", "ja", "es", "zh-CN"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  format: formatter({ lineNumbers: false }),
});

Konfigurasi Vite

Jika Anda menggunakan Vite, tambahkan plugin Lingui bersama plugin React dengan makro Babel. Ini memungkinkan transformasi pesan waktu kompilasi dan kompilasi katalog secara langsung:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingui } from "@lingui/vite-plugin";

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ["@lingui/babel-plugin-lingui-macro"],
      },
    }),
    lingui(),
  ],
});

Format File PO

PO (Portable Object) adalah format file terjemahan standar industri, yang berasal dari sistem GNU gettext. Lingui menggunakan PO sebagai format katalog default karena didukung secara luas oleh alat terjemahan, platform TMS, dan penerjemah profesional di seluruh dunia.

• Mudah Dibaca: Bahkan file terjemahan yang besar tetap dapat dibaca manusia dengan pasangan msgid/msgstr yang jelas.
• Komentar Penerjemah: Mendukung komentar #. yang menyampaikan deskripsi konteks langsung kepada penerjemah.
• Referensi Sumber: Setiap pesan menyertakan komentar #: file:baris yang menunjukkan dengan tepat di mana pesan tersebut digunakan dalam basis kode Anda.
• Dukungan Konteks: Gunakan msgctxt untuk membedakan string identik yang memiliki arti berbeda dalam konteks yang berbeda.
• Dukungan Alat Universal: Kompatibel dengan hampir setiap sistem manajemen terjemahan (TMS), alat CAT, dan platform lokalisasi.

File PO yang diekstraksi (pesan sumber)

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr ""

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr ""

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr ""

File PO yang diterjemahkan (Bahasa Prancis)

Setelah diterjemahkan, setiap msgstr diisi dengan versi yang dilokalkan. Lingui mempertahankan sintaks ICU MessageFormat, tag terindeks untuk komponen React, dan variabel placeholder di semua terjemahan.

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr "Bienvenue sur notre plateforme"

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr "Bonjour {userName}, consultez votre <0>tableau de bord</0> pour commencer."

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr "{itemCount, plural, =0 {Votre panier est vide} one {Vous avez # article dans votre panier} other {Vous avez # articles dans votre panier}}"

Struktur Proyek

Atur katalog PO Anda di dalam direktori locales dengan satu subfolder per lokal. Lingui CLI secara otomatis membuat dan memperbarui file-file ini selama ekstraksi. Modul JS yang dikompilasi dihasilkan pada waktu build dan tidak boleh diedit secara manual.

src/
├── locales/
│   ├── en/
│   │   └── messages.po       ← Source (English)
│   ├── fr/
│   │   └── messages.po       ← French
│   ├── de/
│   │   └── messages.po       ← German
│   ├── ja/
│   │   └── messages.po       ← Japanese
│   ├── es/
│   │   └── messages.po       ← Spanish
│   └── zh-CN/
│       └── messages.po       ← Chinese Simplified
├── components/
├── i18n.ts
├── App.tsx
└── ...

Menerjemahkan Komponen React

Lingui menyediakan dua pendekatan utama untuk menandai pesan: makro JSX untuk konten komponen dan hook useLingui untuk string imperatif. Keduanya adalah makro waktu kompilasi yang menghasilkan output teroptimasi.

Makro Trans

Bungkus konten JSX apa pun dalam makro Trans agar dapat diterjemahkan. Variabel, elemen HTML, dan komponen React didukung sepenuhnya - makro mengubahnya menjadi ICU MessageFormat dengan tag terindeks secara otomatis.

import { Trans } from "@lingui/react/macro";

function WelcomeBanner({ userName }) {
  return (
    <div>
      <h1>
        <Trans>Welcome to our platform</Trans>
      </h1>
      <p>
        <Trans>
          Hello {userName}, check out your <a href="/dashboard">dashboard</a> to
          get started.
        </Trans>
      </p>
    </div>
  );
}

Hook useLingui

Untuk string di luar JSX - pesan peringatan, label aria, nilai atribut, atau kode imperatif apa pun - gunakan hook makro useLingui dengan tagged template literals:

import { useLingui } from "@lingui/react/macro";

function NotificationButton() {
  const { t } = useLingui();

  const showAlert = () => {
    alert(t`Your changes have been saved.`);
  };

  return (
    <button onClick={showAlert} aria-label={t`Save changes`}>
      <Trans>Save</Trans>
    </button>
  );
}

ID Pesan dan Deskripsi

Lingui mendukung dua pendekatan untuk identifikasi pesan: ID yang dibuat otomatis (berasal dari konten pesan sumber) dan ID eksplisit (kunci yang ditentukan pengembang). Kedua pendekatan bekerja dengan file PO.

import { Trans } from "@lingui/react/macro";

// Auto-generated ID (from message content)
<Trans>Welcome to our platform</Trans>

// Explicit ID (developer-defined key)
<Trans id="nav.welcome">Welcome to our platform</Trans>

Menambahkan Konteks untuk Penerjemah dan AI

Gunakan prop comment pada makro apa pun untuk menambahkan deskripsi. Komentar ini diekstraksi ke dalam file PO sebagai catatan penerjemah, memberikan konteks penting tentang di mana dan bagaimana pesan tersebut muncul.

import { Trans } from "@lingui/react/macro";

<Trans comment="Shown on the homepage hero section above the fold">
  Start building with confidence
</Trans>

Penjamakan

Lingui menggunakan ICU MessageFormat untuk penjamakan, yang mendukung semua kategori jamak CLDR. Makro Plural memudahkan penanganan berbagai bentuk jamak langsung di JSX:

• Gunakan komponen Plural dengan nilai, one, other, dan bentuk eksak opsional (_0, _2, dll.).
• Placeholder # secara otomatis diganti dengan nilai jamak.
• l10n.dev menghasilkan semua bentuk jamak yang diperlukan untuk setiap bahasa target - termasuk bahasa kompleks seperti Arab (6 bentuk), Rusia, dan Polandia - tanpa intervensi manual.

import { Plural } from "@lingui/react/macro";

function CartSummary({ itemCount }) {
  return (
    <p>
      <Plural
        value={itemCount}
        _0="Your cart is empty"
        one="You have # item in your cart"
        other="You have # items in your cart"
      />
    </p>
  );
}

Inisialisasi Runtime

Setelah mengekstraksi dan mengompilasi pesan Anda, siapkan instance i18n dan bungkus aplikasi Anda dalam I18nProvider.

Pengaturan Modul i18n

Buat modul i18n yang memuat katalog pesan yang dikompilasi secara dinamis. Plugin Lingui Vite memungkinkan impor langsung file PO, yang dikompilasi secara langsung selama pengembangan:

// src/i18n.ts
import { i18n } from "@lingui/core";

export async function loadCatalog(locale: string) {
  const { messages } = await import(`./locales/${locale}/messages.po`);
  i18n.load(locale, messages);
  i18n.activate(locale);
}

// Initialize with default locale
loadCatalog("en");

export default i18n;

Pengaturan I18nProvider

Bungkus seluruh aplikasi Anda dengan I18nProvider agar terjemahan tersedia untuk semua komponen melalui konteks React:

// src/App.tsx
import { I18nProvider } from "@lingui/react";
import { i18n } from "./i18n";

function App() {
  return (
    <I18nProvider i18n={i18n}>
      <YourAppContent />
    </I18nProvider>
  );
}

Peralihan Bahasa saat Runtime

Mengganti bahasa sangat mudah: muat katalog baru, aktifkan lokal, dan React secara otomatis merender ulang semua konten yang diterjemahkan. Berikut adalah komponen pengalih bahasa yang lengkap:

import { useState } from "react";
import { loadCatalog } from "./i18n";
import { Trans } from "@lingui/react/macro";

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

function LanguageSwitcher() {
  const [currentLocale, setCurrentLocale] = useState("en");

  const handleChange = async (locale: string) => {
    await loadCatalog(locale);
    setCurrentLocale(locale);
  };

  return (
    <select
      value={currentLocale}
      onChange={(e) => handleChange(e.target.value)}
    >
      {Object.entries(LANGUAGES).map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

Alur Kerja Ekstraksi dan Kompilasi

CLI Lingui menyediakan dua perintah utama yang membentuk inti alur kerja terjemahan Anda: extract untuk menarik pesan dari kode sumber ke dalam katalog PO, dan compile untuk mengubah file PO menjadi modul JavaScript yang teroptimasi untuk produksi.

# Extract messages from source code into PO catalogs
npx lingui extract

# Translate your PO files (manually, with a TMS, or with AI)

# Compile PO catalogs into optimized JS modules for production
npx lingui compile

1. Extract: Memindai file sumber Anda dan membuat atau memperbarui katalog PO dengan semua pesan yang dapat diterjemahkan.
2. Translate: Isi kolom msgstr di file PO Anda - secara manual, dengan TMS, atau secara otomatis dengan terjemahan berbasis AI.
3. Compile: Mengubah katalog PO menjadi modul JS ringan yang dimuat saat runtime. Hanya pesan yang diterjemahkan yang disertakan.

Dukungan PO Penuh di l10n.dev

l10n.dev menyediakan dukungan asli untuk file PO, menjadikannya pendamping yang sempurna untuk proyek Lingui.js. Unggah katalog PO sumber Anda dan terima file yang telah diterjemahkan secara akurat:

• Format PO Asli: Unggah file PO secara langsung - l10n.dev membaca entri msgid, menerjemahkannya, dan menulis kembali file PO yang diformat dengan benar dengan nilai msgstr yang tepat.
• Sadar ICU MessageFormat: Placeholder ({name}), tag terindeks (<0>), bentuk jamak, dan ekspresi select dipertahankan dengan benar di semua terjemahan.
• Terjemahan AI Sadar Konteks: Komentar penerjemah (#.) dan konteks pesan (msgctxt) digunakan oleh AI kami untuk menghasilkan terjemahan yang lebih akurat dan sadar konteks.
• Pembuatan Jamak: Semua bentuk jamak CLDR yang diperlukan dihasilkan untuk setiap bahasa target. Bahasa dengan aturan jamak yang kompleks (Arab, Rusia, Polandia) ditangani secara otomatis.
• Pembaruan Batch dan Inkremental: Terjemahkan seluruh katalog sekaligus atau gunakan flag --update untuk menerjemahkan hanya pesan baru dan yang diubah, dengan tetap mempertahankan terjemahan yang ada.

Otomatiskan Terjemahan dengan npm

Gunakan paket npm ai-l10n untuk menerjemahkan katalog PO Lingui Anda dari baris perintah atau sebagai bagian dari pipeline CI/CD. Instal sekali, lalu terjemahkan ke sejumlah bahasa dalam satu perintah.

# Install the CLI
npm install ai-l10n

# Translate your source PO file to multiple languages
npx ai-l10n translate src/locales/en/messages.po \
  --languages fr,de,ja,zh-CN,es,ko

Integrasi ke dalam Proses Build Anda

Hubungkan ai-l10n langsung ke proses build Lingui Anda agar terjemahan selalu mutakhir. Gabungkan ekstraksi, terjemahan, dan kompilasi dalam satu alur kerja.

Melalui skrip package.json

Tambahkan extract, translate, dan compile sebagai skrip dan hubungkan ketiganya. Skrip i18n menjalankan pipeline penuh; gunakan dalam prebuild untuk memastikan terjemahan selalu terkini sebelum pengiriman.

{
  "scripts": {
    "extract": "lingui extract",
    "compile": "lingui compile",
    "translate": "ai-l10n translate src/locales/en/messages.po --languages fr,de,ja,zh-CN,es,ko --update",
    "i18n": "npm run extract && npm run translate && npm run compile",
    "prebuild": "npm run i18n",
    "build": "vite build",
    "dev": "vite"
  }
}

Melalui Makefile

Jika tim Anda menggunakan Make, deklarasikan ekstraksi, terjemahan, dan kompilasi sebagai target terpisah dengan dependensi yang tepat:

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

extract:
	npx lingui extract

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

compile:
	npx lingui compile

i18n: extract translate compile

dev: i18n
	npx vite

build: i18n
	npx vite build

Untuk integrasi CI/CD, pembaruan inkremental, terjemahan batch di berbagai file, dan contoh alur kerja GitHub Actions, lihat Panduan Otomatisasi Lokalisasi.

Ekstensi VS Code

Ekstensi VS Code l10n.dev membawa terjemahan file PO langsung ke editor Anda. Terjemahkan katalog Lingui Anda tanpa meninggalkan VS Code.

Cara Kerjanya di VS Code:

1. Buka file PO sumber Anda (misalnya, src/locales/en/messages.po) di editor.
2. Klik kanan di editor dan pilih "Translate..." (berfungsi dengan file PO juga).
3. Pilih satu atau lebih bahasa target (misalnya, Prancis, Jepang, Jerman).
4. Ekstensi membuat file PO yang diterjemahkan di folder lokal yang sesuai, siap untuk dikompilasi.

Mulai Melokalkan Aplikasi React Anda dengan Lingui

Siap menjangkau pengguna global? Terjemahkan file PO Lingui Anda langsung di ruang kerja l10n.dev, otomatiskan dengan CLI npm, atau terjemahkan langsung di dalam VS Code: