# General Translation React SDKs (gt-react, gt-next, gt-react-native): 插件
URL: https://generaltranslation.com/zh/docs/react/react-native/plugin.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation 的 gt-react-native Babel 插件参考文档。该插件会注入 React Native 所需的 Intl polyfill。gt-react-native 插件的 API 参考。

`gt-react-native/plugin` 是一个 Babel 插件，用于注入 `gt-react-native` 所需的 `@formatjs` `Intl` polyfill。React Native 的 JavaScript 运行时并未内置用于格式化数字、日期、复数形式和区域设置名称的完整 `Intl` API，因此该插件会在应用的入口文件中将它们加入。

请在 `babel.config.js` 中进行配置。它是标准 React Native [设置](/docs/react/react-native/setup) 的一部分；本页介绍它的作用及可用选项。

## 概览 [#overview]

将该插件添加到 Babel 配置中，把 `entryPointFilePath` 指向应用的入口文件，并传入需要 polyfill 的区域设置。该插件是**具名导出**，因此应通过解构来使用它 (`const { plugin } = require('gt-react-native/plugin')`) ，而不要直接使用模块对象。

```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]

在构建阶段，Babel 转换 `entryPointFilePath` 指定的文件时，插件会在文件开头插入以下 `import` 语句：

* 基础 `@formatjs` polyfill：`getcanonicallocales`、`locale`、`displaynames`、`listformat`、`pluralrules`、`numberformat`、`relativetimeformat` 和 `datetimeformat` (包含所有时区) ，但会排除 `excludePolyfills` 中列出的项。
* 每个已解析区域设置的区域设置数据，适用于 `displaynames`、`listformat`、`pluralrules`、`numberformat`、`relativetimeformat` 和 `datetimeformat` polyfill。

该插件仅会修改入口文件，并会跳过已存在的 polyfill 导入语句。区域设置会从 `locales` 中解析；如果传入的是 `config`/`configFilePath`，则会从中解析。

<Callout type="warn">
  **区域设置变体：** 插件会原样使用每个配置的区域设置代码，
  用于所有区域设置数据导入。FormatJS 并未为每个 polyfill 提供所有区域代码；
  例如，`Intl.PluralRules` 提供 `es`，但不提供 `es-US`
  模块。如果生成的导入缺失，请按下文所示手动添加 polyfill，
  以便每个导入都能使用可用的区域设置数据代码，同时让应用
  保持其区域设置变体。
</Callout>

<Accordions>
  <Accordion title="手动添加 polyfill">
    如果不想使用 Babel 插件，可以直接在应用中安装 FormatJS package：

    <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>

    在入口文件顶部、导入应用之前添加基础 polyfill 和区域设置数据。以下示例加载 `en` 和 `es-US`：

    ```js title="index.js"
    // 基础 Intl polyfill
    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';

    // 英语区域设置数据
    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';

    // 美国西班牙语区域设置数据
    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';
    ```

    请继续将 `es-US` 用作应用的区域设置。仅在导入 `PluralRules` 数据时使用 `es`，因为 `@formatjs/intl-pluralrules` 不提供 `es-US` 区域设置数据模块。有关其他区域设置和 polyfill，请参阅 [FormatJS 的 polyfill 文档](https://formatjs.github.io/docs/polyfills)。
  </Accordion>
</Accordions>

## 选项 [#options]

| 选项                                             | 描述                                         | 类型         | 可选 | 默认值           |
| ---------------------------------------------- | ------------------------------------------ | ---------- | -- | ------------- |
| [`locales`](#locales)                          | 要加载其区域设置数据的区域设置代码。                         | `string[]` | 是  | 来自 `config`   |
| [`entryPointFilePath`](#entry-point-file-path) | 要添加 polyfills 的入口文件路径。                     | `string`   | 是  | `src/App.tsx` |
| [`config`](#config)                            | 用于从中读取 locales 的 General Translation 配置对象。 | `object`   | 是  | —             |
| [`configFilePath`](#config-file-path)          | 用于从中读取 locales 的 `gt.config.json` 路径。      | `string`   | 是  | —             |
| [`excludePolyfills`](#exclude-polyfills)       | 要跳过的基础 polyfills。                          | `string[]` | 是  | `[]`          |

### `locales` [#locales]

**类型** `string[]` · **可选**

要加载 `@formatjs` 区域设置数据的区域设置代码。请包含默认区域设置以及每个目标区域设置，例如 `[gtConfig.defaultLocale, ...gtConfig.locales]`。如果省略，则会从 `config` 或 `configFilePath` 中解析区域设置。

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

**类型** `string` · **可选** · **默认值** `src/App.tsx`

注入 polyfill 导入语句的文件的绝对路径。这里必须填写应用真正的入口文件。常见值包括：Expo 使用 `require.resolve('expo-router/entry')`，bare React Native CLI 使用 `path.resolve(__dirname, 'index.js')`。

### `config` [#config]

**类型** `{ defaultLocale: string; locales: string[] } & Record<string, unknown>` · **可选**

General Translation 的配置对象，用于从中解析区域设置，可替代直接传入 `locales`。

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

**类型** `string` · **可选**

`gt.config.json` 文件的路径，用于从该文件中解析区域设置，可作为传入 `locales` 或 `config` 的替代方案。

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

**类型** `string[]` · **可选** · **默认值** `[]`

要跳过的基础 polyfill 导入路径；如果你已自行提供，则可使用此项跳过。其取值必须与该插件的基础 polyfill 导入路径完全一致，例如 `@formatjs/intl-datetimeformat/add-all-tz`。

## 示例 [#example]

原生 React Native CLI，指向 `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.