React Intl

Common errors

• Error: [React Intl] IntlProvider was not found in the React context.

  cause Attempting to use `FormattedMessage`, `useIntl`, or other `react-intl` components/hooks outside of an `IntlProvider`'s context.
  fix Ensure that your entire application or the relevant component tree is wrapped within an `IntlProvider` component, providing the `locale` and `messages` props.

• TypeError: (0 , react_intl__WEBPACK_IMPORTED_MODULE_2__.useIntl) is not a function

  cause This typically occurs in older React environments (pre-16.8) where hooks are not supported, or if there's a module resolution issue where an older `react-intl` version without hooks is being loaded, or incorrect Babel/Webpack configuration.
  fix Verify that your `react` dependency is at least `16.8.0`. Check your module bundler configuration to ensure `react-intl` is correctly resolved and that you're using a compatible version. Update `react-intl` to a version that supports hooks.

• Invariant Violation: [React Intl] The 'locale' prop must be a string.

  cause The `locale` prop passed to `IntlProvider` is not a string, or is `undefined` (e.g., due to a variable not being correctly initialized).
  fix Ensure the `locale` prop passed to `IntlProvider` is always a valid BCP 47 language tag string, such as 'en-US' or 'fr-FR'. Consider a fallback mechanism for determining the user's locale.

• ReferenceError: Intl is not defined

  cause The JavaScript runtime environment (e.g., older browsers, specific Node.js builds, or React Native environments without `Intl` support) lacks the native `Intl` object or required `Intl` APIs.
  fix Include polyfills for the `Intl` object and specific `Intl` APIs (`Intl.PluralRules`, `Intl.RelativeTimeFormat`, etc.) as needed for your target environments. For Node.js, ensure version 16+ is used.

• Warning: Missing locale data for locale: "undefined". Using default locale: "en" as fallback.

  cause This warning indicates that `react-intl` cannot find the necessary locale data for the requested locale, often because the data hasn't been imported or the locale string is incorrect/missing, causing it to fall back to English.
  fix Ensure you are explicitly importing locale data for all supported languages using `@formatjs/intl-*` packages (e.g., `import '@formatjs/intl-pluralrules/locale-data/fr';`) and that your `IntlProvider` correctly receives the `locale` prop.

Warnings

• breaking React Intl v10.x primarily targets React 19. Ensure your project's React and `@types/react` dependencies are updated accordingly. Older React versions might encounter compatibility issues, especially with internal key handling for elements in arrays.
  Fix: Upgrade `react` and `@types/react` to `^19.0.0`. Review the `react-intl` v10 upgrade guide on FormatJS documentation.
• breaking Starting with React Intl v7, support for Node.js versions older than 16 was dropped. Ensure your development and deployment environments run Node.js 16 or later to leverage full internationalization support natively.
  Fix: Upgrade your Node.js environment to version 16 or newer. For older environments, polyfills for `Intl` APIs might be required.
• breaking Earlier versions of React Intl (e.g., v8.x) addressed key warnings related to React 19's stricter key handling when using `React.cloneElement` internally. If upgrading from older versions, be aware of changes to how rich text elements are wrapped (now often with `React.Fragment`).
  Fix: Update to `react-intl@8.0.0` or newer. This issue was fixed by replacing `cloneElement` with `React.Fragment` internally.
• gotcha By default, `react-intl` bundles with only basic English locale data. To support other languages, you must explicitly import and add the necessary locale data, particularly for features like `Intl.PluralRules` or `Intl.RelativeTimeFormat`.
  Fix: Dynamically import locale data for each language your application supports using a pattern like `import '@formatjs/intl-pluralrules/locale-data/fr';` and ensure polyfills for `Intl` APIs are included for older browser support.
• gotcha All `react-intl` components and hooks must be rendered within an `IntlProvider`. Failure to do so will result in an error indicating that `IntlProvider` was not found in the React context.
  Fix: Wrap your root React component (or the relevant sub-tree) with `IntlProvider`, ensuring it receives `locale` and `messages` props.
• gotcha React Intl expects message IDs to be simple strings (e.g., `homepage.header.greeting`). Using deeply nested JavaScript objects for message IDs within the `messages` prop can lead to unexpected behavior or difficulties with message extraction tools.
  Fix: Flatten your message keys into dot-separated strings or another convention that results in plain string IDs. Ensure consistency for maintainability and tool compatibility.

Install

• npm install react-intl npm
• yarn add react-intl yarn
• pnpm add react-intl pnpm

Imports

• IntlProvider
  wrong:

  const IntlProvider = require('react-intl').IntlProvider;

  correct:

  import { IntlProvider } from 'react-intl';

  `IntlProvider` is a named export. It must wrap your React app to provide the internationalization context.
• FormattedMessage
  wrong:

  import FormattedMessage from 'react-intl';

  correct:

  import { FormattedMessage } from 'react-intl';

  `FormattedMessage` is a named component export used for declarative message formatting.
• useIntl
  wrong:

  import { useIntl } from 'react-intl/hooks'; /* deprecated path */

  correct:

  import { useIntl } from 'react-intl';

  `useIntl` is a named hook export, available since React 16.8, providing imperative access to the Intl API.
• defineMessages
  wrong:

  import defineMessages from 'react-intl';

  correct:

  import { defineMessages } from 'react-intl';

  `defineMessages` is a named helper function used to define messages outside of components for extraction and maintainability.

Quickstart

This quickstart initializes `react-intl` with a French locale and a set of predefined messages. It demonstrates both the declarative `FormattedMessage` component for rendering localized strings with interpolated values and rich text, and the imperative `useIntl` hook for formatting a title. It showcases date, plural, and currency formatting.

import React from 'react';
import { IntlProvider, FormattedMessage, useIntl } from 'react-intl';

// Define messages for a specific locale
const messagesInFrench = {
  greeting: 'Bonjour {name}, bienvenue sur notre site !',
  welcome_page_title: 'Page d\'accueil',
  current_date: 'Aujourd\'hui, {ts, date, ::full}',
  unread_notifications: '{count, plural, one {# notification non lue} other {# notifications non lues}}',
  product_price: 'Prix : {price, number, currency}',
};

// Example functional component using FormattedMessage and useIntl hook
const HomePage = () => {
  const intl = useIntl();
  const userName = 'Jean-Luc';
  const notificationCount = 3;
  const productPrice = 42.50;

  return (
    <div>
      <h1>{intl.formatMessage({ id: 'welcome_page_title' })}</h1>
      <p>
        <FormattedMessage
          id="greeting"
          values={{ name: <b>{userName}</b> }}
        />
      </p>
      <p>
        <FormattedMessage
          id="current_date"
          values={{ ts: new Date() }}
        />
      </p>
      <p>
        <FormattedMessage
          id="unread_notifications"
          values={{ count: notificationCount }}
        />
      </p>
      <p>
        <FormattedMessage
          id="product_price"
          values={{ price: productPrice, currency: 'EUR' }}
        />
      </p>
    </div>
  );
};

// Root component to provide the IntlProvider context
const App = () => (
  <IntlProvider locale="fr-FR" messages={messagesInFrench}>
    <HomePage />
  </IntlProvider>
);

export default App;