几分钟内让你的 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 钩子。

在根 App 组件中添加 GTProvider：

import { GTProvider } from 'gt-react';

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

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

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

为你的项目自定义 locales。有关可选项，请参见受支持的 locales。

环境变量

在开发环境中启用热重载，请将以下内容添加到你的环境文件：

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. 从 dash.generaltranslation.com 获取生产环境 API key。

   生产环境密钥以 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> 等处理动态内容