# General Translation React SDKs (gt-react, gt-next): React SPA 快速入门
URL: https://generaltranslation.com/zh/docs/react/react-spa-quickstart.mdx
---

title: React SPA 快速入门
description: 使用 General Translation，只需不到 10 分钟即可为单页 React 应用添加多语言支持。
related:
  links:
    - /docs/react/guides/developing-spa-translations
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/managing-locales
    - /docs/react/guides/storing-translations

---

# React SPA 快速入门

阅读完本指南后，你的单页 React 应用将能够以多种语言显示内容，并提供一个可供用户切换语言的语言切换器。

在单页应用中，`gt-react` 完全在浏览器中运行——你只需在启动时使用 `initializeGTSPA()` 初始化一次，无需 provider 组件。

**前提条件：**

* 一个客户端渲染的 React 应用 (Vite、webpack 或类似工具) 
* Node.js 18+

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

<Callout type="info">
  **注意：** 如果你的应用在服务器端渲染，请改为参考 [React 快速入门](/docs/react/react-quickstart)。
</Callout>

## 快速入门 [#quickstart]

### 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": "src/_gt/[locale].json"
    }
  }
}
```

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

<Callout type="info">
  &#42;&#42;文件位置：&#42;&#42;Vite 之类的打包工具会将翻译文件作为模块导入，因此这些文件应放在 `src/` 目录下。
</Callout>

### 3. 创建翻译加载器

在 SPA 中，`gt-react` 需要一个函数在浏览器运行时加载翻译文件。创建一个 `loadTranslations` 文件：

```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 {};
  }
}
```

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

### 4. 初始化库

在启动时、应用渲染前调用一次 **`initializeGTSPA`**。它会接收你的配置和翻译加载器，确定用户的区域设置，并加载对应的翻译内容。

最稳妥的做法是使用一个小型入口模块，先初始化 GT，再加载应用的其余部分。这样你就能在模块级别翻译内容。

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({
  defaultLocale: gtConfig.defaultLocale,
  locales: gtConfig.locales,
  loadTranslations,
});

await import('./main'); // 仅在 GT 就绪后才渲染应用
```

```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

然后更新 `index.html` 中的模块 script 标签，使其指向新的入口：将其 `src` 从 `/src/main.tsx` 改为 `/src/index.ts`。

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

`initializeGTSPA` 只会在启动时运行一次——在应用的整个生命周期内，配置都是不可变的。它完成后，你就可以在任何模块中获取翻译。**你不需要用 provider 包裹应用。**

<Callout type="info">
  &#42;&#42;提示：&#42;&#42;请按照[使用 SPA translations 进行开发](/docs/react/guides/developing-spa-translations)添加 compiler 和开发凭据。
</Callout>

### 5. 标记要翻译的内容

现在，将任何需要翻译的文本用 **`<T>`** 组件包裹起来。`<T>` 表示 &quot;translate&quot;：

```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。里面的所有内容——文本、嵌套元素，甚至格式——都会作为一个整体被翻译。

对于 React 组件外的字符串，请使用 **`t()`**。它可以在模块级别使用，因为 `initializeGTSPA()` 会在应用其余部分加载前先加载翻译：

```ts title="src/navigation.ts"
import { t } from 'gt-react';

export const navigation = [
  { label: t('Home'), href: '/' },
  { label: t('About'), href: '/about' },
];
```

### 6. 添加语言切换器

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

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

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

`LocaleSelector` 会渲染一个下拉菜单，其中会显示来自你的 `gt.config.json` 的语言。

当用户选择一种语言时，`gt-react` 会将该选择保存到 `generaltranslation.locale` cookie 中，并重新加载页面——随后 `initializeGTSPA` 会再次运行，在应用渲染之前加载新区域设置的翻译内容。

### 7. 身份验证并翻译

开始翻译前，请先通过 General Translation 进行身份验证：

```bash
npx gt auth
```

按照提示创建账户或登录。系统提示选择密钥类型时，请选择生产环境密钥。该命令会生成 API Key 和 project ID，然后将它们添加到项目根目录下的 `.env.local`：

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="gtx-api-your-production-key"
```

<Callout type="warn">
  &#42;&#42;请妥善保管你的密钥：&#42;&#42;不要提交 `.env.local`，也不要在浏览器端代码中暴露 `GT_API_KEY`。
</Callout>

然后运行 translate 命令，为每个已配置的区域设置生成翻译文件：

```bash
npx gt translate
```

CLI 会扫描你的应用、翻译其中的内容，并将结果写入 `gt.config.json` 中指定的输出路径。每当 source 内容发生变化时，都可以再次运行它。

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

## 故障排查 [#troubleshooting]

<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="某些翻译不够准确">
    有歧义的文本可能会导致翻译不准确。例如，“apple” 既可能指水果，也可能指公司。添加 `$context` prop 来提供上下文：

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

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

- /docs/react/guides/developing-spa-translations
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations