Skip to main content

Потпун водич за React интернационализацију

Од почетка до више језика: подесите i18n у React апликацији, а затим аутоматизујте преводе помоћу AI.

1

Инсталирајте пакете

Потребна су Вам три пакета: react-i18next (React повезивања), i18next (основна библиотека) и, по жељи, i18next-browser-languagedetector за аутоматско откривање локала.

react-i18next пружа React hook функције и компоненте. i18next је основни механизам који обрађује учитавање превода, интерполацију и множину. Додатак за откривање језика аутоматски чита жељени језик прегледача.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

Конфигуришите i18n инстанцу

Направите i18n конфигурациону датотеку која покреће i18next са подразумеваним језиком, ресурсима превода и ланцем додатака. Ова датотека мора да се увезе на улазној тачки апликације пре приказивања било које компоненте.

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" — ова грешка значи да сте заборавили да позовете i18n.use(initReactI18next) пре i18n.init(). Позив .use() мора да буде пре .init().
3

Обавијте апликацију компонентом I18nextProvider

Увезите i18n конфигурациону датотеку у корену апликације и обавијте стабло компоненти компонентом I18nextProvider. Без тога useTranslation() враћа необрађене кључеве уместо преведеног текста.

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>
);
Ако преводи приказују необрађене кључеве као што је „welcome" уместо „Welcome to our app", најчешћи узрок је недостатак компоненте I18nextProvider или неувезена i18n конфигурациона датотека.
4

Направите датотеке превода

Направите по једну JSON датотеку за сваки језик. Користите угнежђене кључеве да организујете текстове по функцији или страници. Задржите изворни језик (обично енглески) као једини извор истине.

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"
  }
}
Кључеве именујте према ономе што описују, а не месту на ком се појављују: „cart.itemCount" је боље од „homepageCartLabel". Кључеви треба да преживе редизајн UI окружења.
5

Користите преводе у компонентама

Позовите useTranslation() у било којој компоненти да добијете функцију t(). Користите је за једноставне текстове, интерполиране променљиве и преводе са уграђеним JSX садржајем преко компоненте 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" />
    }} />
  );
}
Динамички кључеви као што је t(`error.$'{code}'`) раде при извршавању, али алати као што је i18next-scanner не могу статички да их издвоје. Ако користите алате за издвајање, изричито наведите динамичке кључеве или употребите савет у коментару.
6

Обрадите множину и променљиве

i18next обрађује множину према CLDR правилима, а не само као једнину и множину. Арапски има шест облика (zero, one, two, few, many, other), а јапански један (other). Дефинишите све потребне облике у датотекама превода и i18next ће аутоматски изабрати исправан.

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}}個のアイテム"
}
Никада немојте у коду да користите count === 1 за откривање једнине. Језици као што је француски третирају 0 као једнину. Руски, арапски и пољски имају облике које енглески нема. Препустите i18next систему правила множине.
7

Додајте промену и откривање језика

Направите избор језика који позива i18n.changeLanguage(). Повежите га са алатом за откривање језика прегледача како бисте при првој посети аутоматски открили жељени језик корисника, а затим сачували његов изричити избор.

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 (Next.js, Remix), сервер може да открије други језик од клијента јер нема подешавања прегледача. То изазива неусклађеност хидратације. Решење: проследите откривени локал са сервера клијенту као prop вредност или колачић, како би оба приказала исти језик.
8

Аутоматизујте преводе

Када завршите i18n подешавање, преведите датотеке локала помоћу AI. У IDE окружењу затражите од AI помоћника да преведе изворну датотеку или користите i18n Agent CLI у CI/CD pipeline процесу.

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
Преводите постепено — када додате нове кључеве у изворну датотеку, преведите само разлику уместо да поново генеришете све датотеке. Тако се чувају преводи које су људи прегледали.

Аутоматизујте квалитет превода

Откријте недостајуће кључеве и неисправна места за променљиве помоћу i18n-validate пре објављивања. Тестирајте UI лажним преводима помоћу i18n-pseudo пре него што стигну прави преводи.

Уобичајене замке

Преводи приказују необрађене кључеве

Узроци: недостаје I18nextProvider, i18n конфигурација није увезена у корену апликације, именски простор није учитан или се преводи још учитавају асинхроно. Потражите савете у конзоли прегледача уз debug: true.

Suspense грешка без резервног приказа

„A component suspended while responding to synchronous input" — додајте границу '&lt;Suspense&gt;' око апликације или поставите useSuspense: false у i18next init конфигурацији.

Неусклађеност SSR хидратације

Сервер приказује један локал, а клијент хидрира други. Обезбедите да оба користе исти извор локала — проследите га са сервера као prop вредност и не ослањајте се само на откривање прегледача.

Без аутоматског довршавања кључева превода

Проширите i18next модул типом ресурса: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Тако t() позиви постају типски безбедни и добијају аутоматско довршавање.

Препоручена структура датотека

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

Преведите и:

Испробајте i18n Agent сада

Пустите датотеку за превођење овде

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

или кликните за избор

Циљни језици

Регистрација није потребнаТренутна процена

Честа питања