GTProvider
<GTProvider> 组件 API 参考
概览
<GTProvider> 组件为其 children 提供 General Translation（GT）上下文，使其能够访问已翻译的内容。
在你的应用中进行任何客户端翻译都必须使用该组件。
何时使用
- 将整个应用包裹在
<GTProvider>中，以在客户端启用翻译。 - 使用 dictionaries 时，可选地指定一个
id，以限制发送到客户端的字典数据，从而优化大型字典的性能。 <GTProvider>组件同时用于 内联<T>和 dictionaries。
参考资料
Props
Prop
Type
描述
| Prop | 描述 |
|---|---|
children | 任何需要在客户端进行翻译或访问翻译信息的组件，或此类组件的父组件。应包括使用 <T>、useGT 或其他翻译工具的任何组件。 |
projectId? | 使用 General Translation 云服务所需的项目 ID。 |
id? | 限制发送到客户端数据所用的嵌套字典 ID。对拥有大量字典的大型项目非常有用。 |
dictionary? | 项目的翻译字典。 |
locales? | 项目批准的 locales 列表。 |
defaultLocale? | 在未找到其他 locale 时使用的默认 locale。 |
locale? | 当前的 locale（如果已设置）。 |
cacheUrl? | 用于获取翻译的缓存服务 URL。 |
runtimeUrl? | 用于获取翻译的运行时服务 URL。 |
renderSettings? | 翻译渲染设置。 |
_versionId? | 用于获取翻译的版本 ID。 |
devApiKey? | 开发环境的 API key。 |
metadata? | 传递给上下文的其他元数据。 |
返回值
包含传递给该组件的 children 的 React.JSX.Element | undefined。
示例
基本用法
将你的应用包裹在 <GTProvider> 中，为应用添加翻译功能。
别忘了添加支持的 locales 列表以启用翻译。
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 钩子进行访问。
import dictionary from "./dictionary.js";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
<App />
</GTProvider>
</StrictMode>
);如需了解更多关于使用 dictionaries 的信息，请查看此指南。
添加配置
如果你不想直接向 <GTProvider> 组件传递 props，可以创建一个配置文件并将其传给该组件。
它还可与 gtx-cli translate 命令 无缝集成，因此无需再以参数形式手动指定诸如 locale 等配置。
{
"projectId": "your-project-id",
"locales": ["es", "fr"],
"defaultLocale": "en-US",
"_versionId": "translation-version-id" // 允许回滚到先前的翻译（由 CLI 自动生成）
}你只需将它传递给 <GTProvider> 组件即可。
import config from "../gt.config.json";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider {...config}> // [!code highlight]
<App />
</GTProvider>
</StrictMode>
);自定义翻译加载器
你可以使用 loadTranslations 属性从自定义来源加载翻译。
当需要从其他来源（例如自定义 API）加载翻译时，这会很有用。
import loadTranslations from "./loadTranslations";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> // [!code 高亮]
<App />
</GTProvider>
</StrictMode>
);渲染设置
渲染设置用于控制翻译的加载行为。
包含两个字段：timeout 和 method。
timeout指在显示后备内容前等待翻译加载的毫秒数（默认：8000ms）。method指用于加载翻译的方式（"skeleton"、"replace"或"default"）。
<GTProvider renderSettings={{ method: "skeleton", timeout: 1000 }}>
<App />
</GTProvider>每个渲染设置对应不同的加载行为：
"skeleton" 会在翻译加载完成前返回 null。
"replace" 会在翻译加载完成前返回 fallback 内容。
"default" 会在翻译加载完成前返回 null，除非 fallback locale 与当前 locale 的语言相同（例如 en-US 和 en-GB）。
在这种情况下，它会立即返回 fallback 内容，直到翻译加载完成。
注意事项
后续步骤
- 进一步了解用于翻译文本和组件的
<T>组件。
本指南如何?