# gt-next: General Translation Next.js SDK: Next.js 快速入门 URL: https://generaltranslation.com/zh/docs/next.mdx --- title: Next.js 快速入门 description: 在 10 分钟内为你的 Next.js 应用添加多语言支持 --- 完成本指南后，你的 Next.js 应用就能以多种语言显示内容，并提供可供用户交互的语言切换器。 **前提条件：** * 使用 **App Router** (Next.js 13+) 的 Next.js 应用 * Node.js 18+ **想自动完成设置？** 运行 `npx gt@latest`，通过 [设置向导](/docs/cli/init) 完成全部配置。本指南介绍的是手动设置。 *** ## 第 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 插件，在构建阶段设置国际化。请用它包装你现有的 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/supported-locales)中任选即可。 * **`files.gt.output`** — CLI 保存翻译文件的位置。`[locale]` 会替换为各语言代码 (例如 `public/_gt/es.json`) 。将 `public/_gt/` 添加到你的 **`.gitignore`** 中——这些文件是自动生成的，不是手动编写的： ```txt title=".gitignore" public/_gt/ ``` *** ## 第 4 步：将 GTProvider 添加到布局中 **`GTProvider`** 组件可让整个应用访问翻译功能。你必须在根布局层级用它包裹应用： ```tsx title="app/layout.tsx" import { GTProvider } from 'gt-next'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` `GTProvider` 是一个**服务端组件**——它会在服务器上加载翻译，并将其传递给客户端组件。 *** ## 第 5 步：将内容标记为可翻译现在，用 **``** 组件包裹你想翻译的文本。`` 表示 "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。其中的所有内容——文本、嵌套元素，甚至格式——都会作为一个整体进行翻译。 *** ## 第 6 步：添加语言切换器添加一个 **``**，让用户能够切换语言： ```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` 中的语言。 *** ## 第 7 步：设置环境变量 (可选) 如果你想在开发环境中看到翻译效果，需要使用 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` 生成翻译文件模板，然后自行翻译 *** ## 第 8 步：查看运行效果启动开发服务器： ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` 打开 [http://localhost:3000](http://localhost:3000)，使用语言下拉菜单切换语言。你应该会看到内容已完成翻译。在开发环境中，翻译是按需进行的——首次切换到某种新语言时，你可能会短暂看到加载状态。在生产环境中，翻译会预先生成，并可即时加载。 *** ## 第 9 步：翻译字符串 (不只是 JSX) 对于普通字符串——例如 `placeholder` 属性、`aria-label` 值或 `alt` 文本——请使用 **`useGT`** Hook。它在服务端组件和客户端组件中都可用： ```tsx title="app/contact/page.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return ( ); } ``` 如果你更喜欢在服务端组件中使用 `async/await`，请从 `gt-next/server` 导入 `getGT`： ```tsx import { getGT } from 'gt-next/server'; export default async function Page() { const gt = await getGT(); return

{gt('Hello')}

; } ``` *** ## 第 10 步：部署到生产环境在生产环境中，翻译会在构建阶段预先生成 (不会发起实时 API 调用) 。将 `translate` 命令添加到构建脚本中： ```json title="package.json" { "scripts": { "build": "npx gt translate && next build" } } ``` 在托管服务提供商 (Vercel、Netlify 等) 中设置 **production** 环境变量： ```bash GT_PROJECT_ID=your-project-id GT_API_KEY=gtx-api-your-production-key ``` 生产密钥以 `gtx-api-` 开头 (不是 `gtx-dev-`) 。可在 [dash.generaltranslation.com](https://dash.generaltranslation.com) 获取。绝不要添加 `NEXT_PUBLIC_` 前缀。就是这样——你的应用现已支持多语言。🎉 *** ## 故障排查 `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` 选项。 *** ## 后续步骤 **查看实际效果：**浏览[可运行的示例应用](/docs/next/tutorials/examples)，看看 `gt-next` 模式在真实项目中的应用，或直接前往[应用目录](https://app-catalog.generaltranslation.dev)。 * [**`` 组件指南**](/docs/next/guides/t) — 了解变量、复数形式和高级翻译模式 * [**字符串翻译指南**](/docs/next/guides/strings) — 深入了解 `useGT` 和 `getGT` * [**变数组件**](/docs/next/guides/variables) — 使用 ``、``、`` 和 `` 处理动态内容 * [**复数变化**](/docs/next/api/components/plural) — 使用 `` 组件处理复数形式 * [**翻译页面元数据**](/docs/next/api/strings/get-gt#metadata) — 使用 `getGT` 翻译标题、说明和 OG 标签 * [**部署到生产环境**](/docs/next/tutorials/quickdeploy) — 设置 CI/CD、缓存和性能优化 * [**共享字符串**](/docs/next/guides/shared-strings) — 使用 `msg()` 翻译数组、配置对象和共享数据中的文本