# react-native: GTProvider
URL: https://generaltranslation.com/zh/docs/react-native/api/components/gtprovider.mdx
---
title: GTProvider
description: GTProvider 组件的 API 参考文档
---

## 概述

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

### 适用场景

* 将整个应用包裹在 `<GTProvider>` 中，以启用客户端翻译。
* `<GTProvider>` 组件同时用于 [内联 `<T>`](/docs/react-native/guides/t) 和 [字典](/docs/react-native/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,
  },
}}
/>

### 说明

| 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 时加载预生成的翻译文件。                                  |
| `loadDictionary?`   | 一个异步函数，接收一个区域设置字符串并返回该区域设置对应的字典翻译。                                                          |
| `region?`           | 用户的区域代码 (例如 `US`、`GB`) 。用于特定区域的格式化。                                                         |
| `fallback?`         | 翻译加载期间显示的自定义回退内容。                                                                           |
| `customMapping?`    | 自定义组件名称到对应 React 组件的映射，用于渲染翻译后的 JSX。                                                        |

### 返回值

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

## 示例

### 基本用法

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

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations}> {/* // [!code highlight] */}
      {/* 您的应用内容 */}
    </GTProvider>
  );
}
```

### 字典

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

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';
import dictionary from './dictionary';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations} dictionary={dictionary}> {/* // [!code highlight] */}
      {/* 你的应用内容 */}
    </GTProvider>
  );
}
```

如需了解有关使用字典的更多信息，请参阅本[指南](/docs/react-native/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="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import config from './gt.config.json';

export default function App() {
  return (
    <GTProvider {...config}> {/* // [!code highlight] */}
      {/* 你的应用内容 */}
    </GTProvider>
  );
}
```

### 自定义翻译加载器

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

```jsx title="App.tsx" copy
import { GTProvider } from 'gt-react-native';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> {/* // [!code highlight] */}
      {/* 你的应用内容 */}
    </GTProvider>
  );
}
```

### 渲染设置

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

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

```jsx title="App.tsx" copy
<GTProvider renderSettings={{ method: 'skeleton', timeout: 1000 }}>
  {/* 您的应用内容 */}
</GTProvider>
```

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

***

## 注意事项

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

## 后续步骤

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