快速开始
使用 gt-react 轻松实现 React 应用的国际化
概述
本快速入门指南将带你了解如何使用 gt-react 对你的 React 应用进行国际化。
在本指南结束时，你将拥有一个完全国际化的 React 应用。
在本指南中，我们将涵盖以下内容：
安装
配置
使用
测试你的应用
部署
前置条件
- 一个使用受支持框架（Next.js、Vite 等）的 React 项目
- 基本的 React 和 JavaScript 知识
安装
安装 gt-react 和 gtx-cli 包：
npm i gt-react
npm i --save-dev gtx-cliyarn add gt-react
yarn add --dev gtx-clibun add gt-react
bun add --dev gtx-clipnpm add gt-react
pnpm add --save-dev gtx-cli自动设置： 我们有一个实验性的设置向导，可以帮助您使用 gt-react 设置项目。
通过运行 npx gtx-cli@latest 来试用。您仍需要手动国际化字符串，但它会帮助您开始。
查看设置向导参考指南了解更多信息。
或者，如果您希望您的 AI 工具（如 Claude Code、Cursor 或 Windsurf）自动设置您的项目， 您可以使用我们的 mcp server。
配置
GTProvider
gt-react 的核心是 GTProvider 组件。
它负责：
- 管理用户当前的语言环境
- 为你的应用程序提供相关的翻译
- 为 hooks 提供访问翻译的上下文
- 为 hooks 提供更改用户语言环境的上下文
首先，将 GTProvider 组件添加到你的应用程序中。它应尽可能放置在组件树的顶层。
import { GTProvider } from 'gt-react';
export default function App() {
return (
<GTProvider>
<App />
</GTProvider>
);
}接下来，在你的项目根目录下创建一个 gt.config.json 文件。
该文件用于同时配置 gtx-cli 工具和 gt-react 库。
{
"defaultLocale": "en",
"locales": ["fr", "es"]
}你应该根据你的项目自定义 defaultLocale 和 locales。更多信息请参阅支持的语言环境列表。
最后，将 gt.config.json 文件展开到 provider 的 props 中。
import gtConfig from './gt.config.json';
<GTProvider {...gtConfig}>
<App />
</GTProvider>展开 gt.config.json 文件可以让配置在你的应用和 CLI 工具中保持一致。
或者，你也可以在 GTProvider 组件中单独指定每个 prop。
<GTProvider
defaultLocale="en"
locales={["fr", "es"]}
>环境变量
请设置以下环境变量：
VITE_GT_API_KEY="" # 你的 General Translation 开发者 API 密钥
VITE_GT_PROJECT_ID="" # 你的 General Translation 项目 IDGATSBY_GT_API_KEY="" # 你的 General Translation 开发者 API 密钥
GATSBY_GT_PROJECT_ID="" # 你的 General Translation 项目 IDREDWOOD_ENV_GT_API_KEY="" # 你的 General Translation 开发者 API 密钥
REDWOOD_ENV_PROJECT_ID="" # 你的 General Translation 项目 IDNEXT_PUBLIC_GT_API_KEY="" # 你的 General Translation 开发者 API 密钥
NEXT_PUBLIC_GT_PROJECT_ID="" # 你的 General Translation 项目 IDREACT_APP_GT_API_KEY="" # 你的 General Translation 开发者 API 密钥
REACT_APP_GT_PROJECT_ID="" # 你的 General Translation 项目 ID许多 React 框架都有各自独特的方式将环境变量导出到客户端。
在开发环境中，GT_API_KEY 和 GT_PROJECT_ID 都需要导出到客户端。
我们目前已支持部分库， 如果你的框架未在列表中，请在我们的 GitHub 仓库 提交 issue 告诉我们。
请确保你的 API 密钥变量只在开发环境中设置！不要在生产环境中设置。
你可以通过创建一个 General Translation 账户 免费获取 API 密钥和项目 ID。
创建账户后，前往 开发 API 密钥 页面获取你的开发 API 密钥和项目 ID。
另外，你也可以使用 CLI 工具命令 npx gtx-cli auth 为你的项目生成 API 密钥和项目 ID，并保存到 .env.local 文件中。
用法
太好了！如果你已经按照上面的步骤操作，你的 React 项目现在已经设置好可以使用 gt-react 了。
接下来的步骤是对你的内容进行国际化。 在这里，我们将简要介绍在你的应用中翻译内容的不同方式。
<T> 组件
<T> 组件是你在应用中翻译 JSX 内容的主要组件。
要使用它，只需将你想要翻译的 JSX 包裹在 <T> 组件中即可。
import { T } from 'gt-react';
<T>
<div>Your content</div>
</T>如果你有动态内容，你需要使用 变量组件 来传递动态值。
import { T, Var } from 'gt-react';
<T>
<div>Hello, <Var>{name}</Var>!</div>
</T>更多信息请参见 翻译 JSX 指南。
useGT Hook
useGT hook 是一个 React hook，它返回一个可以用来翻译字符串的函数。
import { useGT } from 'gt-react';
const translate = useGT();
translate('Hello, world!');更多信息请参见 翻译字符串 指南。
利用热重载翻译功能将有助于你的应用国际化。
要启用此功能，请确保你在开发环境中设置了 GT_API_KEY 和 GT_PROJECT_ID 环境变量。
测试你的应用
恭喜你！🥳 如果你已经按照上面的步骤操作，你的应用现在已经支持多语言了！让我们来看看它的实际效果。
在不同语言下查看你的应用
将 <LocaleSelector> 组件添加到你的应用中。
这样你就可以为你的应用选择不同的语言了。
提示： 你也可以跳过这一步，直接在浏览器设置中更改你的语言。
以开发模式启动你的 React 应用。
npm run dev yarn run dev bun run dev pnpm run dev 在你喜欢的浏览器中打开你的应用（通常地址为 http://localhost:3000）。
故障排查
部署
太好了！如果你对你的翻译和应用的功能感到满意，现在可以部署你的应用程序了。
gt-react 在生产环境下的行为与开发环境略有不同。具体来说，生产环境下不会在运行时进行翻译。
这意味着你需要在部署应用程序之前，在构建过程中完成内容的翻译。
幸运的是，gtx-cli 工具有一个 translate 命令，可以用来自动翻译你的内容。
首先，你需要从 General Translation 平台 获取一个生产环境 API 密钥。
请注意，这个密钥与你的开发环境 API 密钥不同，并且以 gtx-api- 开头，而不是 gtx-dev-。
你可以在这里了解开发环境和生产环境密钥的区别。
将这个环境变量添加到你的 CI/CD 流水线中。
GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>请确保 GT_API_KEY 不要 以 NEXT_PUBLIC_ 或 VITE_ 为前缀，这取决于你的框架！
如果加了前缀，你的 API 密钥有可能会被公开暴露。
运行 translate 命令来翻译你的内容。
npx gtx-cli translate你可以通过 gt.config.json 文件配置 translate 命令的行为。
更多信息请参阅 CLI 工具 参考指南。
将 translate 命令添加到你的构建流程中。
{
"scripts": {
"build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
}
}总结
- 在本指南中，我们介绍了如何使用
gt-react设置你的 React 项目 - 我们简要介绍了在应用中翻译内容的不同方法。
- 我们还讲解了在完成内容国际化后，如何部署你的应用。
下一步
这份指南怎么样？