# gt-react: General Translation React SDK: GTProvider
URL: https://generaltranslation.com/zh/docs/react/api/components/gtprovider.mdx
---
title: GTProvider
description: GTProvider 组件 API 参考
---

## 概述

`<GTProvider>` 组件会向其子组件提供 General Translation (GT) 上下文，使其能够访问翻译后的内容。
如果应用需要进行任何客户端翻译，就必须使用该组件。

### 何时使用

* 将整个应用程序包裹在 `<GTProvider>` 中，以在客户端启用翻译。

* `<GTProvider>` 组件同时用于 [内联 `<T>`](/docs/react/guides/t) 和 [字典](/docs/react/guides/dictionaries)。

## 参考

### 属性

<TypeTable
  type={{
children: {
type: 'ReactNode',
optional: false,
},
projectId: {
type: 'string',
optional: true,
},
'dictionary?': {
type: 'Dictionary',
optional: true,
default: 'defaultDictionary',
},
'locales?': {
type: 'string[]',
optional: true,
},
'defaultLocale?': {
type: 'string',
optional: true,
default: 'libraryDefaultLocale',
},
'locale?': {
type: 'string',
optional: true,
},
'cacheUrl?': {
type: 'string',
optional: true,
default: "'https://cdn.gtx.dev'",
},
'runtimeUrl?': {
type: 'string',
optional: true,
default: "'https://runtime.gtx.dev'",
},
'renderSettings?': {
type: 'RenderSettings',
optional: true,
default: 'defaultRenderSettings',
},
'_versionId?': {
type: 'string',
optional: true,
},
'devApiKey?': {
type: 'string',
optional: true,
},
'config?': {
type: 'object',
optional: true,
},
'loadTranslations?': {
type: '(locale: string) => Promise<Record<string, any>>',
optional: true,
},
'loadDictionary?': {
type: '(locale: string) => Promise<Record<string, any>>',
optional: true,
},
'region?': {
type: 'string',
optional: true,
},
'fallback?': {
type: 'ReactNode',
optional: true,
},
'customMapping?': {
type: 'CustomMapping',
optional: true,
},
'enableI18n?': {
type: 'boolean',
optional: true,
default: 'true',
},
}}
/>

### 说明

| Prop                | 说明                                                                                                 |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `children`          | 任何需要在客户端进行翻译或访问翻译信息的子元素，或这类子元素的父组件。应包括所有使用 `<T>`、`useGT` 或其他翻译工具的组件。                               |
| `projectId?`        | General Translation 云服务所需的项目 ID。                                                                   |
| `dictionary?`       | 项目的翻译字典。                                                                                           |
| `locales?`          | 项目已启用的区域设置列表。                                                                                      |
| `defaultLocale?`    | 未找到其他区域设置时使用的默认区域设置。                                                                               |
| `locale?`           | 当前区域设置 (如果已设置) 。                                                                                   |
| `cacheUrl?`         | 用于获取翻译的缓存服务 URL。                                                                                   |
| `runtimeUrl?`       | 用于获取翻译的 runtime 服务 URL。                                                                            |
| `renderSettings?`   | 渲染翻译时使用的设置。                                                                                        |
| `_versionId?`       | 用于获取翻译的版本 ID。                                                                                      |
| `devApiKey?`        | 开发环境使用的 API 密钥。                                                                                    |
| `config?`           | 配置对象 (通常从 `gt.config.json` 导入) ，其中包含 `projectId`、`locales`、`defaultLocale` 及其他设置。可替代将这些值作为单独的属性传递。 |
| `loadTranslations?` | 一个异步函数，接收区域设置字符串并返回该区域设置的译文对象。用于在 runtime 加载预生成的翻译文件。用法请参阅 [快速入门](/docs/react)。                    |
| `loadDictionary?`   | 一个异步函数，接收区域设置字符串并返回该区域设置对应的字典译文。                                                                   |
| `region?`           | 用户的区域代码 (例如 `US`、`GB`)。用于特定区域的格式设置。                                                                |
| `fallback?`         | 翻译加载期间显示的自定义后备内容。                                                                                  |
| `customMapping?`    | 自定义组件名称到对应 React 组件的映射，用于渲染已翻译的 JSX。                                                               |
| `enableI18n?`       | 是否启用 i18n 功能。默认为 `true`。                                                                           |

### 返回值

包含传递给该组件的子元素的 `React.JSX.Element|undefined`。

## 示例

### 基本用法

使用 `<GTProvider>` 包裹应用，为应用添加翻译功能。
别忘了添加[支持的区域设置列表](/docs/platform/supported-locales)以启用翻译。

```jsx title="index.js" copy
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { GTProvider } from "gt-react";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']}> // 启用西班牙语和法语 // [!code highlight]
      <App />
    </GTProvider> // [!code highlight]
  </StrictMode>
);
```


### 字典

你也可以将字典传给 `<GTProvider>` 组件，然后通过 [`useTranslations`](/docs/react/api/dictionary/use-translations) Hook 来访问它。

```jsx title="index.js" copy
import dictionary from "./dictionary.js";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);
```

有关使用字典的更多信息，请参阅本[指南](/docs/react/guides/dictionaries)。


### 添加配置

如果你不想直接向 `<GTProvider>` 组件传递属性，可以创建一个配置文件并将其传给该组件。
它还可直接与 [`gt translate` 命令](/docs/cli/translate) 集成，因此你无需再手动将 locales 等内容作为参数指定。

```json title="gt.config.json" copy
{
  "projectId": "your-project-id",
  "locales": ["es", "fr"],
  "defaultLocale": "en-US",
  "_versionId": "translation-version-id" // 允许回滚到之前的翻译版本（由 CLI 自动生成）
}
```

你只需将其传给 `<GTProvider>` 组件即可。

```jsx title="index.js" copy
import config from "../gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);
```


### 自定义翻译加载器

你可以使用 `loadTranslations` prop 从自定义来源加载翻译。
当你需要从其他来源 (例如自定义 API) 加载翻译时，这会很有帮助。

```jsx title="index.js" copy
import loadTranslations from "./loadTranslations";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);
```


### 渲染设置

渲染设置用于控制翻译的加载行为。
包含两个字段：`timeout` 和 `method`。

* `timeout` 表示在显示后备内容前，等待翻译加载完成的毫秒数 (默认值：`8000ms`) 。
* `method` 表示加载翻译时使用的方法 (`"skeleton"`、`"replace"` 或 `"default"`) 。

```jsx title="index.js" copy
<GTProvider renderSettings={{ method: 'skeleton', timeout: 1000 }}>
  <App />
</GTProvider>
```

每种渲染设置对应不同的加载行为：
`"skeleton"` 会在翻译加载完成前返回 `null`。
`"replace"` 会在翻译加载完成前返回备用内容。
`"default"` 会在翻译加载完成前返回 `null`，除非回退区域设置与当前区域设置的语言相同 (例如 `en-US` 和 `en-GB`) 。
在这种情况下，在翻译加载完成前，它会立即返回备用内容。

***


## 注意事项

* `<GTProvider>` 必须包裹所有 [`<T>` 组件](/docs/react/api/components/t) 及其他与翻译相关的函数。更多信息请参见[此处](/docs/react/api/components/gtprovider)。

## 后续步骤

* 进一步了解用于翻译文本和组件的 [`<T>` 组件](/docs/react/guides/t)。