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 - IntlProvider setup, FormattedMessage, useIntl, defineMessages, TypeScript integration, lazy loading
• examples/formatting.md - Date, time, number, currency, relative time, and list formatting
• examples/pluralization.md - Plural, ordinal, select, nested ICU patterns
• reference.md - Decision frameworks, ICU syntax quick reference, API tables, anti-patterns

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

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 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, conditional logic based on formatted values.

Pattern 4: defineMessages for Static Extraction

Group related messages with defineMessages for CLI extraction and IDE autocomplete.

export const productMessages = defineMessages({
  title: {
    id: "product.title",
    defaultMessage: "Product Details",
    description: "Page title for product detail page",
  },
  reviewCount: {
    id: "product.reviewCount",
    defaultMessage:
      "{count, plural, =0 {No reviews} one {# review} other {# reviews}}",
    description: "Number of product reviews with pluralization",
  },
});

Why good: centralizes related messages, descriptions provide translator context, CLI extracts these automatically, IDE autocomplete for references

See examples/core.md for usage patterns with FormattedMessage and useIntl.

Pattern 5: Rich Text Formatting

Use XML-like tags in messages for embedded markup. Translators can reorder tags per language grammar while the complete sentence stays in one translation unit.

<FormattedMessage
  id="terms.notice"
  defaultMessage="By signing up, you agree to our <terms>Terms</terms> and <privacy>Privacy Policy</privacy>."
  values={{
    terms: (chunks) => <a href="/terms">{chunks}</a>,
    privacy: (chunks) => <a href="/privacy">{chunks}</a>,
  }}
/>

Configure global tag handlers via defaultRichTextElements on IntlProvider for <b>, <i>, <br> tags.

Pattern 6: Formatting Components

Locale-aware formatting for dates, numbers, currency, relative time, and lists.

<FormattedDate value={date} year="numeric" month="long" day="numeric" />
// en-US: "January 15, 2024" | de-DE: "15. Januar 2024"

<FormattedNumber value={amount} style="currency" currency={currency} />
// en-US: "$1,234.56" | de-DE: "1.234,56 EUR"

<FormattedList type="conjunction" value={names} />
// en: "Alice, Bob, and Charlie" | es: "Alice, Bob y Charlie"

Use imperative equivalents (intl.formatDate(), intl.formatNumber()) when you need strings for attributes or programmat