# General Translation Knowledge Base: 如何为 TanStack Start 添加 i18n？
URL: https://generaltranslation.com/zh/kb/add-i18n-to-tanstack-start.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: TanStack Start 没有内置 i18n，因此你需要引入一个库，在每个服务端请求中解析区域设置，并在渲染前加载消息。建议使用 Paraglide JS——它是 TanStack 的 i18n 指南推荐的库，由 General Translation 维护——并借助 General Translation 的 CLI 翻译其消息文件。若希望将文案内联写在 JSX 中，则可选用 General Translation 的实验性库 gt-tanstack-start。
Category: 国际化
Last updated: 2026-11-16
Authors: General Translation Team
Published: 2026-10-28

TanStack Start 没有自带 i18n 层，因此你需要自行补齐三样东西：一个以当前语言渲染文本的库、一套在每个服务端请求中解析当前语言的机制，以及译文本身。Start 会先在服务端渲染完整文档，再在浏览器中进行水合，因此两端必须使用相同的区域设置和消息，否则首屏会以错误的语言呈现，或者水合失败。

## Video

The video is narrated in English, with English captions.

[How do I add i18n to TanStack Start?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/v2/kb-add-i18n-to-tanstack-start.mp4) (48秒)

TanStack Start has no built-in i18n, so you add a library that resolves the locale for each server request, usually from a URL prefix or cookie, and loads messages before render. General Translation's experimental gt-tanstack-start also generates the translations from copy written inline in JSX: register gtMiddleware in src/start.ts, wrap copy in <T>, and run npx gt translate.

## TanStack Start 提供了什么，又把什么留给了你

TanStack Start 是“一个由 TanStack Router 驱动的全栈 React 框架”，支持完整文档的服务器端渲染 (SSR) 、流式传输、服务器函数和请求中间件 ([TanStack Start 概览](https://tanstack.com/start/latest/docs/framework/react/overview)) 。其中有几项正是 i18n 初始化设置所依赖的基础：

* **区域设置 URL。** 像 `/{-$locale}/about` 这样的可选路径参数，只需一个路由文件即可匹配 `/about`、`/es/about` 和 `/fr/about`；也可以改用路由器的 `rewrite` 选项来添加和移除区域设置前缀 ([TanStack Router i18n 指南](https://tanstack.com/router/latest/docs/guide/internationalization-i18n)) 。
* **请求中间件。** 在 `src/start.ts` 中通过 `createStart` 注册的中间件会在每个请求之前运行，SSR 和服务器函数也不例外 ([TanStack Start 中间件](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)) 。国际化库正是在这里读取 URL、cookie 或 `Accept-Language` 请求头。
* **加载器与 `head`。** root 路由的加载器可以在渲染前加载当前区域设置的消息，而每个路由的 `head` 负责设置翻译后的 `<title>` 和 meta 标签。

Start 留给你自行处理的部分包括：消息目录及负责查找消息的运行时、区域设置检测以及用于记住用户选择的 cookie、根布局中的 `<html lang>` 属性、复数与数字格式化、`hreflang` 链接，以及译文本身。TanStack 的 i18n 指南对 Paraglide JS 做了深入介绍 (包括 TanStack Start 的 SSR 初始化设置) ，并附有 Intlayer 和 use-intl 的社区指南链接。此外，TanStack CLI 还为新应用提供了 `paraglide` 插件。

## 可选方案

| 库                                                                               | 如何编写文案                                                                                                     | 服务端的区域设置                                                                                                                                 | 译文来源                                                                                                     |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Paraglide JS](https://paraglidejs.com/tanstack-start)，由 General Translation 维护 | 每个区域设置对应一个 JSON 文件存放消息，编译为 `m.greeting()` 等带类型的函数                                                          | `paraglideMiddleware` 包裹服务端处理函数；策略包括 URL、cookie 和首选语言                                                                                    | 由 General Translation 的 CLI 翻译消息文件 ([Paraglide 集成](/docs/integrations/paraglide/quickstart)) ，或由你自己和译者填充 |
| [react-i18next](https://react.i18next.com/latest/ssr)                           | 在 JSON 命名空间中定义键，通过 `t('home.title')` 渲染                                                                    | 其文档未提供 TanStack Start 集成；你需要自行创建按请求的实例，并将 `initialLanguage` 和 `initialI18nStore` 传给客户端                                                   | 由你自己、译者、Locize 等翻译管理系统 (TMS) ，或 General Translation 的 CLI 提供                                             |
| [Lingui](https://lingui.dev/ref/vite-plugin)                                    | 内联使用 `<Trans>` 宏，提取到 PO 消息目录                                                                               | 其 Vite 插件负责编译消息目录；你需要在服务端和浏览器中激活当前请求的区域设置                                                                                                | 由你自己、译者、与消息目录同步的服务，或 General Translation 的 CLI 提供                                                        |
| General Translation (`gt-tanstack-start`，实验性)                                   | 用 [`<T>`](/docs/react/reference/components/t) 包裹 JSX，用 [`useGT`](/docs/react/reference/hooks/use-gt) 处理字符串 | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware)：依次检查 URL 前缀 (需主动启用) 、cookie、`Accept-Language`，最后回退到默认区域设置 | 由 [`npx gt translate`](/docs/cli/reference/commands/translate) 生成，并在仪表板中审校                               |

如果你想采用 TanStack i18n 指南推荐的初始化设置、带类型的消息函数以及按消息粒度的 tree-shaking，请选择 Paraglide JS，再由 General Translation 的 CLI 翻译其消息文件 (请参阅[如何翻译 Paraglide JS 消息？](/kb/general-translation-vs-paraglide)) 。如果你要沿用其他应用中的 i18next 消息目录，请选择 react-i18next。如果你的译者习惯使用 PO 文件，请选择 Lingui。如果你希望文案直接内联在组件中，并由此自动生成译文、保持同步更新，请选择 `gt-tanstack-start`。

`gt-tanstack-start` 目前处于实验阶段：General Translation 的文档指出它可能出现破坏性变更，暂不建议用于生产环境。如果现在就要用于生产环境，请将 Paraglide JS 与 General Translation 的 CLI 搭配使用，或参阅[如何翻译 React 应用？](/kb/translate-react-app)了解稳定的 React 初始化设置。

## 将 Paraglide JS 添加到 TanStack Start

TanStack 官方维护了一个 [TanStack Start 集成 Paraglide 的示例](https://github.com/TanStack/router/tree/main/examples/react/start-i18n-paraglide)，Paraglide 的 [TanStack Start 指南](https://paraglidejs.com/tanstack-start)也采用相同的设置方式。新应用也可以直接使用 TanStack CLI 的 `paraglide` 插件起步。

1. 初始化 Paraglide，这会生成 `project.inlang/settings.json` 和你的消息文件：

   ```bash
   npx @inlang/paraglide-js@latest init
   ```

2. 在 `vite.config.ts` 中，将 Vite 插件添加到 `tanstackStart()` 旁边，并配置所需的区域设置策略：

   ```ts title="vite.config.ts"
   import { paraglideVitePlugin } from '@inlang/paraglide-js';

   paraglideVitePlugin({
     project: './project.inlang',
     outdir: './src/paraglide',
     strategy: ['url', 'cookie', 'preferredLanguage', 'baseLocale'],
   });
   ```

3. 在 `src/server.ts` 中用 `paraglideMiddleware` 包裹服务器处理函数，使每个请求都在对应的区域设置下运行：

   ```ts title="src/server.ts"
   import { paraglideMiddleware } from './paraglide/server.js';
   import handler from '@tanstack/react-start/server-entry';

   export default {
     fetch(req: Request): Promise<Response> {
       return paraglideMiddleware(req, () => handler.fetch(req));
     },
   };
   ```

4. 在 `__root.tsx` 中通过 `<html lang={getLocale()}>` 设置文档语言，其中该函数从 Paraglide 生成的 `paraglide/runtime.js` 导入。

如需支持 `/de/about` 这类本地化 URL，请参照示例，将 Paraglide 的 `localizeUrl` 和 `deLocalizeUrl` 传入路由器的 `rewrite` 选项。

### 使用 General Translation 翻译消息

保留 Paraglide，同时添加 General Translation 的 CLI。根据你的消息文件模式运行 [`npx gt init --no-react-setup`](/docs/cli/reference/commands/init)，将快速入门中针对 inlang 消息文件的规则添加到 `gt.config.json`，然后运行 [`npx gt translate`](/docs/cli/reference/commands/translate)。CLI 会为每个目标区域设置生成一个消息文件 (例如 `messages/es.json`) ，键、占位符和变体结构均保持不变，Paraglide 会将其编译为同样的带类型的函数。具体配置和 CI 设置请参阅 [Paraglide JS 快速入门](/docs/integrations/paraglide/quickstart)。

## 将 gt-tanstack-start 添加到 TanStack Start

本教程使用 General Translation 的实验性内联库，将为页面添加西班牙语和法语支持，翻译一个服务器函数，然后为每种语言分配独立的 URL。本教程已使用 `npx @tanstack/cli@latest create` 创建的应用 (`@tanstack/react-start` 1.169.4) 、`gt-tanstack-start@11.4.16` 和 `gt@2.26.11` 测试通过。该软件包要求 `@tanstack/react-start` 1.159.0 或更高版本，且仅支持 ESM。

[初始化设置向导](/docs/cli/reference/commands/init) (`npx gt@2.26.11 init`) 所做的更改与步骤 1 至 4 相同：安装该软件包，写入加载器、中间件、路由器调用和 root 路由，并列出所有无法安全修改的内容。你可以检查它生成的差异，也可以按照以下步骤手动操作。

### 1. 安装库和 CLI

```bash
npm install gt-tanstack-start@11.4.16
npm install --save-dev gt@2.26.11
```

`gt-tanstack-start` 导出共享的 React 组件 (例如 [`<T>`](/docs/react/reference/components/t) 和 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)) 以及服务端辅助函数。`gt` CLI 负责查找源文案并生成翻译文件。

### 2. 设置语言

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

请将输出文件放在 `src/` 目录下，以便 Vite 导入。然后添加一个加载器：

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

### 3. 注册请求中间件

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

// 为服务器函数保留 TanStack Start 的 CSRF 防护。
const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

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

General Translation 的 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) 会为每个请求解析一次区域设置，依次检查区域设置 cookie、`Accept-Language` 和 `defaultLocale`，并将结果保存到 cookie 中。即使多个请求同时渲染，每个请求也会保持各自的区域设置。

### 4. 初始化库并对 root 路由进行水合

在现有的 `src/router.tsx` 中，于模块作用域添加初始化代码：

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

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

// ... 现有的 getRouter() 代码
```

然后在 root 路由中加载区域设置及其译文，并将二者传给 [`<GTProvider>`](/docs/react/reference/components/gt-provider)：

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

export const Route = createRootRoute({
  // 首次请求时在服务器端运行，因此返回的 HTML 已完成翻译。
  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) 在服务器端读取请求的区域设置，在浏览器端则读取 cookie，从而确保两端的渲染结果一致。设置 `lang={locale}` 后，即可替换 starter 模板 shell 中硬编码的 `lang="en"`。

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

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

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

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

  return (
    <main>
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} />
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) 会将标题和段落作为一个整体进行翻译，并将标记结构作为上下文。属性中的字符串则由 [`useGT`](/docs/react/reference/hooks/use-gt) 处理。如果 [`<T>`](/docs/react/reference/components/t) 中包含名称、数量和日期，请使用[变量和格式化组件](/docs/react/guides/formatting-variables)。

### 6. 生成译文

使用 [`npx gt login`](/docs/cli/reference/commands/login) 登录，设置 `GT_PROJECT_ID` (或在 `gt.config.json` 中设置 `projectId`) ，然后运行 [`npx gt translate`](/docs/cli/reference/commands/translate)。该命令会生成 `src/_gt/es.json` 和 `src/_gt/fr.json`。生成译文采用[按用量计费](https://generaltranslation.com/pricing)。

如果想在不注册账户的情况下试用这套初始化设置，请运行 [`npx gt generate`](/docs/cli/reference/commands/generate)。该命令会生成相同的文件，但内容为英文源文本，需要你手动编辑。如果某个区域设置尚无对应文件，则会渲染源文本，并记录一条警告，提示其译文无法加载。

### 7. 运行并切换语言

运行 `npm run dev`，然后在选择器中选择 Español。选择结果会保存到区域设置 cookie 中，页面随即重新加载，服务器会渲染西班牙语内容。在测试应用中，生产环境构建对带有 `Accept-Language: es` 的请求返回了 `<html lang="es">` 以及西班牙语标题和占位符；对未指定语言偏好的请求，则返回了 `<html lang="en">` 和英语内容。

### 在服务器函数和元数据中进行翻译

[`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) 可在服务器函数中根据当前请求的区域设置翻译字符串：

```tsx title="src/routes/account.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { getGT } from 'gt-tanstack-start';

const loadAccount = createServerFn({ method: 'GET' }).handler(async () => {
  const gt = await getGT();
  return { title: gt('Your account') };
});

export const Route = createFileRoute('/account')({
  loader: () => loadAccount(),
  // 翻译后的标题也会用作页面的 <title>。
  head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }),
  component: () => <h1>{Route.useLoaderData().title}</h1>,
});
```

在服务器端，如果在 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) 所处理的请求之外 (例如在模块作用域中) 调用这些辅助函数，就会抛出错误。[使用服务器函数](/docs/react/tanstack-start/using-server-functions)中也介绍了词典条目和已注册的消息的用法。

### 为每种语言提供独立的 URL

上述 `gt-tanstack-start` 初始化设置会在同一个 URL 下提供所有语言，具体显示哪种语言由 cookie 或浏览器语言决定。搜索引擎对每个 URL 只会索引一种语言，因此[公开页面需要添加前缀](/kb/locale-routing-seo)，例如 `/es/about`。请将路由移到一个可选路径段下，例如 `src/routes/{-$locale}/index.tsx`，并配合使用 `createFileRoute('/{-$locale}/')`，然后启用区域设置路由：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "localeRouting": true
}
```

随后，中间件会先检查路径，选择器则跳转到带前缀的 URL。在测试应用中，`/es` 和 `/es/account` 渲染为西班牙语，并带有 `<html lang="es">`，而 `/` 渲染为英语。对于回访用户，不带前缀的 URL 仍会根据 cookie 确定语言；此外，你需要自行在每个路由的 `head` 中添加 [`hreflang` 链接](/kb/what-is-hreflang)。 (参见[区域设置路由初始化设置](/docs/react/tanstack-start/setup#locale-routing)。)

### 发布并让译文保持最新

每次构建前先运行翻译，确保新增文案以所有语言同步发布：

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

[`gt validate`](/docs/cli/reference/commands/validate) 会在发起任何 API 调用之前进行检查，一旦发现会破坏翻译的内容，就让构建失败。在 CI 中，请设置 `GT_PROJECT_ID`，并将一个具有 **Files &gt; Write**、**Translation queue &gt; Enabled** 和 **Context &gt; Write** 权限的项目 API 密钥设为 `GT_API_KEY` (参见 [CLI 凭据](/docs/cli/guides/configuring#credentials)) 。之后每次运行只会翻译新增或变更的源内容。

审校人员可以在 General Translation 的[翻译编辑器](/docs/platform/dashboard/guides/reviewing-translations)中编辑任意字符串；直接在 JSON 文件中所做的修改，则可通过 [`npx gt save-local`](/docs/cli/reference/commands/save-local) 同步回去，确保后续运行时得以保留。[上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)用于存放你的词汇表和自定义提示词，让产品名称和语气在本应用、你的文档以及其他项目中保持一致。General Translation 的 AI 智能体 [Locadex](/docs/platform/locadex/guides/configuring-automations) 支持 TanStack Start 应用，并可通过拉取请求翻译新增文案。

## 常见问题

### TanStack Start 是否内置 i18n？

没有。TanStack Router 提供可选的区域设置路径段和 URL 重写，Start 提供中间件和加载器，但消息、区域设置检测和翻译功能仍需借助库来实现。

### 可以在 TanStack Start 中使用 react-i18next 吗？

可以，把它当作普通的 React 库使用即可。不过 TanStack 并未提供相关文档，react-i18next 的 SSR 指南也只提到了 Next.js、Remix 和 Gatsby 的集成，因此你需要自行接入按请求创建的实例和客户端水合。

### gt-tanstack-start 是否可用于生产环境？

暂不建议：General Translation 目前将其标记为实验性功能。请锁定版本，并在升级前查阅更新日志。

## 要点总结

* TanStack Start 本身没有 i18n 层；它的可选 `/{-$locale}` 路由段、`createStart` 中间件和根加载器正是接入 i18n 的位置。
* 在服务器端按请求解析区域设置，并用相同的消息对客户端进行水合；同时在加载器中设置 `<html lang>`，不要沿用初始模板中硬编码的 `lang="en"`。
* Paraglide JS 是 TanStack 的 i18n 指南所推荐的库，由 General Translation 维护。General Translation 的 CLI 可以翻译其消息文件，也能翻译 i18next JSON 和 Lingui 的 PO 消息目录。
* General Translation 的实验性库 `gt-tanstack-start` 提供了 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware)、[`initializeGT`](/docs/react/reference/config#initialize) 和 [`<GTProvider>`](/docs/react/reference/components/gt-provider)，文案以内联方式保留在 [`<T>`](/docs/react/reference/components/t) 中，再由 [`npx gt translate`](/docs/cli/reference/commands/translate) 写入 `src/_gt/[locale].json`。
* 如果每种语言都需要独立且可被搜索引擎索引的 URL，请添加 `"localeRouting": true`，并配合可选的 `{-$locale}` 路由段使用。

## Related questions

- [如何为 Next.js App Router 应用添加 i18n？](https://generaltranslation.com/zh/kb/add-i18n-to-nextjs.mdx): 首先在受支持的 App Router 项目中运行 gt init 来配置 General Translation，然后标记源内容、生成译文并验证语言切换。gt-next 将文案与翻译上下文一同保留在 JSX 中；CLI、仪表板编辑器和 Locadex 负责生成、审校和持续更新。本指南还演示了如何显式配置本地文件。
- [如何翻译 Paraglide JS 消息？](https://generaltranslation.com/zh/kb/general-translation-vs-paraglide.mdx): 继续使用 Paraglide JS（现由 General Translation 维护），并借助 General Translation 的 CLI 翻译其消息文件。每次运行都会为每个目标区域设置写入一个文件，完整保留键、占位符和变体结构，同时应用你的词汇表和自定义提示词，并在构建前翻译新增和变更的消息。你的组件和 Paraglide 初始化设置均无需改动。
- [React 应用最适合使用哪个国际化库？](https://generaltranslation.com/zh/kb/best-react-i18n-library.mdx): 主流的 React 国际化库有四个：General Translation 的 gt-react、react-i18next、Lingui 和 React Intl。四者都能渲染和格式化译文，但只有 gt-react 还能根据你在 JSX 中内联编写的文案直接生成译文。如果想继续沿用 i18next 的消息目录和插件，请选择 react-i18next；如果需要将文案提取为编译后的消息目录，请选择 Lingui；如果需要 FormatJS 和 ICU MessageFormat，请选择 React Intl。
- [语言重定向与 SEO：URL、cookie 还是 Accept-Language？](https://generaltranslation.com/zh/kb/locale-routing-seo.mdx): 凡是希望被搜索引擎收录的页面，都应由 URL 决定其语言，因为 Googlebot 不会发送 Accept-Language 请求头，而且大多从美国 IP 地址抓取。只有在决定 / 这类中立的根路径重定向到哪里时，才应优先参考 cookie 中保存的用户选择，其次是 Accept-Language，并使用临时的 302 或 307 重定向。
- [如何翻译 React 应用？](https://generaltranslation.com/zh/kb/translate-react-app.mdx): 翻译 React 应用，需要先对组件进行国际化，使其以用户的语言渲染，再将每个字符串翻译成你支持的各种语言。General Translation 的 gt-react 在 `<T>` 组件中原地翻译 JSX，npx gt translate 则会为每种语言生成一个文件。

## Previous and next questions

- Previous question: [如何为 Next.js Pages Router 应用添加 i18n？](https://generaltranslation.com/zh/kb/add-i18n-to-nextjs-pages-router.mdx)
- Next question: [如何为多语言网站创建站点地图？](https://generaltranslation.com/zh/kb/multilingual-sitemap.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/zh/kb/sitemap.md) for every article.
