# tanstack-start: TanStack Start 快速入门 URL: https://generaltranslation.com/zh/docs/tanstack-start.mdx --- title: TanStack Start 快速入门 description: 使用 gt-tanstack-start 为你的 TanStack Start 应用添加国际化支持 --- **前提条件：** 使用 React 16.8+ 的 TanStack Start 项目 **实验性：** `gt-tanstack-start` 仍在积极开发中，暂不建议用于生产环境。 ## 安装安装 `gt-tanstack-start`、`gt-react` 和 `gt` CLI： ```bash npm i gt-tanstack-start gt-react npm i -D gt ``` ```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 ``` 必须将 `gt-react` 作为直接依赖安装，这样 `gt` CLI 才能在源代码中检测到 `` 组件。 ## 配置 ### `gt.config.json` 在项目 root 目录中创建一个 `gt.config.json`： ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "ja"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` 翻译文件**必须**放在 `src/` 目录下，Vite 的动态导入才能正常工作。使用 `public/` 不会生效。 ### 翻译加载器在项目 root 目录中创建一个 `loadTranslations.ts` 文件： ```ts title="loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`./src/_gt/${locale}.json`); return translations.default; } ``` ### Root 路由 setup 更新 `src/routes/__root.tsx`，以初始化 GT 并提供译文： ```tsx title="src/routes/__root.tsx" import { HeadContent, Scripts, createRootRoute, } from '@tanstack/react-router' import { initializeGT, GTProvider, getTranslations, getLocale, LocaleSelector, } from 'gt-tanstack-start' import gtConfig from '../../gt.config.json' import loadTranslations from '../../loadTranslations' // 在模块级别初始化 GT initializeGT({ ...gtConfig, loadTranslations, }) export const Route = createRootRoute({ head: () => ({ meta: [ { charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }, ], }), loader: async () => { return { translations: await getTranslations(), locale: getLocale(), } }, shellComponent: RootDocument, }) function RootDocument({ children }: { children: React.ReactNode }) { const { translations, locale } = Route.useLoaderData() return ( {children} ) } ``` ## 用法使用 `` 包裹内容即可进行翻译。从 `gt-react` 导入 ``： ```tsx title="src/routes/index.tsx" import { createFileRoute } from '@tanstack/react-router' import { T } from 'gt-react' export const Route = createFileRoute('/')({ component: Home }) function Home() { return (

Welcome to our app!

This content is automatically translated.

) } ``` 请从 `gt-react` 导入 `` (不要从 `gt-tanstack-start` 导入) 。`gt` CLI 会扫描从 `gt-react` 的导入，以查找可翻译的内容。 ## 生成译文 ### 使用 General Translation (推荐) 运行 `gt translate` 命令来生成译文： ```bash npx gt translate ``` 这会将你的内容发送到 General Translation API，并将翻译后的 JSON 文件下载到 `src/_gt/`。你需要为该 API 设置环境变量： ```bash title=".env" GT_API_KEY="your-api-key" GT_PROJECT_ID="your-project-id" ``` 前往 [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 免费获取 API 密钥，或运行： ```bash npx gt auth ``` ### 手动翻译如果你希望自行管理译文： 1. 生成源语言文件： ```bash npx gt generate ``` 2. 手动翻译生成的 JSON 文件 3. 将其放在 `src/_gt/{locale}.json` ## 测试启动开发服务器： ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun run dev ``` ```bash pnpm dev ``` 访问 [localhost:3000](http://localhost:3000)，使用区域设置选择器切换语言。译文从本地 JSON 文件加载，因此语言切换会立即生效。 ## 部署将翻译步骤添加到 build 脚本中： ```json title="package.json" { "scripts": { "build": "npx gt translate && vite build" } } ``` ## 示例应用查看完整的可运行示例：[tanstack-start-basic](https://github.com/generaltranslation/gt/tree/main/examples/tanstack-start-basic) *** ## 下一步 * 阅读[概览](/docs/tanstack-start/introduction)，更深入地了解 API * 了解 ``、`` 和 `` 等[变量组件](/docs/react/guides/variables) * 查阅 [`` 组件](/docs/react/api/components/t) 的 API 参考