Skip to main content

Ang Kumpletong Gabay sa React Internationalization

Mula zero hanggang multilingual: i-set up ang i18n sa inyong React app, saka i-automate ang pagsasalin gamit ang AI.

1

I-install ang Mga Package

Kailangan ninyo ng tatlong package: react-i18next (ang React bindings), i18next (ang core library), at opsyonal na i18next-browser-languagedetector para sa awtomatikong pag-detect ng locale.

Nagbibigay ang react-i18next ng mga React hook at component. Ang i18next ang core engine na humahawak sa paglo-load ng translation, interpolation, at pluralization. Awtomatikong binabasa ng language detector plugin ang language preference ng browser.
Terminal
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
2

I-configure ang i18n Instance

Gumawa ng i18n configuration file na nag-i-initialize ng i18next gamit ang default language ninyo, translation resources, at plugin chain. Dapat i-import ang file na ito sa entry point ng app ninyo bago mag-render ang anumang component.

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" — nangangahulugan ang error na ito na nakalimutan ninyong tawagin ang i18n.use(initReactI18next) bago i-call ang i18n.init(). Dapat mauna ang .use() bago ang .init().
3

I-wrap ang Inyong App gamit ang I18nextProvider

I-import ang i18n config file ninyo sa app root at i-wrap ang component tree ninyo gamit ang I18nextProvider. Kung wala ito, magre-return ang useTranslation() ng raw key sa halip na naisaling text.

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>
);
Kung raw key tulad ng "welcome" ang lumalabas sa halip na "Welcome to our app", ang pinakakaraniwang sanhi ay nawawala ang I18nextProvider o hindi nai-import ang i18n config file.
4

Gumawa ng Mga Translation File

Gumawa ng tig-isang JSON file kada wika. Gumamit ng nested key para ayusin ang mga string ayon sa feature o pahina. Panatilihin ang source language (karaniwang English) bilang iisang source of truth.

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"
  }
}
Pangalanan ang mga key ayon sa inilalarawan ng mga ito, hindi kung saan lumalabas: mas mabuti ang "cart.itemCount" kaysa "homepageCartLabel". Dapat manatili ang mga key kahit mag-redesign ang UI.
5

Gamitin ang Mga Pagsasalin sa Mga Component

Tawagin ang useTranslation() sa anumang component para makuha ang t() function. Gamitin ito para sa mga simpleng string, interpolated na variable, at mga pagsasaling naka-embed sa JSX gamit ang Trans component.

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" />
    }} />
  );
}
Gumagana sa runtime ang mga dynamic key gaya ng t(`error.$'{code}'`), ngunit hindi ito kayang i-extract nang static ng mga tool gaya ng i18next-scanner. Kung gumagamit kayo ng extraction tools, ilista nang tahasan ang mga dynamic key o gumamit ng comment hint.
6

Pangasiwaan ang mga Plural at Variable

Pinangangasiwaan ng i18next ang mga plural gamit ang mga panuntunang CLDR — hindi lang singular/plural. May 6 na anyo ang Arabic (zero, one, two, few, many, other). May 1 lang ang Japanese (other). I-define ang lahat ng kinakailangang anyo sa inyong mga translation file at awtomatikong pipiliin ng i18next ang tama.

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}}個のアイテム"
}
Huwag kailanman i-hardcode ang count === 1 para sa pag-detect ng singular. Tinuturing ng mga wikang gaya ng French na singular ang 0. May mga anyo ang Russian, Arabic, at Polish na wala sa English. Hayaan ang i18next na humawak ng mga panuntunan sa plural.
7

Magdagdag ng Language Switching at Detection

Bumuo ng language selector na tumatawag sa i18n.changeLanguage(). Pagsamahin ito sa browser language detector para awtomatikong ma-detect ang preferred language ng user sa unang pagbisita, pagkatapos ay i-persist ang kanilang tahasang pinili.

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>
  );
}
Kung gumagamit kayo ng SSR (Next.js, Remix), maaaring ma-detect ng server ang ibang wika kaysa sa client (walang browser preferences ang server). Nagdudulot ito ng hydration mismatch. Ayusin: ipasa ang na-detect na locale mula sa server papunta sa client bilang prop o cookie, para pareho ang i-render nilang wika.
8

I-automate ang mga Pagsasalin

Kapag kumpleto na ang inyong i18n setup, isalin ang inyong mga locale file gamit ang AI. Sa inyong IDE, hilingin sa AI assistant na isalin ang source file, o gamitin ang i18n Agent CLI sa inyong 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
Magsalin nang paunti-unti — kapag nagdagdag kayo ng mga bagong key sa source file, isalin lang ang diff sa halip na i-regenerate ang lahat ng file. Pinapanatili nito ang anumang human-reviewed na pagsasalin.

I-automate ang Kalidad ng Pagsasalin

Matukoy ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. I-test ang inyong UI gamit ang mga pseudo-translation sa pamamagitan ng i18n-pseudo bago dumating ang mga totoong pagsasalin.

Mga Karaniwang Pitfall

Nagpapakita ang Mga Pagsasalin ng Mga Raw Key

Mga sanhi: nawawala ang I18nextProvider, hindi na-import ang i18n config sa app root, hindi na-load ang namespace, o naglo-load pa nang asynchronous ang mga pagsasalin. Suriin ang browser console na may debug: true para sa mga palatandaan.

Suspense Error Nang Walang Fallback

"A component suspended while responding to synchronous input" — magdagdag ng '&lt;Suspense&gt;' boundary sa paligid ng inyong app, o i-set ang useSuspense: false sa i18next init config.

Hindi Tugmang SSR Hydration

Nagre-render ang server sa isang locale, ngunit nagha-hydrate ang client sa iba. Tiyaking pareho ang pinagmumulan ng locale na ginagamit ng dalawa — ipasa ito bilang prop mula sa server; huwag umasa sa browser detection lang.

Walang Autocomplete para sa Mga Translation Key

I-augment ang i18next module gamit ang inyong resource type: declare module 'i18next' '{ interface CustomTypeOptions { resources: typeof resources } }'. Nagbibigay ito ng type-safe na t() call na may autocomplete.

Inirerekomendang File Structure

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

Magsalin din ng:

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

Mga Madalas Itanong