Migrate from React Intl to Intlayer

If your React application uses react-intl (FormatJS), transitioning to Intlayer is a breeze. Our compat layer seamlessly handles ICU MessageFormat and all existing Formatted* components.

What to do

Start by running the initialization command in your project:

npx intlayer init --interactive

Then, set up the Intlayer Vite or Next.js plugin in your configuration. This plugin injects build-time aliases to redirect react-intl imports to @intlayer/react-intl.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import reactIntlVitePlugin from "@intlayer/react-intl/plugin";

export default defineConfig({
  plugins: [react(), reactIntlVitePlugin()],
});

What it does under the hood

The bundler plugin aliases react-intl to @intlayer/react-intl. Instead of parsing large JSON files manually and wrapping your app in an IntlProvider, the Intlayer plugin statically extracts keys and uses Intlayer dictionaries at runtime.

Under the hood:

• ICU MessageFormat: Intlayer uses the resolveMessage(..., 'icu') resolver which fully supports the ICU pluralization, selection, date/number formatting, and rich text tags natively.
• Method & JSX callers: intl.formatMessage({ id: 'a.b' }) and <FormattedMessage id="a.b"> are identified by the Intlayer compiler plugins (@intlayer/babel / @intlayer/swc), converting flat dotted keys so that the first segment correctly resolves to the Intlayer dictionary key.
• Formatters: <FormattedNumber>, <FormattedDate>, etc., bridge over to the native core/formatters using Intl.

To understand where these libraries come from, read the history of JavaScript i18n.