# gt-react: General Translation React SDK: React 快速入门
URL: https://generaltranslation.com/zh/docs/react.mdx
---
title: React 快速入门
description: 在 10 分钟内为你的 React 应用添加多语言支持
---

完成本指南后，你的 React 应用将能够以多种语言显示内容，并提供用户可操作的语言切换器。

**前提条件：**

* 一个 React 应用 (Vite、Create React App 或类似工具) 
* Node.js 18+

<Callout type="info">
  **想自动完成设置？** 运行 `npx gt@latest`，通过 [设置向导](/docs/cli/init) 完成全部配置。本指南介绍的是手动设置。
</Callout>

***

## 第 1 步：安装软件包

`gt-react` 是为应用提供翻译功能的库。`gt` 是用于为生产环境准备翻译内容的 CLI 工具。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## 第 2 步：创建翻译配置文件

在项目根目录下创建一个 **`gt.config.json`** 文件。该文件用于告诉库你支持哪些语言：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — 你的应用所使用的语言 (即源语言) 。
* **`locales`** — 你要翻译成的目标语言。可从[支持的区域设置列表](/docs/platform/supported-locales)中任选。
* **`files`** — 指定 CLI 将翻译文件保存到哪里。`output` 路径应与 `loadTranslations` 函数 (步骤 3) 中的导入路径保持一致。

<Callout type="info">
  **使用 Vite？** 请将输出路径设置为 `"src/_gt/[locale].json"`，而不是 `"public/_gt/[locale].json"`。Vite 会将翻译文件作为模块导入，因此这些文件应放在 `src/` 中，而不是 `public/`。
</Callout>

***

## 第 3 步：创建翻译加载器

`gt-react` 完全在客户端运行，因此需要一个函数在 runtime 加载翻译文件。创建一个 `loadTranslations` 文件：

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for ${locale}`);
    return {};
  }
}
```

此函数会从你的 `public/_gt/` 目录中加载 JSON 翻译文件。运行 `npx gt translate` 时，CLI 会生成这些文件。

<Accordions>
  <Accordion title="在使用 Vite 吗？">
    由于 Vite 的翻译文件位于 `src/_gt/` 中 (见第 2 步) ，请更新导入路径：

    ```ts title="src/loadTranslations.ts"
    export default async function loadTranslations(locale: string) {
      try {
        const translations = await import(`./_gt/${locale}.json`);
        return translations.default;
      } catch (error) {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }
    ```
  </Accordion>

  <Accordion title="在使用 Create React App 吗？">
    CRA 的 webpack 配置会阻止从 `src/` 之外动态调用 `import()`。请改用 `fetch()`：

    ```ts title="src/loadTranslations.ts"
    export default async function loadTranslations(locale: string) {
      try {
        const response = await fetch(`${process.env.PUBLIC_URL}/_gt/${locale}.json`);
        if (!response.ok) throw new Error('Not found');
        return await response.json();
      } catch (error) {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }
    ```
  </Accordion>
</Accordions>

***

## 第 4 步：将 GTProvider 添加到应用中

**`GTProvider`** 组件可让整个应用访问翻译内容。请在根层级包裹应用：

```tsx title="src/App.tsx"
import { GTProvider } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations}>
      {/* 您的应用内容 */}
    </GTProvider>
  );
}
```

`GTProvider` 通过 props 接收你的配置和翻译加载器。它负责管理区域设置状态，并让所有子组件都能访问翻译内容。

<Accordions>
  <Accordion title="使用 Create React App？">
    CRA 只允许导入 `src/` 内的文件，因此 `import gtConfig from '../gt.config.json'` 会失败。你可以将 `gt.config.json` 复制到 `src/` 中，或者直接内联配置：

    ```tsx title="src/App.tsx"
    import { GTProvider } from 'gt-react';
    import loadTranslations from './loadTranslations';

    export default function App() {
      return (
        <GTProvider
          config={{
            defaultLocale: 'en',
            locales: ['es', 'fr', 'ja'],
          }}
          loadTranslations={loadTranslations}
        >
          {/* 您的应用内容 */}
        </GTProvider>
      );
    }
    ```
  </Accordion>
</Accordions>

***


## 第 5 步：标记要翻译的内容

现在，将所有需要翻译的文本都用 **`<T>`** 组件包裹起来。`<T>` 表示“translate”：

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

你可以在 `<T>` 中包裹任意多或任意少的 JSX。里面的所有内容——文本、嵌套元素，甚至格式——都会作为一个整体进行翻译。

***


## 第 6 步：添加语言切换器

加入 **`<LocaleSelector>`**，让用户可以切换语言：

```tsx title="src/components/Welcome.tsx"
import { T, LocaleSelector } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>欢迎使用我的应用</h1>
        <p>此内容将自动翻译。</p>
      </T>
    </main>
  );
}
```

`LocaleSelector` 会渲染一个下拉菜单，其中列出了 `gt.config.json` 中的语言。

***


## 第 7 步：设置环境变量 (可选)

如果你想在开发环境中看到翻译结果，需要使用 General Translation 提供的 API 密钥。它们会启用**按需翻译**——这样你在开发过程中，应用就能实时翻译内容。

根据你使用的 bundler，使用正确的前缀创建 **`.env.local`** 文件：

<Tabs items={["Vite", "Create React App"]}>
  <Tab value="Vite">
    ```bash title=".env.local"
    VITE_GT_API_KEY="your-dev-api-key"
    VITE_GT_PROJECT_ID="your-project-id"
    ```
  </Tab>

  <Tab value="Create React App">
    ```bash title=".env.local"
    REACT_APP_GT_API_KEY="your-dev-api-key"
    REACT_APP_GT_PROJECT_ID="your-project-id"
    ```
  </Tab>
</Tabs>

前往 [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 免费获取密钥，或运行：

```bash
npx gt auth
```

<Callout type="warn">
  在开发环境中，请使用以 `gtx-dev-` 开头的密钥。生产密钥 (`gtx-api-`) 仅限用于 CI/CD。

  Vite 和 CRA 这类客户端打包工具要求环境变量使用特定前缀 (`VITE_` 或 `REACT_APP_`) 才能暴露给浏览器。未加前缀的 `GT_API_KEY` 在运行时不可用。
</Callout>

<Accordions>
  <Accordion title="不使用 API 密钥也能使用 gt-react 吗？">
    可以。不使用 API 密钥时，`gt-react` 会像标准 i18n 库一样工作。你将无法在开发环境中使用按需翻译，但仍然可以：

    * 手动提供自己的翻译文件
    * 使用所有组件 (`<T>`、`<Var>`、`LocaleSelector` 等)
    * 运行 `npx gt generate` 生成翻译文件模板，然后自行翻译
  </Accordion>
</Accordions>

***

## 第 8 步：查看效果

启动开发服务器：

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

打开应用，并使用语言下拉菜单切换语言。你应该能看到内容已被翻译。

<Callout type="info">
  在开发环境中，翻译按需进行——首次切换到某种新语言时，你可能会看到短暂的加载状态。在生产环境中，翻译会预先生成，并可立即加载。
</Callout>

***

## 第 9 步：翻译字符串 (不只是 JSX) 

对于普通字符串——例如 `placeholder` 属性、`aria-label` 值或 `alt` 文本——请使用 **`useGT`** 钩子：

```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';

export default function ContactForm() {
  const gt = useGT();

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

***


## 第 10 步：部署到生产环境

在生产环境中，翻译会在构建阶段预先生成 (不会发起实时 API 调用) 。将 `translate` 命令添加到构建脚本中：

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

在托管服务提供商 (Vercel、Netlify 等) 中设置 **production** 环境变量：

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

<Callout type="warn">
  生产密钥以 `gtx-api-` 开头 (不是 `gtx-dev-`) 。请前往 [dash.generaltranslation.com](https://dash.generaltranslation.com) 获取。切勿公开暴露你的 `GT_API_KEY`。
</Callout>

就是这样——你的应用现在已经是多语言应用了。🎉

***


## 故障排查

<Accordions>
  <Accordion title="使用下拉菜单时，语言没有切换">
    `gt-react` 会将用户的语言偏好存储在名为 `generaltranslation.locale` 的 Cookie 中。如果你之前测试过其他语言，这个 Cookie 可能会覆盖你的当前选择。请清除 Cookie 后重试。

    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
  </Accordion>

  <Accordion title="开发环境中的翻译速度较慢">
    这是正常现象。在开发环境中，翻译是按需进行的 (你的内容会通过 API 实时翻译) 。**生产环境中不会有这种延迟**——所有翻译都会由 `npx gt translate` 预先生成。
  </Accordion>

  <Accordion title="某些翻译不够准确">
    有歧义的文本可能会导致翻译不准确。例如，“apple” 既可能指水果，也可能指公司。添加 `context` 属性可以帮助消除歧义：

    ```jsx
    <T context="the technology company">Apple</T>
    ```

    `<T>` 和 `useGT()` 都支持 `context` 选项。
  </Accordion>
</Accordions>

***

## 下一步

* [**`<T>` 组件指南**](/docs/react/guides/t) — 了解变量、复数形式和高级翻译用法
* [**字符串翻译指南**](/docs/react/guides/strings) — 深入了解 `useGT`
* [**变量组件**](/docs/react/guides/variables) — 使用 `<Var>`、`<Num>`、`<Currency>` 和 `<DateTime>` 处理动态内容
* [**复数变化**](/docs/react/api/components/plural) — 使用 `<Plural>` 组件处理复数形式
* [**部署到生产环境**](/docs/react/tutorials/quickdeploy) — CI/CD 设置、缓存和性能优化
* [**共享字符串**](/docs/react/guides/shared-strings) — 使用 `msg()` 翻译数组、配置对象和共享数据中的文本