# General Translation React SDKs (gt-react, gt-next, gt-react-native): React 快速入门
URL: https://generaltranslation.com/zh/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在 10 分钟内，使用 General Translation 为服务器端渲染 React 应用添加多种语言。

完成本指南后，你的服务器端渲染 React 应用就能以多种语言显示内容，并提供一个可供用户切换语言的语言切换器。

**前提条件：**

* 一个服务器端渲染的 React 应用 (React Router 或自定义 SSR setup)
* Node.js 18+

<Callout type="info">
  **注意：** 如果你的应用完全通过 Vite 在浏览器中渲染，请改看 [React SPA 快速入门](/docs/react/react-spa-quickstart)。该指南会完全跳过 provider。
</Callout>

## 快速入门 [#quickstart]

### 1. 安装依赖包

`gt-react` 是为应用提供翻译功能的库。`gt` 是用于为 Production 准备翻译的 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`](/docs/react/reference/functions/load-translations) 函数 (步骤 3) 中的导入路径一致。

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

创建一个 [`loadTranslations`](/docs/react/reference/functions/load-translations) 函数，用来加载某个区域设置对应的翻译文件。在服务器端，它会在渲染时运行；运行 [`npx gt translate`](/docs/cli/reference/commands/translate) 时，CLI 会生成这些文件：

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

### 4. 初始化库

在一个会同时在服务器端和客户端加载的文件中，于模块作用域调用 **[`initializeGT`](/docs/react/reference/config#initialize)**——最合适的位置通常是你的 root 路由或布局。它只会注册一次你的配置和翻译加载器；该配置在应用的整个生命周期内都不可更改：

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

initializeGT({
  defaultLocale: gtConfig.defaultLocale,
  locales: gtConfig.locales,
  loadTranslations,
});
```

### 5. 在服务器端加载翻译

在 root 路由的加载器 (或等效的服务器端 handler) 中，解析请求的区域设置，并使用 **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** 获取翻译快照，然后将两者传给 **[`<GTProvider>`](/docs/react/reference/components/gt-provider)**：

```tsx title="src/routes/root.tsx"
import {
  GTProvider,
  getTranslationsSnapshot,
  parseLocale,
} from 'gt-react';

// 在路由加载器中（具体 API 取决于你所使用的框架）
export async function loader({ request }) {
  const locale = parseLocale(request); // [!code highlight]
  return {
    locale,
    translations: await getTranslationsSnapshot(locale), // [!code highlight]
  };
}

export default function Root({ children }) {
  const { locale, translations } = useLoaderData();
  return (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

### 6. 标记需要翻译的内容

用 **[`<T>`](/docs/react/reference/components/t)** 组件包裹任何你想要翻译的文本。[`<T>`](/docs/react/reference/components/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>
  );
}
```

对于普通文本字符串 (例如 `placeholder` 属性或 `aria-label` 的值) ，请使用 **[`useGT`](/docs/react/reference/hooks/use-gt)** 钩子：

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

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```

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

添加一个 **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)**，让用户可以切换语言：

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

export default function Header() {
  return <LocaleSelector />;
}
```

当用户选择一种语言时，`gt-react` 会将该选择保存在 `generaltranslation.locale` cookie 中，并重新加载页面，以便服务器以新的区域设置重新渲染所有内容。

### 8. 设置环境变量 (可选) 

按需开发翻译通过本地开发服务器在浏览器中运行。请使用具备运行时翻译权限的[项目 API Key](/docs/platform/dashboard/reference/api-keys#create-project-keys)。完全访问权限的密钥同样可用，但为降低风险，我们建议选择 **Custom** 权限并仅启用 **Runtime translation**。请仅在本地开发时通过框架的公开环境变量暴露该密钥和项目 ID。

在 Vite 中，`gt-react` 会自动读取以下变量：

```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="gtx-api-your-runtime-key"
```

对于其他框架，请遵循其客户端环境变量的命名约定，并将暴露出的值传递给 [`initializeGT`](/docs/react/reference/config#initialize)。

`VITE_GT_DEV_API_KEY` 配置项用于启用开发环境热重载，其值为以 `gtx-api-` 开头的受限项目密钥。

<Callout type="warn">
  **警告：** 切勿在已部署的浏览器或移动应用包中包含任何 API Key，即使是仅在运行时使用的密钥也不行。请在生产构建中排除 `VITE_GT_DEV_API_KEY`。
</Callout>

### 9. 部署到生产环境

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

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

在你的托管服务商中设置 **生产环境** 变量：

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

<Callout type="warn">
  **警告：** 请为 CLI 使用单独的项目密钥，并授予 **Files &gt; Write** 和 **Translation queue &gt; Enabled** 权限。切勿公开暴露 `GT_API_KEY`。
</Callout>

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

## 故障排查 [#troubleshooting]

<Accordions>
  <Accordion title="使用下拉菜单时语言没有切换">
    确认浏览器 cookie 已启用，所选区域设置出现在 `gt.config.json` 中，并且选择器在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 下渲染。如果你提供了自定义 [`_reload`](/docs/react/reference/components/gt-provider#reload) 回调，请验证它会在选择后重新加载或导航。
  </Accordion>

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

  <Accordion title="某些翻译不准确">
    含义不明确的文本可能会导致翻译不准确。例如，“apple” 既可能指水果，也可能指公司。添加 `context` prop 可帮助模型判断含义：

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

    [`<T>`](/docs/react/reference/components/t) 通过 prop 接收 `context`。调用 [`useGT()`](/docs/react/reference/hooks/use-gt) 时，可通过 `$context` 选项传入同样的消歧字符串。
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.