快速开始
使用 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 组件。
它负责：
- 管理用户的当前语言环境
- 为您的应用程序提供相关翻译
- 为访问翻译的钩子提供上下文
- 为更改用户语言环境的钩子提供上下文
首先，将 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 文件展开到提供者的属性中。
import gtConfig from './gt.config.json';
<GTProvider {...gtConfig}>
<App />
</GTProvider>展开 gt.config.json 文件使配置在您的应用程序和 CLI 工具之间保持一致。
或者，您可以在 GTProvider 组件中单独指定每个属性。
<GTProvider
defaultLocale="en"
locales={["fr", "es"]}
>环境变量
设置以下环境变量：
VITE_GT_API_KEY="" # Your General Translation Developer API key
VITE_GT_PROJECT_ID="" # Your General Translation project IDGATSBY_GT_API_KEY="" # Your General Translation Developer API key
GATSBY_GT_PROJECT_ID="" # Your General Translation project IDREDWOOD_ENV_GT_API_KEY="" # Your General Translation Developer API key
REDWOOD_ENV_PROJECT_ID="" # Your General Translation project IDNEXT_PUBLIC_GT_API_KEY="" # Your General Translation Developer API key
NEXT_PUBLIC_GT_PROJECT_ID="" # Your General Translation project IDREACT_APP_GT_API_KEY="" # Your General Translation Developer API key
REACT_APP_GT_PROJECT_ID="" # Your General Translation project ID许多 React 框架都有各自独特的方式将环境变量导出到客户端。
在开发环境中，GT_API_KEY 和 GT_PROJECT_ID 都需要导出到客户端。
到目前为止，我们已经为一些库添加了支持， 但如果您的框架未列出，请通过在我们的 GitHub 仓库中创建问题来告知我们。
确保您的 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 项目 - 我们简要介绍了在应用程序中翻译内容的不同方法。
- 我们还介绍了在国际化内容后如何部署应用程序。
下一步
这份指南怎么样？