agents-inc/web-i18n-react-intl

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>

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 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 programmatic use.

See examples/formatting.md for comprehensive date/time, number, currency, relative time, and list examples.

---

Pattern 7: TypeScript Integration

Enable type-safe message IDs with TypeScript module augmentation.

// src/types/intl.d.ts
import type messages from "../lang/en.json";

type MessageIds = keyof typeof messages;

declare global {
  namespace FormatjsIntl {
    interface Message {
      ids: MessageIds;
    }
  }
}

Typos in message IDs become compile-time errors. Add "esnext.intl" to compilerOptions.lib in tsconfig.json.

---

Pattern 8: Message Extraction Workflow

Use FormatJS CLI for extracting and compiling messages.

1. Extract messages from source code: formatjs extract 'src/**/*.{ts,tsx}' --out-file lang/en.json
2. Send to translation management system (TMS)
3. Compile translations to AST format: formatjs compile lang/en.json --out-file compiled/en.json --ast

Why compile to AST: 30-50% faster initial render for large message catalogs - skips runtime parsing.

---

Pattern 9: ICU Pluralization

ICU plural syntax handles language-specific rules. Always include other as fallback.

{count, plural, =0 {No items} one {# item} other {# items}}
{position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
{gender, select, male {He} female {She} other {They}} liked your post.

Different languages have different plural categories (English: one/other, Russian: one/few/many/other, Arabic: zero/one/two/few/many/other).

See examples/pluralization.md for nested patterns, ordinals, select, and language-specific examples.

</patterns>

---

<performance>

Performance

Message Compilation (AST Pre-parsing)

Compile messages to AST at build time to skip runtime parsing. Impact: 30-50% faster initial render for large catalogs.

Lazy Loading Locale Data

Use dynamic imports to load only the current locale's messages. Cache loaded messages to prevent duplicate fetches. See examples/core.md for implementation.

RawIntlProvider with createIntl

Use createIntl + createIntlCache + RawIntlProvider for manual control over intl object creation. Useful when you want to memoize the intl instance explicitly.

Avoid Inline Message Objects

Define messages outside components with defineMessages rather than passing inline objects to FormattedMessage. Inline objects create new references each render, preventing memoization optimizations.

</performance>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Missing IntlProvider wrapper - All useIntl and FormattedMessage calls fail without context
• Missing other category in plural/select - Runtime error: "other" is REQUIRED in ICU syntax
• Hardcoded locale strings - Use named constants from config for type safety
• Using FormattedMessage for attributes - Returns ReactNode, not string; breaks placeholder, aria-label, title

Medium Priority Issues:

• Missing defaultLocale on IntlProvider - No fallback for missing translations
• No onError handler - Console noise for every missing translation
• Missing description in defineMessages - Translators lack context for accurate translation

Common Mistakes:

• Concatenating translated strings instead of single message with placeholders (word order varies by language)
• Applying English grammar rules programmatically (possessives, plurals) instead of using ICU syntax
• Using {count} instead of {count, plural, ...} for countable items
• Missing # in plural branches (shows nothing instead of the count value)

Gotchas & Edge Cases:

• FormattedMessage returns ReactNode, not string - cannot use for HTML attributes
• formatMessage returns string for plain values, but string | ReactNode[] when rich text tag functions are in values
• Rich text tag functions receive chunks array, not single element
• formatNumber with style: "percent" expects decimal (0.25 for 25%), not percentage
• formatRelativeTime value is relative to NOW - negative for past, positive for future
• ICU escaping: single quote ' escapes special characters, double single quote '' produces literal apostrophe
• Browser Intl support varies - consider polyfills for older browsers
• injectIntl HOC was removed in v10 - use useIntl hook instead
• Use onWarn prop on IntlProvider to suppress or handle defaultRichTextElements warnings when messages are not pre-compiled

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(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)

Failure to follow these rules will cause runtime errors and broken internationalization.

</critical_reminders>