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

Lingui.js adalah kerangka kerja internasionalisasi (i18n) yang ringan namun kuat untuk aplikasi JavaScript dan React. Ini menggunakan file PO (Portable Object) standar industri untuk katalog terjemahan, makro waktu kompilasi yang kuat untuk pengalaman pengembang yang bersih, dan menghasilkan bundel yang dioptimalkan 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, kinerja, dan alur kerja terjemahan profesional:

• Bersih dan Mudah Dibaca: Tulis terjemahan secara alami menggunakan makro JSX - pustaka mengompilasinya ke ICU MessageFormat di balik layar.
• Universal: @lingui/core bekerja di proyek JavaScript apa pun, sementara @lingui/react menambahkan komponen khusus React termasuk dukungan React Server Components (RSC).
• Dukungan Teks Kaya 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 setiap alat terjemahan, TMS, dan alur kerja penerjemah profesional.
• Ringan dan Dioptimalkan: Pustaka inti di bawah 2 kB gzipped, komponen React hanya menambah 1,3 kB. Data yang tidak penting dihapus pada 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 saat terbang:

// 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 besar tetap dapat dibaca manusia dengan pasangan msgid/msgstr yang jelas.
• Komentar Penerjemah: Mendukung komentar #. yang membawa deskripsi konteks langsung ke penerjemah.
• Referensi Sumber: Setiap pesan menyertakan komentar #: file:line 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 terjemahan (Prancis)

Setelah diterjemahkan, setiap msgstr diisi dengan versi yang dilokalisasi. 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 yang dioptimalkan.

Makro Trans

Bungkus konten JSX apa pun dalam makro Trans untuk membuatnya 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 makro hook useLingui dengan literal templat bertag:

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 penjamakan CLDR. Makro Plural memudahkan penanganan berbagai bentuk penjamakan langsung di JSX:

• Gunakan komponen Plural dengan nilai, one, other, dan bentuk eksak opsional (_0, _2, dll.).
• Placeholder # secara otomatis diganti dengan nilai penjamakan.
• l10n.dev menghasilkan semua bentuk penjamakan yang diperlukan untuk setiap bahasa target - termasuk bahasa dengan penjamakan 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 saat terbang 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 untuk membuat terjemahan tersedia bagi 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 katalog PO, dan compile untuk mengonversi file PO menjadi modul JavaScript yang dioptimalkan 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. Ekstrak: Memindai file sumber Anda dan membuat atau memperbarui katalog PO dengan semua pesan yang dapat diterjemahkan.
2. Terjemahkan: Isi bidang msgstr dalam file PO Anda - secara manual, dengan TMS, atau secara otomatis dengan terjemahan bertenaga AI.
3. Kompilasi: Mengonversi 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 diterjemahkan dengan 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 benar.
• Sadar ICU MessageFormat: Placeholder ({name}), tag terindeks (<0>), bentuk penjamakan, dan ekspresi pilih 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 Penjamakan: Semua bentuk penjamakan CLDR yang diperlukan dihasilkan untuk setiap bahasa target. Bahasa dengan aturan penjamakan 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 mempertahankan terjemahan yang ada.

Otomatisasi Terjemahan dengan npm

Gunakan paket npm ai-l10n untuk menerjemahkan katalog PO Lingui Anda dari baris perintah atau sebagai bagian dari alur 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 dalam proses build Lingui Anda sehingga 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 semuanya. Skrip i18n menjalankan alur 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 beberapa file, dan contoh alur kerja GitHub Actions, lihat Panduan Otomatisasi Lokalisasi.

Ekstensi VS Code

Ekstensi VS Code l10n.dev menghadirkan 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 beberapa bahasa target (misalnya, Prancis, Jepang, Jerman).
4. Ekstensi membuat file PO terjemahan di folder lokal yang sesuai, siap untuk dikompilasi.

Mulai Melokalisasi Aplikasi React Anda dengan Lingui

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