# General Translation React SDKs (gt-react, gt-next, gt-react-native): Plugin
URL: https://generaltranslation.com/en-US/docs/react/react-native/plugin.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Reference for the General Translation gt-react-native Babel plugin, which injects the Intl polyfills React Native needs. API reference for the gt-react-native plugin.

`gt-react-native/plugin` is a Babel plugin that injects the `@formatjs` `Intl` polyfills `gt-react-native` needs. React Native's JavaScript runtime does not ship the full `Intl` APIs used to format numbers, dates, plurals, and locale names, so the plugin adds them at your app's entry point.

Configure it in `babel.config.js`. It is part of the standard React Native [setup](/docs/react/react-native/setup); this page documents what it does and its options.

## Overview [#overview]

Add the plugin to your Babel config, pointing `entryPointFilePath` at your app's entry file and passing the locales to polyfill. The plugin is a **named export**, so destructure it (`const { plugin } = require('gt-react-native/plugin')`) rather than using the module object directly.

```js title="babel.config.js"
const { plugin: gtPlugin } = require('gt-react-native/plugin');
const gtConfig = require('./gt.config.json');

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      [
        gtPlugin,
        {
          locales: [gtConfig.defaultLocale, ...gtConfig.locales],
          entryPointFilePath: require.resolve('expo-router/entry'),
        },
      ],
    ],
  };
};
```

## How it works [#how-it-works]

At build time, when Babel transforms the file at `entryPointFilePath`, the plugin prepends `import` statements for:

- The base `@formatjs` polyfills — `getcanonicallocales`, `locale`, `displaynames`, `listformat`, `pluralrules`, `numberformat`, `relativetimeformat`, and `datetimeformat` (with all time zones) — minus any listed in `excludePolyfills`.
- The locale data for each resolved locale, across the `displaynames`, `listformat`, `pluralrules`, `numberformat`, `relativetimeformat`, and `datetimeformat` polyfills.

The plugin only modifies the entry file, and it skips any polyfill import you already have. The locales are resolved from `locales`, or from `config`/`configFilePath` if you pass those instead.

<Callout type="warn">
  **Regional locales:** The plugin uses each configured locale code unchanged
  for every locale-data import. FormatJS does not provide every regional code
  for every polyfill; for example, `Intl.PluralRules` provides `es` but not an
  `es-US` module. If a generated import is missing, add the polyfills manually
  below so each import can use an available locale-data code while your app
  keeps its regional locale.
</Callout>

<Accordions>
  <Accordion title="Add the polyfills manually">

If you do not want to use the Babel plugin, install the FormatJS packages directly in your app:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install @formatjs/intl-getcanonicallocales @formatjs/intl-locale @formatjs/intl-displaynames @formatjs/intl-listformat @formatjs/intl-pluralrules @formatjs/intl-numberformat @formatjs/intl-relativetimeformat @formatjs/intl-datetimeformat
    ```
  </Tab>
  <Tab value="yarn">
    ```bash
    yarn add @formatjs/intl-getcanonicallocales @formatjs/intl-locale @formatjs/intl-displaynames @formatjs/intl-listformat @formatjs/intl-pluralrules @formatjs/intl-numberformat @formatjs/intl-relativetimeformat @formatjs/intl-datetimeformat
    ```
  </Tab>
  <Tab value="bun">
    ```bash
    bun add @formatjs/intl-getcanonicallocales @formatjs/intl-locale @formatjs/intl-displaynames @formatjs/intl-listformat @formatjs/intl-pluralrules @formatjs/intl-numberformat @formatjs/intl-relativetimeformat @formatjs/intl-datetimeformat
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm add @formatjs/intl-getcanonicallocales @formatjs/intl-locale @formatjs/intl-displaynames @formatjs/intl-listformat @formatjs/intl-pluralrules @formatjs/intl-numberformat @formatjs/intl-relativetimeformat @formatjs/intl-datetimeformat
    ```
  </Tab>
</Tabs>

Add the base polyfills and locale data at the top of your entry file, before importing your application. This example loads `en` and `es-US`:

```js title="index.js"
// Base Intl polyfills
import '@formatjs/intl-getcanonicallocales/polyfill';
import '@formatjs/intl-locale/polyfill';
import '@formatjs/intl-displaynames/polyfill';
import '@formatjs/intl-listformat/polyfill';
import '@formatjs/intl-pluralrules/polyfill-force';
import '@formatjs/intl-numberformat/polyfill';
import '@formatjs/intl-relativetimeformat/polyfill';
import '@formatjs/intl-datetimeformat/polyfill';
import '@formatjs/intl-datetimeformat/add-all-tz';

// English locale data
import '@formatjs/intl-displaynames/locale-data/en';
import '@formatjs/intl-listformat/locale-data/en';
import '@formatjs/intl-pluralrules/locale-data/en';
import '@formatjs/intl-numberformat/locale-data/en';
import '@formatjs/intl-relativetimeformat/locale-data/en';
import '@formatjs/intl-datetimeformat/locale-data/en';

// United States Spanish locale data
import '@formatjs/intl-displaynames/locale-data/es-US';
import '@formatjs/intl-listformat/locale-data/es-US';
import '@formatjs/intl-pluralrules/locale-data/es';
import '@formatjs/intl-numberformat/locale-data/es-US';
import '@formatjs/intl-relativetimeformat/locale-data/es-US';
import '@formatjs/intl-datetimeformat/locale-data/es-US';
```

Keep `es-US` as your app locale. Use `es` only for the `PluralRules` data import because `@formatjs/intl-pluralrules` does not ship an `es-US` locale-data module. See [FormatJS's polyfill documentation](https://formatjs.github.io/docs/polyfills) for other locales and polyfills.

  </Accordion>
</Accordions>

## Options [#options]

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`locales`](#locales) | Locale codes to load locale data for. | `string[]` | Yes | From `config` |
| [`entryPointFilePath`](#entry-point-file-path) | Path to the entry file the polyfills are added to. | `string` | Yes | `src/App.tsx` |
| [`config`](#config) | General Translation config object to read locales from. | `object` | Yes | — |
| [`configFilePath`](#config-file-path) | Path to a `gt.config.json` to read locales from. | `string` | Yes | — |
| [`excludePolyfills`](#exclude-polyfills) | Base polyfills to skip. | `string[]` | Yes | `[]` |

### `locales` [#locales]

**Type** `string[]` · **Optional**

The locale codes to load `@formatjs` locale data for. Include your default locale and every target locale, for example `[gtConfig.defaultLocale, ...gtConfig.locales]`. When omitted, locales are resolved from `config` or `configFilePath`.

### `entryPointFilePath` [#entry-point-file-path]

**Type** `string` · **Optional** · **Default** `src/App.tsx`

Absolute path to the file the polyfill imports are injected into. This must be your app's true entry point. Common values are `require.resolve('expo-router/entry')` for Expo and `path.resolve(__dirname, 'index.js')` for the bare React Native CLI.

### `config` [#config]

**Type** `{ defaultLocale: string; locales: string[] } & Record<string, unknown>` · **Optional**

A General Translation config object to resolve locales from, as an alternative to passing `locales` directly.

### `configFilePath` [#config-file-path]

**Type** `string` · **Optional**

Path to a `gt.config.json` file to resolve locales from, as an alternative to passing `locales` or `config`.

### `excludePolyfills` [#exclude-polyfills]

**Type** `string[]` · **Optional** · **Default** `[]`

Base polyfill import paths to skip, in case you provide one yourself. Values must match the plugin's base polyfill import paths, such as `@formatjs/intl-datetimeformat/add-all-tz`.

## Example [#example]

Bare React Native CLI, pointing at `index.js`:

```js title="babel.config.js"
const path = require('path');
const { plugin: gtPlugin } = require('gt-react-native/plugin');
const gtConfig = require('./gt.config.json');

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    [
      gtPlugin,
      {
        locales: [gtConfig.defaultLocale, ...gtConfig.locales],
        entryPointFilePath: path.resolve(__dirname, 'index.js'),
      },
    ],
  ],
};
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.