Skip to main content

The Complete Guide to React Internationalization

From zero to multilingual: set up i18n in your React app, then automate translations with AI.

1

Csomagok telepítése

Három csomagra van szükség: react-i18next (React-kötések), i18next (alapkönyvtár), valamint opcionálisan i18next-browser-languagedetector a területi beállítás automatikus felismeréséhez.

A react-i18next React-hookokat és -komponenseket biztosít. Az i18next az alapmotor, amely a fordítások betöltését, az interpolációt és a többes számok kezelését végzi. A nyelvfelismerő bővítmény automatikusan beolvassa a böngésző nyelvi beállítását.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Az i18n-példány konfigurálása

Hozzon létre egy i18n-konfigurációs fájlt, amely az alapértelmezett nyelvvel, a fordítási erőforrásokkal és a bővítménylánccal inicializálja az i18nextet. A fájlt az alkalmazás belépési pontján, még bármely komponens megjelenítése előtt importálni kell.

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” — ez a hiba azt jelenti, hogy az i18n.init() előtt elmaradt az i18n.use(initReactI18next) meghívása. A .use() hívásnak meg kell előznie az .init() hívást.
3

Az alkalmazás körülvétele I18nextProviderrel

Importálja az i18n-konfigurációs fájlt az alkalmazás gyökerében, és vegye körül a komponensfát I18nextProviderrel. Enélkül a useTranslation() a lefordított szöveg helyett a nyers kulcsokat adja vissza.

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>
);
Ha a fordítások a „Welcome to our app” helyett olyan nyers kulcsokat jelenítenek meg, mint a „welcome”, ennek leggyakoribb oka a hiányzó I18nextProvider vagy az i18n-konfigurációs fájl importjának elmaradása.
4

Fordítási fájlok létrehozása

Hozzon létre nyelvenként egy JSON-fájlt. Beágyazott kulcsokkal rendezze a karakterláncokat funkció vagy oldal szerint. A forrásnyelv — általában az angol — maradjon az egyetlen hiteles forrás.

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"
  }
}
A kulcsokat a jelentésük, ne a megjelenési helyük alapján nevezze el: a „cart.itemCount” jobb, mint a „homepageCartLabel”. A kulcsoknak a felület újratervezését is túl kell élniük.
5

Fordítások használata komponensekben

Bármely komponensben hívja meg a useTranslation() függvényt a t() függvény lekéréséhez. Használja egyszerű karakterláncokhoz, interpolált változókhoz és a Trans komponenssel beágyazott JSX-fordításokhoz.

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" />
    }} />
  );
}
Az olyan dinamikus kulcsok, mint a t(`error.$'{code}'`), futásidőben működnek, de az i18next-scannerhez hasonló eszközök nem tudják őket statikusan kinyerni. Kinyerőeszköz használatakor sorolja fel kifejezetten a dinamikus kulcsokat, vagy használjon megjegyzéses útmutatást.
6

Többes számok és változók kezelése

Az i18next a CLDR szabályai szerint kezeli a többes számokat, nem pusztán egyes és többes számként. Az arabnak 6 alakja van (zero, one, two, few, many, other), a japánnak 1 (other). Határozza meg az összes szükséges alakot a fordítási fájlokban, az i18next pedig automatikusan kiválasztja a megfelelőt.

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}}個のアイテム"
}
Soha ne kódolja be a count === 1 feltételt az egyes szám felismeréséhez. A francia például a 0-t is egyes számként kezeli. Az oroszban, arabban és lengyelben olyan alakok vannak, amelyek az angolból hiányoznak. Bízza az i18nextre a többes számú szabályok kezelését.
7

Nyelvváltás és -felismerés hozzáadása

Készítsen nyelvválasztót, amely meghívja az i18n.changeLanguage() függvényt. A böngésző nyelvfelismerőjével együtt az első látogatáskor automatikusan azonosíthatja a felhasználó kívánt nyelvét, majd megőrizheti a felhasználó kifejezett választását.

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>
  );
}
SSR — például Next.js vagy Remix — használatakor a szerver a klienstől eltérő nyelvet észlelhet, mert nem fér hozzá a böngésző beállításaihoz. Ez hidratálási eltérést okoz. Megoldás: a felismert területi beállítást tulajdonságként vagy cookie-ban adja át a szerverről a kliensnek, hogy mindkettő ugyanazon a nyelven jelenítsen meg.
8

Fordítások automatizálása

A kész i18n-beállítással AI segítségével fordítsa le a területi fájlokat. Az IDE-ben kérje meg AI-asszisztensét a forrásfájl lefordítására, vagy használja az i18n Agent CLI-t a CI/CD-folyamatban.

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
Fordítson lépésenként: amikor új kulcsokat ad a forrásfájlhoz, az összes fájl újragenerálása helyett csak a különbséget fordítsa le. Így megmaradnak az ember által ellenőrzött fordítások.

A fordítási minőség automatizálása

Az i18n-validate segítségével még kiadás előtt észlelheti a hiányzó kulcsokat és hibás helyőrzőket. A valódi fordítások elkészülte előtt az i18n-pseudo álfordításaival tesztelheti a felületet.

Gyakori buktatók

A fordítások nyers kulcsokat jelenítenek meg

Lehetséges okok: hiányzik az I18nextProvider, az i18n-konfiguráció nincs importálva az alkalmazás gyökerében, a névtér nincs betöltve, vagy a fordítások aszinkron betöltése még tart. Útmutatásért ellenőrizze a böngésző konzolját debug: true beállítással.

Suspense-hiba tartalék nélkül

„A component suspended while responding to synchronous input” — adjon '&lt;Suspense&gt;' határt az alkalmazás köré, vagy állítsa a useSuspense értékét false-ra az i18next init-konfigurációjában.

SSR-hidratálási eltérés

A szerver az egyik, a kliens egy másik területi beállítással hidratál. Gondoskodjon róla, hogy mindkettő ugyanazt a területi forrást használja: tulajdonságként adja át a szerverről, és ne hagyatkozzon kizárólag a böngészős felismerésre.

Nincs automatikus kiegészítés a fordítási kulcsokhoz

Bővítse az i18next modult az erőforrástípussal: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Így típusbiztos t() hívásokat és automatikus kiegészítést kap.

Ajánlott fájlszerkezet

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

Also translate:

Try i18n Agent Now

Drop your translation file here

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

or click to browse

Target languages

No signup requiredInstant estimate

Frequently Asked Questions