Skip to main content

Täielik React'i internatsionaliseerimise juhend

Nullist mitmekeelseks: seadista React'i rakenduses i18n ja automatiseeri seejärel tõlked tehisintellektiga.

1

Paigalda paketid

Vajad kolme paketti: react-i18next (React'i sidumised), i18next (põhiteek) ja soovi korral i18next-browser-languagedetector lokaadi automaatseks tuvastamiseks.

react-i18next pakub React'i hook'e ja komponente. i18next on tõlgete laadimist, interpoleerimist ja mitmusevorme haldav põhimootor. Keeletuvastuse plugin loeb veebilehitseja keele-eelistuse automaatselt.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Seadista i18n-i eksemplar

Loo i18n-i seadistusfail, mis lähtestab i18next'i sinu vaikekeele, tõlkeressursside ja pluginate ahelaga. See fail tuleb importida rakenduse sisenemispunktis enne ühegi komponendi renderdamist.

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;
Tõrge "You will need to pass in an i18next instance by using initReactI18next" tähendab, et unustasid enne i18n.init() käivitamist kutsuda i18n.use(initReactI18next). .use()-kutse peab eelnema .init()-kutsele.
3

Ümbritse rakendus I18nextProvideriga

Impordi i18n-i seadistusfail rakenduse juurtasemel ja ümbritse komponendipuu I18nextProvideriga. Ilma selleta tagastab useTranslation() tõlgitud teksti asemel töötlemata võtmed.

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>
);
Kui tõlgete asemel kuvatakse "Welcome to our app" asemel töötlemata võtmeid, näiteks "welcome", on tavalisim põhjus puuduv I18nextProvider või importimata i18n-i seadistusfail.
4

Loo tõlkefailid

Loo iga keele jaoks üks JSON-fail. Korrasta stringid funktsiooni või lehe järgi pesastatud võtmetega. Hoia lähtekeel, tavaliselt inglise keel, ainsa tõeallikana.

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"
  }
}
Anna võtmetele nimi selle järgi, mida need kirjeldavad, mitte selle järgi, kus need asuvad: "cart.itemCount" on parem kui "homepageCartLabel". Võtmed peaksid kasutajaliidese ümberkujundamise üle elama.
5

Kasuta tõlkeid komponentides

Kutsu mis tahes komponendis useTranslation(), et saada funktsioon t(). Kasuta seda lihtsate stringide, interpoleeritud muutujate ja Trans-komponendiga JSX-i manustatud tõlgete jaoks.

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" />
    }} />
  );
}
Dünaamilised võtmed, näiteks t(`error.$'{code}'`), töötavad käitusajal, kuid sellised tööriistad nagu i18next-scanner ei saa neid staatiliselt eraldada. Kui kasutad eraldamistööriistu, loetle dünaamilised võtmed eraldi või kasuta kommentaarivihjet.
6

Töötle mitmusevorme ja muutujaid

i18next töötleb mitmusevorme CLDR-i reeglite järgi, mitte ainult ainsuse ja mitmusega. Araabia keeles on kuus vormi (zero, one, two, few, many, other), jaapani keeles üks (other). Määra tõlkefailides kõik vajalikud vormid ning i18next valib automaatselt õige.

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}}個のアイテム"
}
Ära kunagi kasuta ainsuse tuvastamiseks jäigalt tingimust count === 1. Sellised keeled nagu prantsuse keel käsitlevad arvu 0 ainsusena. Vene, araabia ja poola keeles on vorme, mida inglise keeles pole. Lase i18next'il mitmusereegleid hallata.
7

Lisa keele vahetamine ja tuvastamine

Loo keelevalija, mis kutsub funktsiooni i18n.changeLanguage(). Ühenda see veebilehitseja keeletuvastusega, et kasutaja eelistatud keel tuvastataks esimesel külastusel automaatselt ning tema selgesõnaline valik jääks hiljem meelde.

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>
  );
}
Kui kasutad SSR-i (Next.js, Remix), võib server tuvastada kliendist erineva keele, sest serveril puuduvad veebilehitseja eelistused. See põhjustab hüdratsiooni lahknevuse. Parandus: edasta tuvastatud lokaat serverist kliendile atribuudi või küpsisena, et mõlemad renderdaksid sama keelt.
8

Automatiseeri tõlked

Kui i18n-i seadistus on valmis, tõlgi lokaadifailid tehisintellektiga. Palu IDE-s oma tehisintellekti abilisel lähtefail tõlkida või kasuta CI/CD-konveieris i18n Agent'i CLI-d.

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
Tõlgi järk-järgult — kui lisad lähtefaili uusi võtmeid, tõlgi kõigi failide uuesti loomise asemel ainult erinevus. Nii säilivad inimeste ülevaadatud tõlked.

Automatiseeri tõlkekvaliteet

Leia i18n-validate'i abil puuduvad võtmed ja katkised kohatäitjad enne avaldamist. Testi kasutajaliidest i18n-pseudo abil näidistõlgetega enne päris tõlgete saabumist.

Levinud komistuskivid

Tõlgetes kuvatakse töötlemata võtmed

Põhjused: I18nextProvider puudub, i18n-i seadistust pole rakenduse juurtasemel imporditud, nimeruumi pole laaditud või tõlkeid laaditakse veel asünkroonselt. Otsi vihjeid veebilehitseja konsoolist valikuga debug: true.

Suspense'i tõrge ilma varusisuta

Tõrge "A component suspended while responding to synchronous input" — lisa rakenduse ümber '&lt;Suspense&gt;' piir või määra i18next'i lähtestusseadistuses useSuspense: false.

SSR-i hüdratsiooni lahknevus

Server renderdab ühes lokaadis, klient hüdreerib teises. Veendu, et mõlemad kasutaksid sama lokaadiallikat — edasta see serverist atribuudina, ära looda ainult veebilehitseja tuvastusele.

Tõlkevõtmetel puudub automaattäide

Laienda i18next'i moodulit oma ressursitüübiga: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Nii saad tüübikindlad t()-kutsed koos automaattäitega.

Soovituslik failistruktuur

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

Tõlgi ka:

Proovi i18n Agent'i kohe

Kukuta tõlkefail siia

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

või klõpsa faili valimiseks

Sihtkeeled

Registreerumine pole vajalikKohene hinnang

Korduma kippuvad küsimused