/web-i18n-react-intl

name: web-i18n-react-intl
description: ICU message format internationalization

React-Intl (FormatJS) Internationalization Patterns

> **Quick Guide:** Use react-intl for internationalization with ICU Message Format. `FormattedMessage` for JSX content, `useIntl` for string attributes and programmatic use, `defineMessages` for extractable message descriptors. Wrap app with `IntlProvider` and configure `onError` for missing translations. Always include the `other` category in plurals and selects. > > **Version Note:** react-intl v7.x supports React 16.6+/17/18/19. v8+ requires React 19 only (React 18 support dropped). Current latest: v10.x.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST wrap the application root with `IntlProvider` and configure locale, messages, and defaultLocale)**

**(You MUST include the `other` category in ALL plural and select ICU messages - omission causes runtime errors)**

**(You MUST use named constants for locale codes - NO inline locale strings)**

**(You MUST verify React version compatibility: v7.x supports React 16.6-19, v8+ requires React 19 only)**

</critical_requirements>

---

**Auto-detection:** react-intl, FormatJS, FormattedMessage, useIntl, IntlProvider, defineMessages, ICU message format, formatMessage, FormattedDate, FormattedNumber, FormattedRelativeTime

**When to use:**

• Implementing internationalization in React applications
• Rendering localized messages with ICU syntax (interpolation, pluralization, select)
• Formatting dates, numbers, currency, and relative time per locale
• Extracting and compiling translation messages for TMS workflows
• Building type-safe i18n with TypeScript augmentation

**Key patterns covered:**

• IntlProvider setup with error handling and default rich text elements
• FormattedMessage vs useIntl: declarative JSX vs imperative strings
• defineMessages for static message extraction
• ICU Message Format syntax (plurals, select, ordinals, rich text)
• Date, time, number, currency, relative time, and list formatting
• TypeScript integration for type-safe message IDs
• Lazy loading locale data with dynamic imports

**When NOT to use:**

• SSR frameworks with built-in i18n (use the framework's i18n solution for better SSR integration)
• Simple single-locale applications (skip i18n complexity)
• Server-side rendering without React context (use `createIntl` from `@formatjs/intl`)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - IntlProvider setup, FormattedMessage, useIntl, defineMessages, TypeScript integration, lazy loading
• [examples/formatting.md](examples/formatting.md) - Date, time, number, currency, relative time, and list formatting
• [examples/pluralization.md](examples/pluralization.md) - Plural, ordinal, select, nested ICU patterns
• [reference.md](reference.md) - Decision frameworks, ICU syntax quick reference, API tables, anti-patterns

---

<philosophy>

Philosophy

React-intl follows the principle of **ICU Message Format standardization** with both declarative and imperative APIs. Translations use industry-standard ICU syntax enabling compatibility with professional translation management systems. The library is built on browser-native `Intl` APIs for optimal performance and accurate locale-aware formatting.

**Core principles:**

1. **ICU Standard**: Use industry-standard ICU Message Format for professional translation workflows 2. **Dual API**: FormattedMessage for JSX content, useIntl for string contexts (attributes, programmatic use) 3. **Native Intl**: Built on browser Intl APIs for accurate locale-specific formatting 4. **Extractable**: defineMessages enables CLI extraction for translation management

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: IntlProvider Setup

Wrap your application root with `IntlProvider`. Configure `onError` to distinguish missing translations from actual errors, set `defaultLocale` for fallback, and define `defaultRichTextElements` for consistent markup.

export function AppIntlProvider({ children, locale, messages }: Props) {
  return (
    <IntlProvider
      locale={locale}
      defaultLocale={DEFAULT_LOCALE}
      messages={messages}
      defaultRichTextElements={DEFAULT_RICH_TEXT_ELEMENTS}
      onError={(err) => {
        if (err.code === "MISSING_TRANSLATION") {
          console.warn(`Missing translation: ${err.message}`);
          return;
        }
        throw err;
      }}
    >
      {children}
    </IntlProvider>
  );
}

**Why good:** custom onError distinguishes missing translations from actual errors, defaultLocale provides fallback, defaultRichTextElements ensure consistent markup

See [examples/core.md](examples/core.md) for full setup with locale config, lazy loading, and app integration.

---

Pattern 2: FormattedMessage (Declarative JSX)

Use `FormattedMessage` for rendering translated text directly in JSX elements. Supports ICU syntax for interpolation, pluralization, and rich text.

<FormattedMessage
  id="greeting.unread"
  defaultMessage="{count, plural, =0 {No messages} one {# message} other {# messages}}"
  values={{ count: unreadCount }}
/>

**When to use:** Text content rendered directly in JSX, rich text with embedded formatting.

**When not to use:** String attributes like placeholder, aria-label, title (use useIntl instead).

---

Pattern 3: useIntl Hook (Imperative Strings)

Use `useIntl` when you need formatted strings for attributes, props, or programmatic use.

const intl = useIntl();
const placeholder = intl.formatMessage({
  id: "search.placeholder",
  defaultMessage: "Search products...",
});

<input placeholder={placeholder} aria-label={ariaLabel} />

**When to use:** Input placeholders, ARIA labels, document titles, third-party component props, conditiona