# General Translation React SDKs (gt-react, gt-next): Next.js App Router 快速开始 URL: https://generaltranslation.com/zh/docs/react/nextjs-quickstart.mdx --- title: Next.js App Router 快速开始 description: 在 10 分钟内使用 General Translation 为 Next.js App Router 应用添加多语言支持。 related: links: - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables --- # Next.js App Router 快速开始完成本指南后，你的 Next.js 应用将能够以多种语言显示内容，并提供可供用户使用的语言切换器。 **前提条件：** * 一个使用 **App Router** 的 Next.js 应用 (Next.js 13+) * Node.js 18+ **提示：**运行 `npx gt@latest`，即可通过[设置向导](/docs/cli/reference/commands/init)完成全部配置。本指南介绍的是手动设置。 **注意：**如果你使用的是 Pages Router，请改为参考 [Next.js Pages Router 快速开始](/docs/react/nextjs-pages-router-quickstart)。 ## 快速开始 [#quickstart] ### 1. 安装软件包 `gt-next` 是为应用提供翻译能力的库。`gt` 是用于为生产环境准备翻译内容的 CLI 工具。 ```bash npm i gt-next npm i -D gt ``` ```bash yarn add gt-next yarn add --dev gt ``` ```bash bun add gt-next bun add --dev gt ``` ```bash pnpm add gt-next pnpm add --save-dev gt ``` ### 2. 配置 Next.js `gt-next` 使用名为 **`withGTConfig`** 的 Next.js plugin，在构建阶段设置国际化。请用它包裹你现有的 Next.js 配置： ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; const nextConfig = {}; export default withGTConfig(nextConfig); ``` 此插件会读取你的翻译设置，并在后台自动完成所有相关配置。无需对你的 Next.js 配置做任何其他更改。 ### 3. 创建翻译配置文件在项目根目录下创建一个 **`gt.config.json`** 文件，用于告诉该库你支持哪些语言： ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` * **`defaultLocale`** — 你的应用所使用的语言 (即源语言) 。 * **`locales`** — 你想翻译成的语言。可从[支持的区域设置列表](/docs/platform/dashboard/reference/supported-locales)中任选。 * **`files.gt.output`** — CLI 保存翻译文件的位置。`[locale]` 会替换为各个语言代码 (例如 `public/_gt/es.json`) 。将 `public/_gt/` 添加到你的 **`.gitignore`** 中——这些文件是自动生成的，不是手动编写的： ```txt title=".gitignore" public/_gt/ ``` ### 4. 为本地翻译添加 load function 在你的 `src/` 目录 (或项目根目录) 中创建一个 **`loadTranslations`** 文件，用于告诉 `gt-next` 如何加载由 CLI 生成的翻译文件： ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` 会自动检测 `src/` 目录或项目根目录中的 `loadTranslations.[js|ts]` 文件，无需额外配置。 **注意：**本地翻译会随应用一同打包，因此可即时加载，无需依赖外部服务。有关详细信息和取舍，请参阅[存储翻译](/docs/react/guides/storing-translations)。 ### 5. 将 GTProvider 添加到布局中 **`GTProvider`** 组件可让整个应用访问翻译内容。它必须在根布局层级包裹你的应用： ```tsx title="app/layout.tsx" import { GTProvider, useLocale } from 'gt-next'; export default function RootLayout({ children }: { children: React.ReactNode }) { const locale = useLocale(); return ( {children} ); } ``` ### 6. 将内容标记为可翻译现在，用 **``** 组件包裹任何你想要翻译的文本。`` 表示 "translate"： ```tsx title="app/page.tsx" import { T } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.

); } ``` 你可以在 `` 中包裹任意多少 JSX。里面的所有内容——文本、嵌套元素，甚至格式——都会作为一个整体进行翻译。 ### 7. 添加语言切换器添加一个 **``**，让用户可以切换语言： ```tsx title="app/page.tsx" import { T, LocaleSelector } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.

); } ``` `LocaleSelector` 会渲染一个下拉菜单，其中显示的是来自你的 `gt.config.json` 的语言。 ### 8. 设置环境变量 (可选) 要在开发环境中查看翻译效果，你需要 General Translation 提供的 API 密钥。它们可启用**按需翻译**——这样你在开发过程中，应用就能实时翻译内容。创建一个 **`.env.local`** 文件： ```bash title=".env.local" GT_API_KEY="your-api-key" GT_PROJECT_ID="your-project-id" ``` 前往 [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 免费获取密钥，或运行： ```bash npx gt auth ``` **警告：** 在开发环境中，请使用以 `gtx-dev-` 开头的密钥。生产环境密钥 (`gtx-api-`) 仅用于 CI/CD。切勿将 `GT_API_KEY` 暴露给浏览器，也不要将其提交到版本控制系统中。可以。不使用 API 密钥时，`gt-next` 会作为标准 i18n 库运行。你将无法在开发环境中使用按需翻译，但仍然可以： * 手动提供自己的翻译文件 * 使用所有组件 (``、``、`LocaleSelector` 等) * 运行 `npx gt generate` 创建翻译文件模板，然后自行翻译 ### 9. 查看效果启动开发服务器： ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` 打开 [http://localhost:3000](http://localhost:3000)，使用语言下拉菜单切换语言。你应该能看到内容已被翻译。 **注意：** 在开发环境中，翻译是按需进行的，因此首次切换到新语言时，你可能会看到短暂的加载状态。在生产环境中，翻译会预先生成，并可立即加载。 ### 10. 翻译字符串对于普通字符串——例如 `placeholder` 属性、`aria-label` 的值或 `alt` 文本——请使用 **`useGT`** 钩子。它可用于同步服务器组件和客户端组件： ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return ( ); } ``` 异步组件不能使用钩子。请改为从 `gt-next/server` 导入 `getGT`： ```tsx import { getGT } from 'gt-next/server'; export default async function Page() { const gt = await getGT(); return

{gt('Hello')}

; } ``` ### 11. 部署到生产环境在生产环境中，翻译会在构建阶段预先生成 (不会发起实时 API 调用) 。将 translate 命令添加到你的构建脚本中： ```json title="package.json" { "scripts": { "build": "npx gt translate && next build" } } ``` 在你的托管服务商 (Vercel、Netlify 等) 中设置 **生产环境** 变量： ```bash GT_PROJECT_ID=your-project-id GT_API_KEY=gtx-api-your-production-key ``` **警告：**Production keys 以 `gtx-api-` 开头 (不是 `gtx-dev-`) 。请前往 [dash.generaltranslation.com](https://dash.generaltranslation.com) 获取。绝不要添加 `NEXT_PUBLIC_` 前缀。就是这样——你的应用现在已经支持多语言了。🎉 ## 故障排查 [#troubleshooting] `gt-next` 会将用户的语言偏好存储在名为 `generaltranslation.locale` 的 cookie 中。如果你之前测试过其他语言，这个 cookie 可能会覆盖当前选择。请清除 cookie 后重试。 * [Chrome](https://support.google.com/chrome/answer/95647) * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored) * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0) 这是预期行为。在开发环境中，翻译是按需进行的 (你的内容会通过 API 实时翻译) 。这种延迟**在生产环境中不会出现**——所有翻译都会由 `npx gt translate` 预先生成。含义模糊的文本可能会导致翻译不准确。例如，“apple” 既可能指水果，也可能指公司。添加 `context` prop 可以帮助消除歧义： ```jsx Apple ``` ``、`useGT()` 和 `getGT()` 都支持 `context` 选项。 ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables