让你的 React 应用在几分钟内完成内容国际化。

前置条件： React、基础 JavaScript 知识

安装

安装 gt-react 和 gtx-cli 包：

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

配置

GTProvider

GTProvider 组件为 React 组件提供翻译上下文。它管理 locale 状态和翻译资源，并启用 useGT 与 useTranslations 这两个 Hook。

将 GTProvider 添加到根 App 组件中：

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <YourAppContent />
    </GTProvider>
  );
}

在项目根目录创建一个 gt.config.json 文件：

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

为你的项目自定义 locales。查看支持的 locales以了解可用 options。

环境变量

将以下内容添加到你的环境配置文件，以启用开发时热重载：

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

在 dash.generaltranslation.com 领取免费的 API Keys，或运行：

npx gtx-cli auth

使用

现在你可以开始对内容进行国际化了。主要有两种方式：

含有 <T> 的 JSX 内容

使用 <T> 组件包裹 JSX 元素以进行翻译：

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>欢迎使用我们的应用程序！</h1>
    </T>
  );
}

对于动态内容，请使用变量组件，如<Var>：

import { T, Var } from 'gt-react';

function Greeting({ user }) {
  return (
    <T>
      <p>你好，<Var>{user.name}</Var>！</p>
    </T>
  );
}

有关更多信息，请参阅《使用 <T> 组件》指南。

使用 useGT 处理纯文本字符串

适用于通过 useGT 钩子处理的属性、标签和纯文本：

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('请输入您的邮箱')}
      aria-label={t('邮箱输入框')}
    />
  );
}

请参阅字符串翻译指南以了解更多信息。

测试你的应用

通过切换语言来测试翻译效果：

1. 添加语言选择下拉菜单，使用 <LocaleSelector>：

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. 启动开发服务器：

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. 访问 localhost:3000，通过语言选择下拉菜单切换语言。

在开发环境中，翻译按需加载（会有短暂的加载时间）。在生产环境中，内容均已预先翻译。

疑难解答

部署

在生产环境中，你需要预先完成内容翻译，因为运行时翻译已被禁用（<Tx> 和 tx 函数除外）。

1. 获取生产环境 API key，前往 dash.generaltranslation.com。

   生产环境密钥以 gtx-api- 开头（区别于开发环境密钥，其以 gtx-dev- 开头）。了解更多环境差异。

2. 添加到 CI/CD 环境：

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   切勿为生产环境密钥添加框架的公共变量前缀（如 VITE_、REACT_APP_ 等）——这些密钥应仅限于服务端使用。

3. 运行 translate 命令以翻译内容：

   npx gtx-cli translate

   你可以通过 gt.config.json 文件配置 translate 命令的行为。

   更多信息请参阅 CLI 工具参考指南。

4. 更新构建脚本，在构建前执行翻译：

   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }

下一步

• <T> 组件指南 - 深入了解 <T> 组件与 JSX 翻译
• 字符串翻译指南 - 使用 useGT 进行字符串翻译
• 变量组件 - 使用 <Var>、<Num> 等处理动态内容