# General Translation React SDKs (gt-react, gt-next, gt-react-native): TanStack Start 快速入门
URL: https://generaltranslation.com/zh/docs/react/tanstack-start-quickstart.mdx
---
title: TanStack Start 快速入门
description: 使用 gt-tanstack-start 将 General Translation 添加到 TanStack Start 应用，并完成首次内容翻译。
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

`gt-tanstack-start` 可为 TanStack Start 应用添加自动国际化支持。你需要在路由器入口文件中初始化 General Translation，解析请求的区域设置，并通过路由加载器为 [`GTProvider`](/docs/react/reference/components/gt-provider) 提供水合数据。

本快速入门适用于 TanStack Start 应用。对于普通的 React SPA，请参阅 [React 快速入门](/docs/react/react-quickstart)。

<Callout type="warn">
  **警告：** `gt-tanstack-start` 仍处于实验阶段，可能会引入破坏性变更。目前尚不建议在生产环境中使用。
</Callout>

## 快速入门 [#quickstart]

安装这些包，创建配置文件和翻译加载器，添加请求中间件，初始化路由器，配置 root 路由，标记需要翻译的内容，并生成翻译。

### 1. 安装 `gt-tanstack-start`

安装 `gt-tanstack-start` 和 `gt-react` 作为依赖，并将 [`gt` CLI](/docs/cli/quickstart) 安装为开发依赖。还需要直接安装 `gt-react`，这样 CLI 才能在你的 source 中检测到 [`<T>`](/docs/react/reference/components/t) 组件。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-tanstack-start gt-react && npm install gt --save-dev
    ```
  </Tab>

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

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

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

`gt-tanstack-start` 仅支持 ESM。请使用 `import` 语法，而不要使用 CommonJS 的 `require()`。

### 2. 创建 `gt.config.json`

在项目根目录中创建一个 `gt.config.json` 文件。它用于声明源语言、目标区域设置，以及翻译文件的输出位置。

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

* `defaultLocale` — 你的应用所使用的源语言。
* `locales` — 要翻译到哪些语言。从[受支持的区域设置](/docs/platform/dashboard/reference/supported-locales)中选择。
* `files.gt.output` — CLI 写入翻译文件的位置。请将它们保存在 `src/` 下，这样 Vite 才能导入它们；位于 `public/` 中的文件将无法解析。

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

创建一个 `loadTranslations.ts` 文件，用于在运行时导入对应区域设置的翻译文件。

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./src/_gt/${locale}.json`);
  return translations.default;
}
```

### 4. 添加请求中间件

创建 `src/start.ts`，并将 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) 注册为全局请求中间件。定义自定义的 start 实例时，请保留 TanStack Start&#39;s CSRF 中间件。

```ts title="src/start.ts"
import { createCsrfMiddleware, createStart } from '@tanstack/react-start';
import { gtMiddleware } from 'gt-tanstack-start';

const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware, gtMiddleware],
}));
```

该中间件会将区域设置、地区和国际化设置限定在每个请求范围内，以便服务器函数使用正确的语言。请先在下一步完成初始化，再启动开发服务器。

### 5. 初始化 General Translation 并设置 root 路由

在 `src/router.tsx` 中，在模块级别调用一次 [`initializeGT`](/docs/react/tanstack-start/setup#initialize)。将导入和初始化器添加到现有的路由器文件中：

```tsx title="src/router.tsx"
import { initializeGT } from 'gt-tanstack-start';
import gtConfig from '../gt.config.json';
import loadTranslations from '../loadTranslations';

initializeGT({ ...gtConfig, loadTranslations });
```

然后用 [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) 解析区域设置，并在 `src/routes/__root.tsx` 加载器中加载翻译快照。将 `locale` 和 `translations` 传给 [`GTProvider`](/docs/react/reference/components/gt-provider)。

```tsx title="src/routes/__root.tsx"
import {
  HeadContent,
  Scripts,
  createRootRoute,
} from '@tanstack/react-router';
import {
  GTProvider,
  getLocale,
  getTranslationsSnapshot,
  LocaleSelector,
} from 'gt-tanstack-start';

export const Route = createRootRoute({
  loader: async () => {
    const locale = getLocale();
    return {
      locale,
      translations: await getTranslationsSnapshot(locale),
    };
  },
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  const { locale, translations } = Route.useLoaderData();
  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <GTProvider locale={locale} translations={translations}>
          <LocaleSelector />
          {children}
        </GTProvider>
        <Scripts />
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) 在服务器端会读取请求作用域的区域设置，在客户端会读取已初始化的浏览器区域设置。[`GTProvider`](/docs/react/reference/components/gt-provider) 同时需要 `locale` 和 `translations`。

<Callout type="warn">
  &#42;&#42;警告：&#42;&#42;这些翻译文件 (`src/_gt/[locale].json`) 在创建之前并不存在。默认区域设置仍然会渲染，但在语言切换器中选择目标区域设置时，在这些文件存在之前会返回 HTTP 500。请先运行 [`npx gt generate`](/docs/cli/reference/commands/generate) (不需要 API Key) 或 [`npx gt translate`](/docs/cli/reference/commands/translate) (使用凭据) 来创建这些文件。
</Callout>

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

将 JSX 包裹在 [`<T>`](/docs/react/reference/components/t) 组件中，即可原地翻译。请从 `gt-react` 导入 [`<T>`](/docs/react/reference/components/t) 和 [`useGT`](/docs/react/reference/hooks/use-gt)，这样 CLI 在扫描源代码时就能识别它们。

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { T, useGT } from 'gt-react';

export const Route = createFileRoute('/')({ component: Home });

function Home() {
  const gt = useGT();

  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email input field')} />
    </main>
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) 会直接返回翻译函数，因此请这样调用：`const gt = useGT();`。

### 7. 生成翻译

运行 CLI，通过 General Translation API 为你的项目生成翻译。

```bash
npx gt translate
```

将该命令添加到你的构建脚本中，以确保生产环境构建始终使用最新的翻译：

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

<Callout type="info">
  **注意：**[`npx gt translate`](/docs/cli/reference/commands/translate) 需要项目 ID 和 production API key，并将它们在环境中设置为 `GT_PROJECT_ID` 和 `GT_API_KEY`。运行 [`npx gt auth`](/docs/cli/reference/commands/auth) 或访问[仪表板](/docs/platform/dashboard/get-started)即可获取。
</Callout>
## Next steps

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