# General Translation React SDKs (gt-react, gt-next): 配置 URL: https://generaltranslation.com/zh/docs/react/reference/config.mdx --- title: 配置 description: 通过共享的 gt.config.json 文件和运行时初始化，在 React 生态中配置 General Translation。gt.config.json 的 API 参考。 --- General Translation 需要在两个位置进行配置：一个是 `gt.config.json` 文件，用于保存与 [CLI](/docs/cli/reference/config) 共用的区域设置和文件配置；另一个是运行时 setup 步骤，用于在 first render 之前加载该配置。`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：初始化库、加载当前生效的区域设置对应的翻译，并使用 [``](/docs/react/reference/components/gt-provider) 包裹组件树。 * **初始化**：对于 服务器端渲染 的 setup，使用 [`initializeGT`](#initialize)。单页应用则使用 [`initializeGTSPA`](#initialize-spa)，它还会从 cookie 和浏览器中解析当前生效的区域设置。 * **加载翻译**：使用 [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) 加载当前生效的区域设置对应的翻译。 * **提供**：使用 [``](/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` | 否 | — | 这两个函数都接受以下字段。它们使用相同的选项，区别在于只有 `initializeGTSPA` 会执行浏览器区域设置检测。 | Option | Description | Type | Optional | Default | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ----------------- | | `defaultLocale` | 用于翻译的源区域设置。 | `string` | 是 | `en` | | `locales` | 支持的目标 locales。 | `string[]` | 是 | `[defaultLocale]` | | `locale` | 显式指定初始区域设置。设置后将跳过检测。 | `string` | 是 | 已检测 | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | 返回某个区域设置对应翻译内容的加载器。文档：[`loadTranslations`](/docs/react/reference/functions/load-translations)。 | `(locale: string) => Promise` | 是 | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | 返回某个区域设置对应 dictionary 的加载器。文档：[`loadDictionary`](/docs/react/reference/functions/load-dictionary)。 | `(locale: string) => Promise` | 是 | — | | `dictionary` | 内联 dictionary，可作为 `loadDictionary` 的替代方案。 | `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` | 是 | — | | `region` | 用于区域感知格式化的初始区域代码。 | `string` | 是 | — | | `enableI18n` | 是否启用内容翻译。为 `false` 时，将渲染源区域设置。 | `boolean` | 是 | `true` | | `htmlTagOptions` | 是否在区域设置变更时同步 `` 的 `lang` 和 `dir` 属性。 | `object` | 是 | — | ### `initializeGT` [#initialize] **类型** `(config) => void` · **必填** 在不进行浏览器区域设置检测的情况下初始化配置和翻译缓存。请在服务器端渲染的 setup 中使用它，此时框架会提供请求的区域设置和翻译内容。 ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **类型** `(config) => Promise` · **必填** 在单页应用中初始化 `gt-react`。请在首次渲染前调用一次。它会创建翻译缓存，根据 cookie 和浏览器确定当前生效的区域设置，并预加载翻译。仅可在浏览器入口中使用。 ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` 由于它会从环境中确定区域设置，`initializeGTSPA` 会返回一个 Promise——请在渲染前先 `await` 它。使用 `htmlTagOptions` 来控制当区域设置变化时，`` 元素的 `lang` 和 `dir` 属性是否更新： ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // 默认值：true updateHtmlDirTag: true, // 默认值：true }, }); ``` ## `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[]` | 是 | — | | [`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` | 是 | — | | [`_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']`。 ### `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)。 ### `_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 ( {children} ); } ```