让你的 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 钩子。

将 GTProvider 添加到应用的根组件中：

import { GTProvider } from 'gt-react';

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

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

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

为你的项目自定义 locale。查看支持的 locale以了解可用的 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 密钥，或运行：

npx gtx-cli auth

使用方法

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

含有 <T> 的 JSX 内容

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

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> 添加一个 locale 选择下拉菜单：

   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，并通过 locale 选择下拉菜单切换语言。

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

疑难解答

部署

在生产环境中，你需要预先翻译内容，因为运行时翻译已禁用（<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> 等处理动态内容