React Intl

React Intl is the React binding for the FormatJS internationalization suite, the most widely used i18n library in the React ecosystem. It provides a component and hook API — <IntlProvider>, <FormattedMessage>, <FormattedDate>, <FormattedNumber>, <FormattedList>, <FormattedRelativeTime>, and the useIntl hook — that wraps the browser’s built-in Intl APIs so dates, numbers, lists, and pluralized messages render correctly for a user’s locale without hand-rolled formatting logic scattered across a codebase.

Beyond formatting, React Intl standardizes how translated strings are declared (defineMessages) and extracted from source via the companion @formatjs/cli and babel-plugin-formatjs tooling, so translation workflows stay mechanical rather than manual. It’s built on the same core (@formatjs/intl, intl-messageformat, @formatjs/icu-messageformat-parser) shared by FormatJS’s Vue, Svelte, and vanilla-JS bindings, giving teams a consistent ICU MessageFormat syntax across frameworks.

What You Get

• <IntlProvider> root component that scopes locale, messages, and format config to a component tree
• <FormattedMessage>, <FormattedDate>, <FormattedTime>, <FormattedNumber>, <FormattedList>, <FormattedRelativeTime>, <FormattedDisplayName>, and <FormattedDateTimeRange> components for declarative, locale-aware rendering
• useIntl hook exposing an imperative intl object (formatMessage, formatDate, formatNumber, etc.) for cases where a React element isn’t suitable, such as aria-label or title attributes
• defineMessages/defineMessage helpers plus @formatjs/cli and babel-plugin-formatjs for extracting translatable strings straight from source
• ICU MessageFormat syntax support for pluralization, gender/select formatting, and rich-text message interpolation
• First-class TypeScript types, including the ability to type message IDs and custom formats against your own message catalog

Common Use Cases

• Shipping a multi-locale React app where dates, currency, and numbers must render per the visitor’s region
• Pluralizing and gendering UI copy correctly across languages with very different plural rules
• Extracting and syncing translatable strings from source into a translation management pipeline
• Formatting relative timestamps (“2 days ago”) and locale-correct lists (“A, B, and C”) without a bespoke formatter
• Providing translated aria/title attribute strings where a React component can’t be used directly

Under The Hood

Architecture

React Intl’s architecture centers on a provider/context pattern: IntlProvider (components/provider.tsx) builds an IntlShape via createIntl.ts and exposes it through IntlContext to the tree, while every Formatted* component is produced by a shared factory (createFormattedComponent.tsx) that wraps an underlying formatter method (formatDate, formatNumber, etc.) instead of reimplementing formatting logic per component — keeping the component layer thin around one formatters core. Message resolution and ICU parsing live one layer down in the shared @formatjs/intl and @formatjs/icu-messageformat-parser packages in the same monorepo, so react-intl itself is essentially a React-specific adapter over framework-agnostic formatting/parsing engines that also back FormatJS’s Vue and Svelte bindings; a change to the core IntlShape contract would ripple through every Formatted* component and useIntl consumer, but adding a new formatted component is typically a thin new wrapper rather than new formatting logic.

Tech Stack

Written in TypeScript and distributed as an ESM-first package (type: module, an explicit exports map for . and ./server), it targets React as a peer dependency and depends on sibling workspace packages (@formatjs/icu-messageformat-parser, @formatjs/intl, intl-messageformat) inside a large pnpm/Bazel monorepo. Testing runs on Vitest, and releases are automated through release-please in CI, which versions and publishes each FormatJS package independently.

Code Quality

The package carries an extensive unit-test suite covering individual components and hooks, plus dedicated integration tests, and — notably — separate TypeScript type-checking test suites that verify the public type surface itself against multiple supported React versions, a level of type-safety testing uncommon even in well-tested libraries. Source is fully typed, uses explicit invariant-style assertions rather than silently swallowing misconfiguration (a missing IntlProvider throws a descriptive error rather than failing silently), and the monorepo enforces linting, formatting, and pre-commit hook checks across all packages in CI.

API Design The defining developer-experience choice is offering the same formatting logic through two parallel surfaces: declarative Formatted* components for typical rendering, and an imperative intl.formatX() call via useIntl for contexts where a React element isn’t usable, such as an aria-label or title attribute — avoiding the common need for a second library to cover that gap. Getting started requires little more than wrapping the app in a single <IntlProvider locale messages>, and TypeScript users can further opt into typed message IDs and custom format names for compile-time checking against their own message catalog.