# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<GTProvider>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/gt-provider.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 向 React 组件树提供翻译和区域设置上下文。`<GTProvider>` 组件的 API 参考。

`<GTProvider>` 的具体约定因框架和 router 而异。有些 provider 通过属性接收区域设置数据，另一些则会为你解析并加载这些数据。

*注意：使用 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 初始化的 React SPA 会使用全局翻译缓存，因此不需要 provider 组件。*

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#overview]

| 运行时                  | 必需属性                    | 区域设置和翻译来源          |
| -------------------- | ----------------------- | ------------------ |
| React 服务器端渲染         | `locale`、`translations` | 你的服务器端加载器          |
| Next.js App Router   | 无                       | 请求和 `gt-next` 缓存   |
| Next.js Pages Router | `locale`、`translations` | Pages Router 数据包装器 |
| TanStack Start       | `locale`、`translations` | 你的请求加载器            |
| React Native         | 无                       | 原生区域设置检测和已配置的翻译加载器 |

[属性](#props)部分明确说明了各个 provider 变体接受哪些属性。

## 框架约定 [#contracts]

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    服务器端渲染的 `gt-react` 应用需要传入当前区域设置和翻译快照。在调用 [`initializeGT`](/docs/react/reference/config#initialize) 后加载快照。

    ```tsx
    import { GTProvider } from 'gt-react';

    <GTProvider locale={locale} translations={translations}>
      <App />
    </GTProvider>
    ```

    [`loadTranslations`](/docs/react/reference/functions/load-translations)、[`loadDictionary`](/docs/react/reference/functions/load-dictionary) 和凭据应在[初始化调用](/docs/react/reference/config#initialization)中配置，而不是传给 provider。

    <Callout type="info">
      **v11 变更：**`gt-react` 的 `<GTProvider>` 不再接受 `config`、[`loadTranslations`](/docs/react/reference/functions/load-translations)、[`loadDictionary`](/docs/react/reference/functions/load-dictionary) 或凭据。请将这些内容移至 [`initializeGT`](/docs/react/reference/config#initialize)，然后将解析后的 `locale` 和 `translations` 传给 provider。
    </Callout>
  </Tab>

  <Tab value="Next.js">
    ### App Router

    App Router 的 provider 是一个异步服务器组件，仅接受 `children` 属性。它会根据请求和 `gt-next` 缓存解析区域设置、地区、翻译状态、翻译和字典。

    ```tsx title="app/layout.tsx"
    import { GTProvider } from 'gt-next';

    export default function RootLayout({ children }) {
      return <GTProvider>{children}</GTProvider>;
    }
    ```

    不要向 App Router provider 传入 `locale`、`translations`、`dictionaries`、`region` 或 `enableI18n`。

    ### Pages Router

    Pages Router 重新导出了共享的 `gt-react` provider。传入通过[服务器端渲染](/docs/react/nextjs-pages-router-quickstart#quickstart)或[静态生成](/docs/react/nextjs/pages-router-static-site-generation)注入的值；如果区域设置变更应通过 Next.js 路由处理，请提供 `_reload`。

    ```tsx title="pages/_app.tsx"
    import Router from 'next/router';
    import { GTProvider } from 'gt-next';

    <GTProvider
      locale={pageProps.locale}
      translations={pageProps.translations}
      _reload={({ locale }) => {
        void Router.push(Router.pathname, Router.asPath, { locale });
      }}
    >
      <Component {...pageProps} />
    </GTProvider>
    ```
  </Tab>

  <Tab value="TanStack Start">
    `gt-tanstack-start` 重新导出了共享 provider。注册 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) 后，传入当前区域设置及其翻译快照。

    ```tsx
    import { GTProvider } from 'gt-tanstack-start';

    <GTProvider locale={locale} translations={translations}>
      <App />
    </GTProvider>
    ```
  </Tab>

  <Tab value="React Native">
    React Native provider 会检测初始区域设置、加载对应翻译，并在区域设置变更时重新渲染。`locale` 是可选属性，`translations` 不是公开属性。

    ```tsx
    import { GTProvider } from 'gt-react-native';

    <GTProvider>
      <App />
    </GTProvider>
    ```

    传入 `fallback` 可在翻译加载期间替换内置加载指示器。
  </Tab>
</Tabs>

## 工作原理 [#how-it-works]

* **React、TanStack Start 和 Next.js Pages Router。** provider 会预先接收翻译快照，因此可同步渲染翻译后的内容。
* **Next.js App Router。** 服务器端 provider 会读取请求状态，并在渲染其客户端边界前加载翻译和字典。
* **React Native。** provider 通过 Suspense 加载已解析区域设置的翻译。在翻译可用前，会渲染 `fallback`。
* **组件树的上下文。** 子组件从 provider 上下文中读取当前区域设置、翻译、字典、区域和翻译状态。
* **区域设置变更。** Web provider 会将区域设置持久化到 cookie，并触发重新加载。React Native 会将其持久化到原生存储中，并更新 provider 状态。

## 属性 [#props]

| 属性                                                      | 描述                                                                                                 | 类型                           | 可选    | 默认值                            |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------- | ----- | ------------------------------ |
| [`children`](#children)                                 | 组件树。所有 provider 均可接受。                                                                              | `ReactNode`                  | 是     | —                              |
| [`locale`](#locale)                                     | 当前区域设置。React、TanStack Start 和 Next.js Pages Router 中必填；React Native 中可选；Next.js App Router 不支持。    | `string \| LocaleCandidates` | 特定于框架 | React Native 中为设备区域设置或已保存的区域设置 |
| [`translations`](#translations)                         | 翻译快照。React、TanStack Start 和 Next.js Pages Router 中必填；Next.js App Router 和 React Native 不支持。        | `object`                     | 特定于框架 | —                              |
| [`dictionaries`](#dictionaries)                         | 按区域设置划分的字典。React、TanStack Start、Next.js Pages Router 和 React Native 均支持；Next.js App Router 会在内部加载。 | `object`                     | 是     | —                              |
| [`region`](#region)                                     | 当前区域。React、TanStack Start、Next.js Pages Router 和 React Native 均支持；Next.js App Router 会在内部解析。       | `string`                     | 是     | 已保存的区域或 `undefined`            |
| [`enableI18n`](#enable-i18n)                            | 是否进行翻译。React、TanStack Start、Next.js Pages Router 和 React Native 均支持；Next.js App Router 会在内部解析。     | `boolean`                    | 是     | `true`                         |
| [`fallback`](#fallback)                                 | React Native 获取翻译期间显示的加载内容。仅适用于 React Native。                                                      | `ReactNode`                  | 是     | 加载指示器                          |
| [`_reload`](#reload)                                    | 框架重新加载回调。React、TanStack Start 和 Next.js Pages Router 支持；Next.js App Router 和 React Native 不支持。     | `(state) => void`            | 是     | 特定于框架                          |
| [`onMissingTranslation`](#missing-translation)          | 处理缺失的内联或 JSX 翻译。Next.js App Router 不支持。                                                            | `OnMissingTranslation`       | 是     | —                              |
| [`onMissingDictionaryEntry`](#missing-dictionary-entry) | 处理缺失的字典条目。Next.js App Router 不支持。                                                                  | `OnMissingDictionaryEntry`   | 是     | —                              |
| [`onMissingDictionaryObj`](#missing-dictionary-object)  | 处理缺失的字典对象。Next.js App Router 不支持。                                                                  | `OnMissingDictionaryObj`     | 是     | —                              |

### `children` [#children]

**类型** `ReactNode` · **可选**

接收翻译上下文的组件树。每种 provider 变体都接受 `children`。

### `locale` [#locale]

**类型** `string | LocaleCandidates` · **特定于框架**

树当前使用的区域设置：

* 在 React、TanStack Start 和 Next.js Pages Router 中，必须提供已解析的 `string`。
* 在 React Native 中为可选项，可接受区域设置候选项，默认使用已存储的区域设置或设备区域设置。
* Next.js App Router provider 不接受此项，而是在内部解析请求区域设置。

使用 [`useLocale`](/docs/react/reference/hooks/use-locale) 在下游获取结果。

### `translations` [#translations]

**类型** `Record<Locale, Record<Hash, Translation>>` · **特定于框架**

由 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 生成的翻译快照。在 React、TanStack Start 和 Next.js Pages Router 中，必须提供此项，以便这些 provider 能够同步解析内容。

Next.js App Router provider 会在内部加载翻译快照。React Native provider 不接受 `translations` prop，而是自行加载当前区域设置对应的翻译。

### `dictionaries` [#dictionaries]

**类型** `Record<Locale, Dictionary>` · **可选**

按区域设置组织的字典，供 [`useTranslations`](/docs/react/reference/hooks/use-translations) 根据 id 进行查找。React、TanStack Start、Next.js Pages Router 和 React Native 接受此 prop。Next.js App Router provider 会在内部加载字典。

### `region` [#region]

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

当前生效的区域代码，例如 `US` 或 `GB`。React、TanStack Start、Next.js Pages Router 和 React Native 接受此 prop。Next.js App Router 从请求中解析区域。

### `enableI18n` [#enable-i18n]

**Type** `boolean` · **可选** · **默认值** `true`

是否启用内容翻译。为 `false` 时，provider 会渲染源区域设置的内容。React、TanStack Start、Next.js Pages Router 和 React Native 接受此 prop。Next.js App Router 会从请求状态解析该值。

### `fallback` [#fallback]

**类型** `ReactNode` · **可选**

仅适用于 React Native，在翻译加载期间显示的内容。默认值为居中显示的 React Native `ActivityIndicator`。

### `_reload` [#reload]

**类型** `(state: { locale: string; region: string | undefined; enableI18n: boolean }) => void` · **可选** · **默认值** 特定于框架

Web 区域设置、区域或翻译状态变更后调用的回调。React 和 TanStack Start 通过共享 provider 接收此回调。Next.js Pages Router 使用它通过 `Router.push` 替代整页重新加载。

原生 `gt-react` 和 Next.js Pages Router 会回退到 `window.location.reload`。启用区域设置路由时，TanStack Start 会提供 pathname 导航。Next.js App Router provider 提供自己的回调，不接受此 prop：它通常调用 `router.refresh`，但在切换到默认区域设置后，若 middleware 必须移除非默认区域设置前缀，则会重新加载文档。React Native 则会更新 provider 状态。

### `onMissingTranslation` [#missing-translation]

**类型** `OnMissingTranslation` · **可选**

用于处理缺失的内联或 JSX 翻译的高级回调。浏览器和 React Native Provider 可使用传入的回调。服务器端渲染 Provider 会安装自己的处理程序。

### `onMissingDictionaryEntry` [#missing-dictionary-entry]

**类型** `OnMissingDictionaryEntry` · **可选**

用于处理缺失字典条目的高级回调。浏览器和 React Native provider 可使用传入的回调。服务器端渲染 provider 会自行安装处理程序。

### `onMissingDictionaryObj` [#missing-dictionary-object]

**类型** `OnMissingDictionaryObj` · **可选**

用于处理字典对象缺失情况的高级回调。浏览器和 React Native provider 可使用传入的回调。服务器端渲染 provider 会安装自己的处理程序。

## Sitemap

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