Skip to main content

Panduan Lengkap Pengantarabangsaan React

Daripada sifar hingga berbilang bahasa: sediakan i18n dalam aplikasi React, kemudian automatikkan terjemahan dengan AI.

1

Pasang Pakej

Anda memerlukan tiga pakej: react-i18next (pengikatan React), i18next (pustaka teras), dan i18next-browser-languagedetector sebagai pilihan untuk mengesan bahasa secara automatik.

react-i18next menyediakan cangkuk dan komponen React. i18next ialah enjin teras yang mengendalikan pemuatan terjemahan, interpolasi, dan bentuk jamak. Pemalam pengesan bahasa membaca keutamaan bahasa pelayar secara automatik.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Konfigurasikan Kejadian i18n

Cipta fail konfigurasi i18n yang memulakan i18next dengan bahasa lalai, sumber terjemahan, dan rantaian pemalam. Fail ini perlu diimport pada titik masuk aplikasi sebelum sebarang komponen dipaparkan.

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

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)  // Must come before .init()
  .init({
    fallbackLng: 'en',
    debug: process.env.NODE_ENV === 'development',
    interpolation: {
      escapeValue: false,  // React already escapes
    },
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },
  });

export default i18n;
"You will need to pass in an i18next instance by using initReactI18next"—ralat ini bermaksud anda terlupa memanggil i18n.use(initReactI18next) sebelum i18n.init(). Panggilan .use() perlu ditempatkan sebelum .init().
3

Balut Aplikasi dengan I18nextProvider

Import fail konfigurasi i18n pada akar aplikasi dan balut pepohon komponen dengan I18nextProvider. Tanpanya, useTranslation() mengembalikan kekunci mentah, bukan teks terjemahan.

src/main.tsx
import React, { Suspense } from 'react';
import ReactDOM from 'react-dom/client';
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';  // Import your config
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Suspense fallback={<div>Loading...</div>}>
      <I18nextProvider i18n={i18n}>
        <App />
      </I18nextProvider>
    </Suspense>
  </React.StrictMode>
);
Jika terjemahan memaparkan kekunci mentah seperti "welcome" dan bukannya "Welcome to our app", punca paling biasa ialah I18nextProvider yang tiada atau fail konfigurasi i18n yang belum diimport.
4

Cipta Fail Terjemahan

Cipta satu fail JSON untuk setiap bahasa. Gunakan kekunci tersarang untuk menyusun rentetan mengikut ciri atau halaman. Jadikan bahasa sumber (biasanya bahasa Inggeris) sebagai satu-satunya sumber rujukan.

public/locales/en/translation.json
// public/locales/en/translation.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {{name}}!",
  "cart": {
    "itemCount_one": "{{count}} item",
    "itemCount_other": "{{count}} items"
  }
}

// public/locales/de/translation.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "itemCount_one": "{{count}} Artikel",
    "itemCount_other": "{{count}} Artikel"
  }
}
Namakan kekunci berdasarkan perkara yang diterangkannya, bukan tempat ia muncul: "cart.itemCount" lebih baik daripada "homepageCartLabel". Kekunci sepatutnya kekal selepas UI direka semula.
5

Gunakan Terjemahan dalam Komponen

Panggil useTranslation() dalam sebarang komponen untuk mendapatkan fungsi t(). Gunakannya untuk rentetan ringkas, pemboleh ubah interpolasi, dan terjemahan yang dibenamkan dalam JSX dengan komponen Trans.

Greeting.tsx
import { useTranslation } from 'react-i18next';

function Greeting({ userName }: { userName: string }) {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('greeting', { name: userName })}</h1>
      <nav>
        <a href="/">{t('nav.home')}</a>
        <a href="/about">{t('nav.about')}</a>
      </nav>
    </div>
  );
}
Trans component for JSX
import { Trans, useTranslation } from 'react-i18next';

// For JSX inside translations:
// "terms": "By signing up, you agree to our <link>Terms</link>."

function SignUp() {
  const { t } = useTranslation();
  return (
    <Trans i18nKey="terms" components={{
      link: <a href="/terms" className="underline" />
    }} />
  );
}
Kekunci dinamik seperti t(`error.$'{code}'`) berfungsi semasa masa jalan, tetapi tidak boleh diekstrak secara statik oleh alat seperti i18next-scanner. Jika menggunakan alat pengekstrakan, senaraikan kekunci dinamik secara jelas atau gunakan petunjuk komen.
6

Kendalikan Bentuk Jamak dan Pemboleh Ubah

i18next mengendalikan bentuk jamak dengan peraturan CLDR—bukan hanya tunggal/jamak. Bahasa Arab mempunyai 6 bentuk (zero, one, two, few, many, other). Jepun mempunyai 1 (other). Takrifkan semua bentuk yang diperlukan dalam fail terjemahan dan i18next akan memilih bentuk yang betul secara automatik.

Plural forms by language
// English: 2 forms (one, other)
{
  "itemCount_one": "{{count}} item",
  "itemCount_other": "{{count}} items"
}

// Arabic: 6 forms (zero, one, two, few, many, other)
{
  "itemCount_zero": "لا عناصر",
  "itemCount_one": "عنصر واحد",
  "itemCount_two": "عنصران",
  "itemCount_few": "{{count}} عناصر",
  "itemCount_many": "{{count}} عنصرًا",
  "itemCount_other": "{{count}} عنصر"
}

// Japanese: 1 form (other)
{
  "itemCount_other": "{{count}}個のアイテム"
}
Jangan sekali-kali mengkod keras count === 1 untuk mengesan bentuk tunggal. Bahasa seperti Perancis menganggap 0 sebagai tunggal. Rusia, Arab, dan Poland mempunyai bentuk yang tiada dalam bahasa Inggeris. Biarkan i18next mengendalikan peraturan bentuk jamak.
7

Tambahkan Penukaran dan Pengesanan Bahasa

Bina pemilih bahasa yang memanggil i18n.changeLanguage(). Gabungkan dengan pengesan bahasa pelayar untuk mengesan bahasa pilihan pengguna secara automatik pada lawatan pertama, kemudian simpan pilihan jelas mereka.

LanguageSwitcher.tsx
import { useTranslation } from 'react-i18next';

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

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

  return (
    <select
      value={i18n.language}
      onChange={(e) => i18n.changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>{label}</option>
      ))}
    </select>
  );
}
Jika anda menggunakan SSR (Next.js, Remix), pelayan mungkin mengesan bahasa yang berbeza daripada klien (pelayan tidak mempunyai keutamaan pelayar). Ini menyebabkan ketidakpadanan hydration. Penyelesaian: teruskan bahasa yang dikesan daripada pelayan kepada klien sebagai prop atau kuki supaya kedua-duanya memaparkan bahasa yang sama.
8

Automatikkan Terjemahan

Selepas persediaan i18n selesai, terjemah fail bahasa dengan AI. Dalam IDE, minta pembantu AI menterjemah fail sumber atau gunakan CLI i18n Agent dalam saluran CI/CD.

Terminal
# In your IDE, ask your AI assistant:
> Translate public/locales/en/translation.json to German, Japanese, and Spanish

✓ de/translation.json created (1.2s)
✓ ja/translation.json created (1.5s)
✓ es/translation.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate public/locales/en/translation.json --lang de,ja,es
Terjemah secara berperingkat—apabila menambahkan kekunci baharu pada fail sumber, terjemah hanya perbezaannya dan bukannya menjana semula semua fail. Ini mengekalkan terjemahan yang telah disemak manusia.

Automatikkan Kualiti Terjemahan

Kesan kekunci hilang dan ruang letak rosak sebelum dikeluarkan dengan i18n-validate. Uji UI dengan terjemahan palsu menggunakan i18n-pseudo sebelum terjemahan sebenar tersedia.

Kesilapan Umum

Terjemahan Memaparkan Kekunci Mentah

Punca: I18nextProvider tiada, konfigurasi i18n tidak diimport pada akar aplikasi, ruang nama belum dimuatkan, atau terjemahan masih dimuatkan secara tidak segerak. Periksa konsol pelayar dengan debug: true untuk mendapatkan petunjuk.

Ralat Suspense Tanpa Sandaran

"A component suspended while responding to synchronous input"—tambahkan sempadan '&lt;Suspense&gt;' di sekeliling aplikasi atau tetapkan useSuspense: false dalam konfigurasi init i18next.

Ketidakpadanan Hidrasi SSR

Pelayan memaparkan satu bahasa, tetapi klien melakukan hydration dalam bahasa lain. Pastikan kedua-duanya menggunakan sumber bahasa yang sama—teruskan sebagai prop daripada pelayan dan jangan hanya bergantung pada pengesanan pelayar.

Tiada Pelengkapan Automatik untuk Kekunci Terjemahan

Lanjutkan modul i18next dengan jenis sumber anda: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Ini memberikan panggilan t() yang selamat dari segi jenis dengan pelengkapan automatik.

Struktur Fail yang Disyorkan

Project Structure
my-react-app/
├── public/
│   └── locales/
│       ├── en/
│       │   ├── translation.json    # Default namespace
│       │   ├── common.json         # Shared strings
│       │   └── dashboard.json      # Feature namespace
│       ├── de/
│       │   ├── translation.json
│       │   ├── common.json
│       │   └── dashboard.json
│       └── ja/
│           └── ...
├── src/
│   ├── i18n.ts                     # i18n configuration
│   ├── main.tsx                    # App entry with Provider
│   ├── App.tsx
│   └── components/
│       └── LanguageSwitcher.tsx
└── package.json

Terjemah juga:

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

JSON, YAML, PO, XML, CSV, Markdown, Properties

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Soalan Lazim