# General Translation React SDKs (gt-react, gt-next): GTProvider
URL: https://generaltranslation.com/zh/docs/react/reference/components/gt-provider.mdx
---

title: GTProvider
description: 向 General Translation 的 gt-react 组件树提供当前区域设置及其翻译。GTProvider 的 API 参考。

---

`<GTProvider>` 组件会为 服务器端渲染 的 `gt-react` 组件树提供当前区域设置及对应的翻译。当服务器加载翻译并将其传递给客户端时，请使用它。

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

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。示例从 `gt-react` 导入；请改为从你的框架对应的包中导入。*

*注意：区域设置和翻译传递到 `<GTProvider>` 的方式因框架而异。在 `gt-react` 中，你需要将它们作为属性传入 (如下) ；而 `gt-next`、`gt-tanstack-start` 和 `gt-react-native` 则通过各自的初始化配置来解析，具体见各框架对应章节的文档。*

## 概览 [#overview]

完成[初始化](/docs/react/reference/config#initialization)后，使用 `<GTProvider>` 包裹你的应用。传入当前的 `区域设置`，以及通过 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 加载的该 `区域设置` 对应的 `translations`。

```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)中，而不是传给 `<GTProvider>`。该 provider 会同步使用已解析的区域设置和翻译内容。*

<Callout type="info">
  **v11 中的变更：** `gt-react` 的 `<GTProvider>` 不再接受 `config`、`loadTranslations`、`loadDictionary` 或凭据。请将这些移到[初始化调用](/docs/react/reference/config#initialization)中，并改为将已解析的 `locale` 和 `translations` (来自 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)) 传递给 provider。
</Callout>

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

* **同步翻译。** provider 需要预先传入 `translations`，这样已翻译内容就能同步渲染，不会出现加载闪烁。完成初始化后，可使用 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 生成该对象。
* **为组件树提供上下文。** 在基于 provider 的 setup 中，provider 下方的组件会从中读取当前区域设置、translations、dictionaries 和 region。
* **切换翻译。** 当 `enableI18n` 为 `false` 时，provider 会渲染源区域设置的内容并跳过翻译，这对于预览未翻译的应用很有用。

## 属性 [#props]

| Prop                            | 描述                                                                               | Type        | 可选 | 默认值    |
| ------------------------------- | -------------------------------------------------------------------------------- | ----------- | -- | ------ |
| [`locale`](#locale)             | 此树的活动区域设置。                                                                       | `string`    | 否  | —      |
| [`translations`](#translations) | 活动区域设置对应的翻译内容。                                                                   | `object`    | 否  | —      |
| [`dictionaries`](#dictionaries) | [`useTranslations`](/docs/react/reference/hooks/use-translations) 使用的按区域设置划分的字典。 | `object`    | 是  | —      |
| [`region`](#region)             | 活动区域代码。                                                                          | `string`    | 是  | —      |
| [`enableI18n`](#enable-i18n)    | 是否翻译内容。为 `false` 时，渲染源区域设置。                                                      | `boolean`   | 是  | `true` |
| [`children`](#children)         | 应用树。                                                                             | `ReactNode` | 是  | —      |

### `locale` [#locale]

**类型** `string` · **必填**

该树当前生效的区域设置，采用 BCP 47 代码，例如 `es`。你可以在下层组件中通过 [`useLocale`](/docs/react/reference/hooks/use-locale) 读取它。

### `translations` [#translations]

**类型** `object` · **必填**

当前生效区域设置的翻译，格式需与 provider 同步使用的格式一致。请在初始化后使用 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 生成。

### `dictionaries` [#dictionaries]

**类型** `object` · **可选**

按区域设置组织的字典，供 [`useTranslations`](/docs/react/reference/hooks/use-translations) 根据 id 进行查找。若你只使用 `<T>` 和 `useGT`，则可省略此项。

### `region` [#region]

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

当前生效的区域代码 (例如 `US` 或 `GB`) ，用于区域相关的格式设置，也可供区域钩子和选择器使用。

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

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

是否启用内容翻译。为 `false` 时，provider 会渲染源区域设置的内容，并跳过翻译。

### `children` [#children]

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

应用的组件树。在基于 provider 的设置中，所有进行翻译或读取区域设置状态的组件都必须位于该 provider 之下。

## 示例 [#examples]

```tsx title="src/routes/root.tsx"
import {
  GTProvider,
  initializeGT,
  getTranslationsSnapshot,
  parseLocale,
} from 'gt-react';
import gtConfig from '../../gt.config.json';

const loadTranslations = (locale: string) =>
  import(`../_gt/${locale}.json`).then((m) => m.default);

initializeGT({ ...gtConfig, loadTranslations });

export async function loadRoot(request: Request) {
  const locale = parseLocale(request);
  return {
    locale,
    translations: await getTranslationsSnapshot(locale),
  };
}

export function Root({ locale, translations, children }) {
  return (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

```tsx
// 预览未翻译的（源区域设置）应用
<GTProvider locale={locale} translations={translations} enableI18n={false}>
  <App />
</GTProvider>
```