# General Translation React SDKs (gt-react, gt-next, gt-react-native): Next.js App Router 快速开始 URL: https://generaltranslation.com/zh/docs/react/nextjs-quickstart.mdx Docs index: https://generaltranslation.com/llms.txt Description: 使用 General Translation，在 10 分钟内为 Next.js App Router 应用添加多语言支持。 完成本指南后，你的 Next.js 应用将能够以多种语言显示内容，并提供可供用户使用的语言切换器。 **前提条件：** * 一个使用 **App Router** 的 Next.js 应用 (Next.js 13.0.0 或更高版本，但不包括 15.2.1 和 15.2.2) * Node.js 18+ **提示：**运行 `npx gt@latest`，即可通过[设置向导](/docs/cli/quickstart)完成全部配置。本指南介绍的是手动设置。 **注意：**如果你使用的是 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 配置。在此代码片段及下方的代码片段中，绿色行表示新增内容，红色行表示删除内容；请保留你的配置中已有的任何 options： ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; // [!code ++] const nextConfig = {}; export default nextConfig; // [!code --] export default withGTConfig(nextConfig); // [!code ++] ``` 此插件会读取你的翻译设置，并在后台自动完成所有相关配置。无需对你的 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`](/docs/react/reference/functions/load-translations)** 文件，用于告诉 `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; } ``` **警告：**这些翻译文件在创建之前并不存在，因此首次运行 `npm run dev` 时会编译失败，页面会返回 HTTP 500。请运行 [`npx gt generate`](/docs/cli/reference/commands/generate) (无需 API 密钥) 或 [`npx gt translate`](/docs/cli/reference/commands/translate) (使用凭据) ，或者在 `public/_gt/[locale].json` 中添加空的 `{}` 文件。 `withGTConfig` 会自动检测 `src/` 目录或项目根目录中的 `loadTranslations.[js|ts]` 文件，无需额外配置。 **注意：**本地翻译会随应用一同打包，因此可即时加载，无需依赖外部服务。有关详细信息和取舍，请参阅[存储翻译](/docs/react/guides/storing-translations)。 ### 5. 将 GTProvider 添加到布局中 **[`GTProvider`](/docs/react/reference/components/gt-provider)** 组件可让整个应用访问翻译内容。它必须在根布局层级包裹你的应用。其余现有布局 (字体、元数据、样式) 保持不变： ```tsx title="app/layout.tsx" import { GTProvider, useLocale } from 'gt-next'; // [!code ++] export default function RootLayout({ children }: { children: React.ReactNode }) { const locale = useLocale(); // [!code ++] return ( {/* [!code --] */} {/* [!code ++] */} {/* [!code --] */} {children} {/* [!code ++:3] */} {children} ); } ``` ### 6. 将内容标记为可翻译 现在，用 **[``](/docs/react/reference/components/t)** 组件包裹任何你想要翻译的文本。[``](/docs/react/reference/components/t) 表示 "translate"： ```tsx title="app/page.tsx" import { T } from 'gt-next'; // [!code ++] export default function Home() { return (
{/* [!code ++] */}

Welcome to my app

This content will be translated automatically.

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

Welcome to my app

This content will be translated automatically.
); } ``` [`LocaleSelector`](/docs/react/reference/components/locale-selector) 会渲染一个下拉菜单，其中显示的是来自你的 `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/en-US/signin) 免费获取密钥，或运行： ```bash npx gt auth ``` **警告：** 在开发环境中，请使用以 `gtx-dev-` 开头的密钥。生产环境密钥 (`gtx-api-`) 仅用于 CI/CD。 切勿将 `GT_API_KEY` 暴露给浏览器，也不要将其提交到版本控制系统中。 可以。不使用 API 密钥时，`gt-next` 会作为标准 i18n 库运行。你将无法在开发环境中使用按需翻译，但仍然可以： * 手动提供自己的翻译文件 * 使用所有组件 ([``](/docs/react/reference/components/t)、[``](/docs/react/reference/components/var)、[`LocaleSelector`](/docs/react/reference/components/locale-selector) 等) * 运行 [`npx gt generate`](/docs/cli/reference/commands/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`](/docs/react/reference/hooks/use-gt)** 钩子。它可用于同步服务器组件和客户端组件： ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return (
); } ``` 异步组件不能使用钩子。请改为从 `gt-next/server` 导入 [`getGT`](/docs/react/nextjs/reference/functions/get-gt)： ```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] 确认浏览器 cookie 已启用，并且选择器在 [``](/docs/react/reference/components/gt-provider) 下渲染。如果已启用区域设置路由，还请确认中间件匹配器和 [`pathRegex`](/docs/react/nextjs/config#path-regex) 包含当前路由。 这是预期行为。在开发环境中，翻译是按需进行的 (你的内容会通过 API 实时翻译) 。这种延迟**在生产环境中不会出现**——所有翻译都会由 [`npx gt translate`](/docs/cli/reference/commands/translate) 预先生成。 含义模糊的文本可能会导致翻译不准确。例如，“apple” 既可能指水果，也可能指公司。添加 `$context` prop 可以帮助消除歧义： ```jsx Apple ``` [``](/docs/react/reference/components/t)、[`useGT()`](/docs/react/reference/hooks/use-gt) 和 [`getGT()`](/docs/react/nextjs/reference/functions/get-gt) 都支持 `$context`。 ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.