# General Translation React SDKs (gt-react, gt-next): 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 应用添加自动国际化支持。你需要在 root 路由中初始化 General Translation，解析请求的区域设置，并通过路由加载器为 `GTProvider` 提供水合数据。本快速入门适用于 TanStack Start 应用。对于普通的 React SPA，请参阅 [React 快速入门](/docs/react/react-quickstart)。 `gt-tanstack-start` 仍处于实验阶段，可能会引入破坏性变更。目前尚不建议在生产环境中使用。 ## 快速入门 [#quickstart] 安装这些包，创建配置文件和翻译加载器，配置 root 路由，标记需要翻译的内容，并生成翻译。 ### 1. 安装 `gt-tanstack-start` 安装 `gt-tanstack-start` 和 `gt-react` 作为依赖，并将 [`gt` CLI](/docs/cli/quickstart) 安装为开发依赖。还需要直接安装 `gt-react`，这样 CLI 才能在你的 source 中检测到 [``](/docs/react/reference/components/t) 组件。 ```bash npm install gt-tanstack-start gt-react && npm install gt --save-dev ``` ```bash yarn add gt-tanstack-start gt-react && yarn add --dev gt ``` ```bash bun add gt-tanstack-start gt-react && bun add --dev gt ``` ```bash pnpm add gt-tanstack-start gt-react && pnpm add --save-dev gt ``` ### 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. 设置 root 路由在 `src/routes/__root.tsx` 中，在模块级别调用 [`initializeGT`](/docs/node/reference/functions/initialize-gt)，用 `parseLocale` 解析区域设置，并在路由加载器中加载翻译快照。将 `locale` 和 `translations` 传给 `GTProvider`。 ```tsx title="src/routes/__root.tsx" import { HeadContent, Scripts, createRootRoute, } from '@tanstack/react-router'; import { initializeGT, GTProvider, parseLocale, getTranslationsSnapshot, LocaleSelector, } from 'gt-tanstack-start'; import gtConfig from '../../gt.config.json'; import loadTranslations from '../../loadTranslations'; // 在模块级别初始化 General Translation，只执行一次 initializeGT({ ...gtConfig, loadTranslations }); export const Route = createRootRoute({ loader: async () => { const locale = parseLocale(); return { locale, translations: await getTranslationsSnapshot(locale), }; }, shellComponent: RootDocument, }); function RootDocument({ children }: { children: React.ReactNode }) { const { locale, translations } = Route.useLoaderData(); return ( {children} ); } ``` `parseLocale` 在服务器端会从请求的 cookie 和 header 中读取区域设置，在浏览器端则从 cookie 中读取。`GTProvider` 同时需要 `locale` 和 `translations`。 ### 5. 标记要翻译的内容将 JSX 包裹在 `` 组件中，即可原地翻译。请从 `gt-react` 导入 `` 和 [`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 (

Welcome to my app

This content is translated automatically.

); } ``` `useGT()` 会直接返回翻译函数，因此请这样调用：`const gt = useGT();`。 ### 6. 生成翻译运行 CLI，通过 General Translation API 为你的项目生成翻译。 ```bash npx gt translate ``` 将该命令添加到你的构建脚本中，以确保生产环境构建始终使用最新的翻译： ```json title="package.json" { "scripts": { "build": "npx gt translate && vite build" } } ``` *注意：`npx gt translate` 需要项目 ID 和 production API key，并将它们在环境中设置为 `GT_PROJECT_ID` 和 `GT_API_KEY`。运行 `npx gt auth` 或访问[仪表板](/docs/platform/dashboard/get-started)即可获取。* ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables