Skip to main content

Kompletný sprievodca internacionalizáciou Reactu

Od začiatku až po viacjazyčnú aplikáciu: nastavte i18n vo svojej aplikácii React a potom automatizujte preklady pomocou AI.

1

Nainštalujte balíky

Potrebujete tri balíky: react-i18next (väzby pre React), i18next (základnú knižnicu) a voliteľne i18next-browser-languagedetector na automatické rozpoznanie miestneho nastavenia.

react-i18next poskytuje hooky a komponenty pre React. i18next je základný mechanizmus, ktorý zabezpečuje načítanie prekladov, interpoláciu a tvorbu množného čísla. Doplnok na rozpoznanie jazyka automaticky načíta jazykové nastavenie prehliadača.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Nakonfigurujte inštanciu i18n

Vytvorte konfiguračný súbor i18n, ktorý inicializuje i18next s Vaším predvoleným jazykom, prekladovými zdrojmi a reťazcom doplnkov. Tento súbor sa musí importovať vo vstupnom bode aplikácie pred vykreslením ktoréhokoľvek komponentu.

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" — táto chyba znamená, že ste pred volaním i18n.init() zabudli zavolať i18n.use(initReactI18next). Volanie .use() musí byť uvedené pred .init().
3

Obaľte aplikáciu komponentom I18nextProvider

Importujte konfiguračný súbor i18n v koreňovej časti aplikácie a obaľte strom komponentov komponentom I18nextProvider. Bez neho useTranslation() namiesto preloženého textu vracia nespracované kľúče.

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>
);
Ak sa namiesto textu "Vitajte v našej aplikácii" zobrazujú nespracované kľúče, napríklad "welcome", najčastejšou príčinou je chýbajúci I18nextProvider alebo neimportovaný konfiguračný súbor i18n.
4

Vytvorte prekladové súbory

Pre každý jazyk vytvorte jeden súbor JSON. Pomocou vnorených kľúčov usporiadajte reťazce podľa funkcie alebo stránky. Zdrojový jazyk (zvyčajne angličtinu) používajte ako jediný zdroj pravdy.

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"
  }
}
Kľúče pomenúvajte podľa toho, čo opisujú, nie podľa toho, kde sa zobrazujú: "cart.itemCount" je vhodnejší než "homepageCartLabel". Kľúče by mali zostať použiteľné aj po zmene návrhu používateľského rozhrania.
5

Použite preklady v komponentoch

V ľubovoľnom komponente zavolajte useTranslation(), aby ste získali funkciu t(). Použite ju na jednoduché reťazce, interpolované premenné a preklady s vloženým JSX prostredníctvom komponentu 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" />
    }} />
  );
}
Dynamické kľúče, napríklad t(`error.$'{code}'`), fungujú počas behu aplikácie, ale nástroje ako i18next-scanner ich nedokážu staticky extrahovať. Ak používate nástroje na extrakciu, dynamické kľúče uveďte explicitne alebo použite pomocný komentár.
6

Spracujte množné čísla a premenné

i18next spracúva množné čísla podľa pravidiel CLDR — nie iba ako jednotné a množné číslo. Arabčina má 6 tvarov (nula, jeden, dva, málo, veľa, ostatné). Japončina má 1 tvar (ostatné). V prekladových súboroch definujte všetky požadované tvary a i18next automaticky vyberie správny.

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}}個のアイテム"
}
Pri určovaní jednotného čísla nikdy nepoužívajte napevno zadanú podmienku count === 1. Jazyky, ako je francúzština, považujú 0 za jednotné číslo. Ruština, arabčina a poľština majú tvary, ktoré angličtina nemá. Spracovanie pravidiel množného čísla prenechajte i18next.
7

Pridajte prepínanie a rozpoznávanie jazyka

Vytvorte výber jazyka, ktorý volá i18n.changeLanguage(). Skombinujte ho s rozpoznávaním jazyka prehliadača, aby sa pri prvej návšteve automaticky zistil preferovaný jazyk používateľa. Potom uložte jeho explicitný výber.

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>
  );
}
Ak používate SSR (Next.js, Remix), server môže rozpoznať iný jazyk než klient (server nemá prístup k nastaveniam prehliadača). To spôsobí nesúlad pri hydratácii. Riešenie: odovzdajte rozpoznané miestne nastavenie zo servera klientovi ako prop alebo súbor cookie, aby obe strany vykresľovali rovnaký jazyk.
8

Automatizujte preklady

Po dokončení nastavenia i18n preložte súbory miestnych nastavení pomocou AI. Vo svojom IDE požiadajte asistenta AI o preklad zdrojového súboru alebo použite nástroj príkazového riadka i18n Agent vo svojom procese 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
Prekladajte postupne — keď do zdrojového súboru pridáte nové kľúče, preložte iba rozdiel namiesto opätovného vygenerovania všetkých súborov. Zachováte tak všetky preklady skontrolované človekom.

Automatizujte kontrolu kvality prekladov

Pomocou i18n-validate odhaľte chýbajúce kľúče a poškodené zástupné symboly ešte pred vydaním. Kým budú k dispozícii skutočné preklady, otestujte používateľské rozhranie s falošnými prekladmi pomocou i18n-pseudo.

Bežné nástrahy

Namiesto prekladov sa zobrazujú nespracované kľúče

Príčiny: chýba I18nextProvider, konfigurácia i18n nie je importovaná v koreňovej časti aplikácie, menný priestor nie je načítaný alebo sa preklady ešte stále načítavajú asynchrónne. Vodidlá nájdete v konzole prehliadača po nastavení debug: true.

Chyba Suspense bez záložného obsahu

"A component suspended while responding to synchronous input" — pridajte okolo aplikácie hranicu '&lt;Suspense&gt;' alebo v inicializačnej konfigurácii i18next nastavte useSuspense: false.

Nesúlad pri hydratácii SSR

Server vykresľuje obsah v jednom miestnom nastavení, zatiaľ čo klient vykonáva hydratáciu v inom. Zaistite, aby obe strany používali rovnaký zdroj miestneho nastavenia — odovzdajte ho zo servera ako prop a nespoliehajte sa iba na rozpoznávanie v prehliadači.

Kľúče prekladov nemajú automatické dokončovanie

Rozšírte modul i18next o typ Vašich zdrojov: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Získate tak typovo bezpečné volania t() s automatickým dokončovaním.

Odporúčaná štruktúra súborov

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

Prekladajte aj:

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Často kladené otázky