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

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

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

**前提条件：**

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

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

<Callout type="info">
  **服务器端渲染应用？** 如果你的应用在服务器端渲染，请改为参阅 [React 快速入门](/docs/react)。
</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": "src/_gt/[locale].json"
    }
  }
}
```

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

<Callout type="info">
  **文件位置：** 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` 中的模块脚本标签，让它指向新的入口：将其 `src` 从 `/src/main.tsx` 改为 `/src/index.ts`。

`initializeGTSPA` 只会在启动时运行一次——在应用的整个生命周期内，配置都是不可变的。待它完成后，你的应用中的所有组件和钩子都可以访问翻译。**你不需要用 provider 包裹应用。**

<Callout type="info">
  **想在开发时使用实时翻译？** 请按照 [SPA 开发翻译指南](/docs/react/tutorials/spa-development-translations) 添加 compiler 和开发凭证。
</Callout>

***

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

对于 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
```

按照提示创建账户或登录。系统提示你选择 key type 时，请选择生产环境 key。该命令会生成 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 内容发生变化时，请再次运行它。

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

***

## 故障排查

<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` 属性有助于澄清含义：

    ```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>` 组件处理复数形式
* [**SPA 开发中的翻译**](/docs/react/tutorials/spa-development-translations) — 在开发时实时查看翻译更新
* [**部署到生产环境**](/docs/react/tutorials/quickdeploy) — CI/CD 设置、缓存和性能优化
* [**共享字符串**](/docs/react/guides/shared-strings) — 使用 `msg()` 翻译数组、配置对象和共享数据中的文本