Skip to main content

Gabay sa react-intl: Setup ng Internationalization sa React

I-set up ang FormatJS react-intl sa inyong React app gamit ang IntlProvider, FormattedMessage, useIntl, ICU message format, at automated translations.

Gumagamit kayo ng react-i18next sa halip? Tingnan ang aming gabay sa react-i18next

1

I-install ang react-intl

Bahagi ng FormatJS project ang react-intl. Nagbibigay ito ng mga React component at hook para mag-format ng mga string, number, date, at plural gamit ang pamantayang ICU MessageFormat.

Walang runtime dependencies ang react-intl bukod sa React. Ginagamit nito ang built-in na Intl API ng browser para sa number at date formatting, at kasama ang sarili nitong ICU MessageFormat parser para sa plurals, select, at rich text.
Terminal
npm install react-intl
2

I-configure ang IntlProvider

I-wrap ang inyong app sa IntlProvider sa root. Ipasa ang aktibong locale at isang flat messages object. Pagkatapos, maa-access ng bawat component sa ibaba ang mga pagsasalin sa pamamagitan ng FormattedMessage o useIntl.

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { IntlProvider } from 'react-intl';
import App from './App';
import enMessages from './messages/en.json';
import deMessages from './messages/de.json';

const messages: Record<string, Record<string, string>> = {
  en: enMessages,
  de: deMessages,
};

// Detect locale from browser or your routing layer
const locale = navigator.language.split('-')[0] || 'en';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <IntlProvider locale={locale} messages={messages[locale] || messages.en}>
      <App />
    </IntlProvider>
  </React.StrictMode>
);
Nangangailangan ang IntlProvider ng flat key-value messages object (hal., { "app.greeting": "Hello" }). Kailangang i-flatten ang nested JSON bago ipasa sa IntlProvider, o gumamit ng utility tulad ng flat para i-convert ang mga nested structure.

Mga Message File

Gumawa ng tig-isang JSON file para sa bawat locale. Native na gumagamit ang react-intl ng ICU MessageFormat syntax—ang plurals, select, at variables ay lahat ipinapahayag inline sa mga string ng message.

messages/en.json & messages/de.json
// messages/en.json
{
  "app.greeting": "Hello, {name}!",
  "nav.home": "Home",
  "nav.about": "About",
  "nav.settings": "Settings",
  "cart.itemCount": "{count, plural, one {# item} other {# items}} in your cart"
}

// messages/de.json
{
  "app.greeting": "Hallo, {name}!",
  "nav.home": "Startseite",
  "nav.about": "Über uns",
  "nav.settings": "Einstellungen",
  "cart.itemCount": "{count, plural, one {# Artikel} other {# Artikel}} in Ihrem Warenkorb"
}
Gumamit ng mga dot-separated ID tulad ng "nav.home" para sa organisasyon. Hindi tulad ng react-i18next, inaasahan ng react-intl ang isang flat messages object—kayo ang nagfa-flatten ng mga key, hindi ang structure.
3

Gamitin ang Mga Pagsasalin sa Mga Component

Nagbibigay ang react-intl ng dalawang pangunahing API: ang FormattedMessage component para mag-render ng isinaling JSX, at ang useIntl hook para sa imperative access (placeholder, aria label, programmatic formatting).

Component na FormattedMessage

Gamitin ang FormattedMessage para sa declarative translations sa JSX. Ipasa ang message ID at anumang interpolation value. Ire-render nito nang direkta ang isinaling string.

Greeting.tsx
import { FormattedMessage } from 'react-intl';

function Greeting({ userName }: { userName: string }) {
  return (
    <div>
      <h1>
        <FormattedMessage
          id="app.greeting"
          values={{ name: userName }}
        />
      </h1>
      <nav>
        <a href="/"><FormattedMessage id="nav.home" /></a>
        <a href="/about"><FormattedMessage id="nav.about" /></a>
      </nav>
    </div>
  );
}

Hook na useIntl

Gamitin ang useIntl() kapag kailangan ninyo ang isinaling string bilang plain value—para sa input placeholder, aria-label, document.title, o kapag nagpapasa ng mga string sa mga non-React API. Nagbibigay din ito ng formatNumber, formatDate, at formatRelativeTime.

SearchBar.tsx
import { useIntl } from 'react-intl';

function SearchBar() {
  const intl = useIntl();

  return (
    <input
      type="search"
      placeholder={intl.formatMessage({ id: 'search.placeholder' })}
      aria-label={intl.formatMessage({ id: 'search.ariaLabel' })}
    />
  );
}

// useIntl also gives you formatNumber, formatDate, formatRelativeTime:
function PriceTag({ amount, currency }: { amount: number; currency: string }) {
  const intl = useIntl();
  return (
    <span>{intl.formatNumber(amount, { style: 'currency', currency })}</span>
  );
}

Rich Text (HTML sa Mga Pagsasalin)

Mag-embed ng JSX sa loob ng mga pagsasalin gamit ang XML-like tag sa inyong mga string ng message. Ipasa ang mga tag handler sa pamamagitan ng values prop para mag-render ng link, bold na teksto, o anumang React component sa loob ng isang isinaling message.

SignUp.tsx
import { FormattedMessage } from 'react-intl';

// Message: "By signing up, you agree to our <link>Terms</link>."
// Key: "signup.terms"
// Value: "By signing up, you agree to our <link>Terms</link>."

function SignUp() {
  return (
    <FormattedMessage
      id="signup.terms"
      values={{
        link: (chunks) => <a href="/terms" className="underline">{chunks}</a>,
      }}
    />
  );
}
Nagre-render ang FormattedMessage ng React Fragment bilang default. Kung kailangan ninyo ng partikular na wrapper element, ipasa ang textComponent prop sa IntlProvider o i-wrap ang FormattedMessage sa sarili ninyong element.

Message Extraction gamit ang @formatjs/cli

Nagbibigay ang FormatJS ng CLI para awtomatikong i-extract ang mga message ID mula sa inyong source code papunta sa isang JSON file. Tinitiyak nito na nananatiling naka-sync ang inyong messages file sa mga component nang walang mano-manong bookkeeping.

Terminal
# Install the CLI
npm install -g @formatjs/cli

# Extract messages from source code into a JSON file
formatjs extract 'src/**/*.tsx' --out-file messages/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'

# Or use explicit IDs (recommended):
formatjs extract 'src/**/*.tsx' --out-file messages/en.json

# Compile messages for production (optional, improves perf)
formatjs compile messages/en.json --out-file compiled/en.json
formatjs compile messages/de.json --out-file compiled/de.json
4

Plurals at ICU Select

Native na gumagamit ang react-intl ng ICU MessageFormat. Ang plurals, gender-based select, at nested formatting ay lahat ipinapahayag nang direkta sa mga string ng message—walang kailangang suffix convention o hiwalay na key.

ICU plural syntax by language
// ICU MessageFormat syntax — react-intl uses this natively
// English
{
  "cart.itemCount": "{count, plural, one {# item} other {# items}} in your cart",
  "inbox.unread": "You have {count, plural, =0 {no unread messages} one {# unread message} other {# unread messages}}"
}

// Arabic — 6 plural forms
{
  "cart.itemCount": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصرًا} other {# عنصر}} في سلتك"
}

// Japanese — 1 form (other)
{
  "cart.itemCount": "カートに{count}個の商品があります"
}
Huwag kailanman mag-hardcode ng plural logic sa JavaScript. May 6 na plural form ang Arabic, itinuturing ng French na singular ang 0, at walang plural distinction ang Japanese. Hayaan ninyong ICU MessageFormat ang humawak sa mga rule—ipasa lamang ang count value.

ICU Select para sa Gender at Mga Role

Gamitin ang ICU select syntax para sa mga pagsasaling nakadepende sa context tulad ng gender, mga role ng user, o mga value ng status. Pinipili ng select expression ang tamang variant batay sa ibinigay na value.

ICU select syntax
// Gender-dependent messages using ICU select
{
  "user.greeting": "{gender, select, male {He} female {She} other {They}} liked your post.",
  "user.invitation": "{role, select, admin {You can manage all settings.} editor {You can edit content.} other {You can view content.}}"
}

// Usage:
<FormattedMessage
  id="user.greeting"
  values={{ gender: user.gender }}
/>

I-automate ang Kalidad ng Pagsasalin

Matukoy ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. Subukan ang inyong UI gamit ang pseudo-translations sa pamamagitan ng i18n-pseudo bago dumating ang mga tunay na pagsasalin.

Mga Karaniwang Pitfall

Sobrang Pag-asa sa defaultMessage

Development fallback ang defaultMessage, hindi ito estratehiya sa pagsasalin. Kung gagamitin ninyo ang defaultMessage para sa lahat ng string, maglalaman ang output ng message extraction ng English text ngunit maaaring hindi mapansin ng mga tagasalin ang mga bagong key. Laging i-extract at panatilihin ang kumpletong source locale file.

Mga Nested Object sa Halip na Flat Key

Inaasahan ng IntlProvider ang isang flat Record&lt;string, string&gt; para sa messages. Kung magpapasa kayo ng nested JSON tulad ng { nav: { home: "Home" } }, hindi mahahanap ng react-intl ang key na "nav.home". I-flatten ang inyong mga message bago ipasa, o gumamit ng library tulad ng flat.

Nagiging Sanhi ang IntlProvider ng Re-render

Kung gagawa kayo ng messages object inline sa loob ng render function, makakatanggap ang IntlProvider ng bagong object reference sa bawat render, na nagdudulot na mag-re-render ang lahat ng consumer. I-memoize ang messages gamit ang useMemo o ideklara ang mga ito sa labas ng component.

Walang IntlProvider sa Mga Test

Magti-throw ang mga component na gumagamit ng FormattedMessage o useIntl kapag ni-render nang walang IntlProvider ancestor. Sa mga test, i-wrap ang inyong component sa IntlProvider na may locale="en" at isang empty o minimal na messages object.

Inirerekomendang File Structure

Project Structure
my-react-app/
├── messages/
│   ├── en.json              # Source of truth (English)
│   ├── de.json              # German
│   ├── ja.json              # Japanese
│   └── es.json              # Spanish
├── compiled/                # Optional: compiled messages for prod
│   ├── en.json
│   └── ...
├── src/
│   ├── main.tsx             # App entry with IntlProvider
│   ├── App.tsx
│   └── components/
│       ├── Greeting.tsx      # Uses FormattedMessage
│       └── SearchBar.tsx     # Uses useIntl
└── package.json

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

Locale Fallback gamit ang react-intl-locale-chain

Kapag nawawala ang translation key sa isang regional locale tulad ng pt-BR, diretso ang react-intl sa default locale sa halip na suriin muna ang parent locale na pt.

Terminal
npm install react-intl-locale-chain
Configuration
<LocaleChainProvider
  fallbacks={{
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  }}
  defaultLocale="en"
>
  <App />
</LocaleChainProvider>

Tingnan ang aming Locale Fallback Guide para sa kumpletong listahan ng mga sinusuportahang framework at 75 built-in chain. Learn more →

Mga Madalas Itanong