# General Translation React SDKs (gt-react, gt-next, gt-react-native): Plugin
URL: https://generaltranslation.com/en-GB/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 include 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) — excluding 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 skips any polyfill imports you already have. The locales are resolved from `locales`, or from `config`/`configFilePath` if you provide 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&#39;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 to which the polyfills are added. | `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 that the polyfill imports are injected into. This must be your app&#39;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 from which to resolve locales, as an alternative to passing `locales` directly.

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

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

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

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

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

Base polyfill import paths to skip, if you provide your own. Values must match the plugin&#39;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.