Skip to main content

Ítarlegur leiðarvísir um alþjóðavæðingu React

Frá grunni að stuðningi við mörg tungumál: Settu upp i18n í React-forritinu þínu og gerðu síðan þýðingar sjálfvirkar með gervigreind.

1

Settu upp pakkana

Þú þarft þrjá pakka: react-i18next (React-tengingarnar), i18next (grunnsafnið) og valfrjálst i18next-browser-languagedetector til sjálfvirkrar greiningar á staðfærslu.

react-i18next útvegar React-krækjur og íhluti. i18next er grunnvélin sem sér um að hlaða þýðingum, skjóta inn gildum og mynda fleirtölu. Tungumálagreiningarviðbótin les sjálfkrafa tungumálaval vafrans.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Stilltu i18n-tilvikið

Búðu til i18n-stillingaskrá sem frumstillir i18next með sjálfgefnu tungumáli, þýðingartilföngum og viðbótaröð. Flytja verður þessa skrá inn á inngangsstað forritsins áður en nokkur íhlutur er myndgerður.

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" — þessi villa merkir að þú gleymdir að kalla á i18n.use(initReactI18next) á undan i18n.init(). Kallið á .use() verður að koma á undan .init().
3

Umlykktu forritið með I18nextProvider

Flyttu i18n-stillingaskrána inn við rót forritsins og umlykktu íhlutatréð með I18nextProvider. Án þess skilar useTranslation() óþýddum lyklum í stað þýdds texta.

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>
);
Ef óþýddir lyklar á borð við "welcome" birtast í stað "Welcome to our app" er algengasta orsökin sú að I18nextProvider vantar eða i18n-stillingaskráin hefur ekki verið flutt inn.
4

Búðu til þýðingarskrár

Búðu til eina JSON-skrá fyrir hvert tungumál. Notaðu falda lykla til að skipuleggja strengi eftir eiginleikum eða síðum. Hafðu frummálið (yfirleitt ensku) sem eina viðmiðið.

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"
  }
}
Nefndu lykla eftir því sem þeir lýsa, ekki eftir staðsetningu þeirra: "cart.itemCount" er betra en "homepageCartLabel". Lyklarnir ættu að haldast óbreyttir þótt notandaviðmótið sé endurhannað.
5

Notaðu þýðingar í íhlutum

Kallaðu á useTranslation() í hvaða íhlut sem er til að fá fallið t(). Notaðu það fyrir einfalda strengi, innskotnar breytur og þýðingar með innfelldu JSX með Trans-íhlutnum.

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" />
    }} />
  );
}
Kvikir lyklar á borð við t(`error.$'{code}'`) virka við keyrslu en verkfæri á borð við i18next-scanner geta ekki dregið þá út með stöðugreiningu. Ef þú notar útdráttarverkfæri skaltu tilgreina kvika lykla sérstaklega eða nota vísbendingu í athugasemd.
6

Meðhöndlaðu fleirtölumyndir og breytur

i18next meðhöndlar fleirtölumyndir samkvæmt CLDR-reglum — ekki aðeins eintölu og fleirtölu. Arabíska hefur 6 myndir (zero, one, two, few, many, other). Japanska hefur 1 (other). Skilgreindu allar nauðsynlegar myndir í þýðingarskránum og i18next velur sjálfkrafa þá réttu.

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}}個のアイテム"
}
Aldrei skal harðkóða count === 1 til að greina eintölu. Tungumál á borð við frönsku meðhöndla 0 sem eintölu. Rússneska, arabíska og pólska hafa myndir sem enska hefur ekki. Láttu i18next sjá um fleirtölureglurnar.
7

Bættu við tungumálaskiptum og tungumálagreiningu

Búðu til tungumálaval sem kallar á i18n.changeLanguage(). Tengdu það við tungumálagreiningu vafrans til að greina sjálfkrafa valið tungumál notandans við fyrstu heimsókn og varðveita síðan skýrt val hans.

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>
  );
}
Ef þú notar SSR (Next.js, Remix) kann þjónninn að greina annað tungumál en biðlarinn (þjónninn hefur engan aðgang að tungumálavali vafrans). Þetta veldur misræmi við vökvun. Lausn: Sendu greindu staðfærsluna frá þjóninum til biðlarans sem eigindi eða vafraköku svo báðir myndgeri sama tungumál.
8

Gerðu þýðingar sjálfvirkar

Þegar uppsetningu i18n er lokið skaltu þýða staðfærsluskrárnar með gervigreind. Biddu gervigreindaraðstoðina í þróunarumhverfinu að þýða frumskrána eða notaðu skipanalínuverkfæri i18n Agent í CI/CD-vinnslurásinni.

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
Þýddu í áföngum — þegar þú bætir nýjum lyklum við frumskrána skaltu aðeins þýða mismuninn í stað þess að endurgera allar skrár. Þannig varðveitast þýðingar sem manneskja hefur yfirfarið.

Gerðu gæðatryggingu þýðinga sjálfvirka

Finndu lykla sem vantar og skemmd frátök áður en breytingarnar eru gefnar út með i18n-validate. Prófaðu notandaviðmótið með sýndarþýðingum með i18n-pseudo áður en raunverulegar þýðingar berast.

Algengar gildrur

Óþýddir lyklar birtast í stað þýðinga

Orsakir: I18nextProvider vantar, i18n-stillingarnar hafa ekki verið fluttar inn við rót forritsins, nafnrýminu hefur ekki verið hlaðið eða þýðingar eru enn að hlaðast ósamstillt. Leitaðu vísbendinga í stjórnborði vafrans með debug: true.

Suspense-villa án varaframsetningar

"A component suspended while responding to synchronous input" — bættu '&lt;Suspense&gt;'-mörkum utan um forritið eða stilltu useSuspense: false í frumstillingum i18next.

Misræmi við SSR-vökvun

Þjónninn myndgerir eina staðfærslu en biðlarinn vökvar aðra. Tryggðu að báðir noti sömu uppsprettu staðfærslu — sendu hana sem eigindi frá þjóninum og treystu ekki eingöngu á greiningu vafrans.

Engin sjálfvirk útfylling fyrir þýðingarlykla

Útvíkkaðu i18next-eininguna með tilföngstegundinni þinni: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Þannig færðu tegundaörugg köll á t() með sjálfvirkri útfyllingu.

Ráðlagt skráaskipulag

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

Þýddu einnig:

Prófaðu i18n Agent núna

Slepptu þýðingarskránni þinni hér

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

eða smelltu til að fletta

Markmál

Engin skráning nauðsynlegKostnaðaráætlun samstundis

Algengar spurningar