# General Translation React SDKs (gt-react, gt-next, gt-react-native): 配置
URL: https://generaltranslation.com/zh/docs/react/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 通过共享的 gt.config.json 文件和运行时初始化配置 React 生态。gt.config.json 的参考。

General Translation 需要在两个位置进行配置：一个是 `gt.config.json` 文件，用于保存与 [CLI](/docs/cli/reference/config) 共用的区域设置和文件配置；另一个是运行时 setup 步骤，用于在首次渲染之前加载该配置。`gt.config.json` 文件在整个 React 生态中都是通用的；运行时 setup 则因框架而异。

*本页中的 `gt.config.json` 参考由 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native` 共享。初始化函数 ([`initializeGT`](#initialize)、[`initializeGTSPA`](#initialize-spa)) 适用于 `gt-react`；`gt-tanstack-start` 和 `gt-react-native` 也使用 `initializeGT`。*

*注意：`gt-next` 不使用这些初始化函数——它通过 `withGTConfig` 插件读取配置，详见 Next.js 部分。*

## 概览 [#overview]

一个 服务器端渲染 的 `gt-react` 应用可通过三个步骤完成 setup：初始化库、加载当前生效的区域设置对应的翻译，并使用 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 包裹组件树。

* **初始化**：对于 服务器端渲染 的 setup，使用 [`initializeGT`](#initialize)。单页应用则使用 [`initializeGTSPA`](#initialize-spa)，它还会从 cookie 和浏览器中解析当前生效的区域设置。
* **加载翻译**：使用 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 加载当前生效的区域设置对应的翻译。
* **提供**：使用 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 将区域设置和翻译提供给组件。

```tsx title="src/routes/root.tsx"
import { 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),
  };
}
```

`gt.config.json` 文件保存共享的区域设置和文件设置。初始化调用和 CLI 会读取相同的值，因此请将它们统一放在同一处。

## 初始化 [#initialization]

| Function                             | Description                   | Type       | Optional | Default |
| ------------------------------------ | ----------------------------- | ---------- | -------- | ------- |
| [`initializeGT`](#initialize)        | 初始化时不进行浏览器区域设置检测，适用于服务器端渲染应用。 | `function` | 否        | —       |
| [`initializeGTSPA`](#initialize-spa) | 初始化单页应用，包括浏览器区域设置检测。          | `function` | 否        | —       |

这两个函数都接受以下共享字段：

| Option                                                                  | Description                                                                                        | Type                                   | Optional | Default           |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ----------------- |
| `defaultLocale`                                                         | 用于翻译的源区域设置。                                                                                        | `string`                               | 是        | `en`              |
| `locales`                                                               | 支持的目标 locales。                                                                                     | `string[]`                             | 是        | `[defaultLocale]` |
| [`loadTranslations`](/docs/react/reference/functions/load-translations) | 返回某个区域设置对应翻译内容的加载器。文档：[`loadTranslations`](/docs/react/reference/functions/load-translations)。     | `(locale: string) => Promise<unknown>` | 是        | GT CDN            |
| [`loadDictionary`](/docs/react/reference/functions/load-dictionary)     | 返回某个区域设置对应 dictionary 的加载器。文档：[`loadDictionary`](/docs/react/reference/functions/load-dictionary)。 | `(locale: string) => Promise<unknown>` | 是        | —                 |
| `dictionary`                                                            | 内联 dictionary，可作为 [`loadDictionary`](/docs/react/reference/functions/load-dictionary) 的替代方案。       | `object`                               | 是        | —                 |
| `projectId`                                                             | 用于 CDN 和开发翻译的 General Translation 项目 ID。                                                           | `string`                               | 是        | —                 |
| `devApiKey`                                                             | 用于按需翻译和热重载的开发 API 密钥。                                                                              | `string`                               | 是        | —                 |
| `apiKey`                                                                | 生产环境 API 密钥。在浏览器中优先使用 `devApiKey`。                                                                 | `string`                               | 是        | —                 |
| `cacheUrl`                                                              | 自定义翻译主机。设为 `null` 时会禁用远程加载。                                                                        | `string \| null`                       | 是        | GT CDN            |
| `runtimeUrl`                                                            | 运行时 翻译主机，用于开发翻译。                                                                                   | `string \| null`                       | 是        | GT runtime        |
| `customMapping`                                                         | 区域设置别名和属性覆盖。                                                                                       | `object`                               | 是        | —                 |
| [`_tagIds`](#tag-ids)                                                   | 将每个 [`<T>`](/docs/react/reference/components/t) 翻译哈希值公开为 `data-_gt-hash` DOM 属性。                   | `boolean`                              | 是        | `false`           |

### `initializeGT` [#initialize]

**类型** `(config) => void` · **必填**

在不进行浏览器区域设置检测的情况下初始化配置和翻译缓存。请在服务器端渲染的 setup 中使用它，此时框架会提供请求的区域设置和翻译内容。

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

### `initializeGTSPA` [#initialize-spa]

**类型** `(config) => Promise<void>` · **必填**

在单页应用中初始化 `gt-react`。请在首次渲染前调用一次。它会创建翻译缓存，根据 cookie 和浏览器确定当前生效的区域设置，并预加载翻译。仅可在浏览器入口中使用。

它还接受以下仅限浏览器使用的字段：

| 选项                                  | 描述                         | 类型                                                            | 可选 | 默认值    |
| ----------------------------------- | -------------------------- | ------------------------------------------------------------- | -- | ------ |
| `locale`                            | 显式指定初始区域设置。设置后会跳过检测。       | `string`                                                      | 是  | 自动检测   |
| `region`                            | 用于区域感知格式化的初始区域代码。          | `string`                                                      | 是  | —      |
| `enableI18n`                        | 翻译内容。当为 `false` 时，渲染源区域设置。 | `boolean`                                                     | 是  | `true` |
| [`htmlTagOptions`](#htmltagoptions) | 不会自动更新 HTML 元素的兼容性字段。      | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | 是  | —      |

```tsx
await initializeGTSPA({
  ...gtConfig,
  loadTranslations,
  locale: gtConfig.defaultLocale,
});
```

由于它会从环境中确定区域设置，`initializeGTSPA` 会返回一个 Promise——请在渲染前先 `await` 它。当区域设置变化时，请在你的应用中更新 `<html>` 元素的 `lang` 和 `dir` 属性。

#### `htmlTagOptions`

**类型** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **可选**

仅在浏览器环境中兼容的字段，`initializeGTSPA` 接受此字段。传入此字段不会在区域设置变更时自动更新 `<html>` 元素的 `lang` 或 `dir` 属性；请在应用中自行更新这些属性。

## `gt.config.json` [#config-file]

`gt.config.json` 位于项目根目录，包含与 CLI 共享的区域设置和文件配置。导入该文件，并在初始化时传入其中的字段。

| 键                                          | 描述                                                                                | 类型         | 可选 | 默认值        |
| ------------------------------------------ | --------------------------------------------------------------------------------- | ---------- | -- | ---------- |
| [`projectId`](#project-id)                 | General Translation 项目 ID。                                                        | `string`   | 是  | —          |
| [`defaultLocale`](#default-locale)         | 源区域设置。                                                                            | `string`   | 是  | `en`       |
| [`locales`](#locales)                      | 目标 locales。                                                                       | `string[]` | 是  | —          |
| [`localeRouting`](#locale-routing)         | 在路径名中保留当前区域设置。                                                                    | `boolean`  | 是  | 特定于框架      |
| [`customMapping`](#custom-mapping)         | 区域设置别名和属性覆盖。                                                                      | `object`   | 是  | —          |
| [`cacheUrl`](#cache-url)                   | 缓存翻译的基础 URL。                                                                      | `string`   | 是  | GT CDN     |
| [`runtimeUrl`](#runtime-url)               | 运行时 (开发) 翻译的基础 URL。                                                               | `string`   | 是  | GT runtime |
| [`stageTranslations`](#stage-translations) | 翻译发布到 Production 前需要先审核。                                                          | `boolean`  | 是  | `false`    |
| [`files`](#files)                          | 本地翻译文件路径和解析标志。                                                                    | `object`   | 是  | —          |
| [`_tagIds`](#tag-ids)                      | 将每个 [`<T>`](/docs/react/reference/components/t) 的翻译哈希值公开为 `data-_gt-hash` DOM 属性。 | `boolean`  | 是  | `false`    |
| [`_versionId`](#version-id)                | 内部翻译版本标识符。请勿编辑。                                                                   | `string`   | 是  | —          |

### `projectId` [#project-id]

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

这是你在 General Translation 中的项目唯一标识符。CDN 交付和按需开发翻译需要使用此项。

### `defaultLocale` [#default-locale]

**类型** `string` · **可选** · **默认值** `en`

你的 UI 所使用的源区域设置。缺少翻译时会使用它作为后备内容。

### `locales` [#locales]

**Type** `string[]` · **可选**

项目支持的目标 locales，采用 BCP 47 代码，例如 `['es', 'fr']`。

### `localeRouting` [#locale-routing]

**类型** `boolean` · **可选** · **默认** 特定于框架

用于控制 TanStack Start 中带区域设置前缀的 URL。此功能需显式启用，默认值为 `false`。此选项不会定义路由：请配置可选的 `/{-$locale}` 路径参数或 URL 重写，以便 TanStack Router 同时接受无前缀和带区域设置前缀的 URL。请参阅 [TanStack Start 设置指南](/docs/react/tanstack-start/setup#locale-routing)。启用后，[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) 会优先采用第一个受支持的路径段，默认区域设置保持无前缀，而客户端区域设置变更时会重新加载到对应的路径名。

Next.js 则通过 [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware) 单独配置路由，其默认值为 `true`。此选项不会影响纯 React SPA 或 React Native。

### `customMapping` [#custom-mapping]

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

区域设置别名和属性覆盖，用于重命名区域设置，或自定义其解析和显示方式。

### `cacheUrl` [#cache-url]

**类型** `string` · **可选** · **默认值** GT CDN

用于获取缓存翻译的基础 URL。可将其设置为你自己的主机地址，或在初始化调用中传入 `null` 以禁用远程加载。

### `runtimeUrl` [#runtime-url]

**类型** `string` · **可选** · **默认值** GT runtime

运行时翻译服务的基础 URL。仅适用于开发翻译。

### `stageTranslations` [#stage-translations]

**类型** `boolean` · **可选** · **默认值** `false`

当其为 `true` 时，`gt` 工具会将翻译标记为需要审核。只有在获得批准后，才能通过 [`gt translate`](/docs/cli/reference/commands/translate) 将其部署到生产环境。

### `files` [#files]

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

用于指定将本地存储的翻译内容写入到哪里，以替代存储在云端。`files.gt.output` 是一个包含 `[locale]` 的路径模板，`files.gt.parsingFlags` 用于控制编译器如何解析你的源内容。

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json",
      "parsingFlags": {
        "enableAutoJsxInjection": true,
        "autoderive": true
      }
    }
  }
}
```

* `enableAutoJsxInjection` (`boolean`，默认值为 `false`) — 在构建时自动将可翻译的 JSX 文本包裹在翻译组件中。请参阅 [自动 JSX 注入](/docs/cli/guides/using-auto-jsx)。
* `autoderive` (`boolean`，默认值为 `false`) — 自动将 [`t()`](/docs/react/reference/functions/t-function)、`gt()` 和 [`msg()`](/docs/react/reference/functions/msg) 调用中的插值视为 [`derive()`](/docs/react/reference/functions/derive) 调用。请参阅 [autoderive](/docs/cli/guides/using-autoderive)。

完整的 `files` schema 请参阅 [CLI 配置参考](/docs/cli/reference/config)。

## `_tagIds` [#tag-ids]

**类型** `boolean` · **可选** · **默认值** `false`

在 `gt-react`、`gt-next` 和 `gt-tanstack-start` 中，为渲染的 [`<T>`](/docs/react/reference/components/t) 和 [`<Tx>`](/docs/react/nextjs/reference/components/tx) 输出启用 DOM ID 标记。本地化回放、上下文 QA 等工具会使用 `data-_gt-hash` 属性，将渲染节点映射回对应的翻译。

在共享配置文件中设置 `_tagIds`，然后将该配置传递给 [`initializeGT`](#initialize) 或 [`initializeGTSPA`](#initialize-spa)。`withGTConfig` 插件在 Next.js 中也会读取同一文件：

```json title="gt.config.json"
{
  "_tagIds": true
}
```

该值必须为字面量 `true`。任何其他值 (包括真值但非布尔类型的值) 都会使标记功能保持关闭。React Native 接受此共享配置字段，但会跳过 DOM 标记。

<Callout type="warn">
  **启用此功能可能会添加包装元素。** Span 注入会尽可能保持在最低限度：

  * **单个宿主元素** (例如 `<T><td>…</td></T>`) 会原地添加属性。不会添加包装元素，因此在 `<tr>`、`<select>` 和 `<ul>` 等受限父元素内，标记仍保持有效。
  * **纯文本、片段或组件根节点**没有可承载该属性的宿主元素，因此输出会被包装在不影响布局的 `display:contents` `<span>` 中。这是唯一会注入包装元素的情况。
  * **不渲染任何内容的输出** (`null`、`undefined`、布尔值、`''`、所有 entries 均不渲染任何内容的 arrays，或空片段) 会保持不变，因此不会出现空的 `<span>`。请注意，`0` 和 `NaN` 确实会渲染文本，并会正常添加标记。

  正因这种标记注入，标记功能默认关闭。除非你运行的工具需要这些 hashes，否则请保持关闭。
</Callout>

### `_versionId` [#version-id]

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

这是 CLI 用来跟踪翻译版本的内部标识符，可用于回滚到之前的翻译版本。它会自动生成——请勿编辑。

## 示例 [#examples]

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": { "gt": { "output": "src/_gt/[locale].json" } }
}
```

```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>
  );
}
```

## Sitemap

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