Next.js 快速入门
使用 gt-next 轻松实现 Next.js 应用的国际化
概述
本快速入门指南将带您了解如何使用 gt-next 设置您的 Next.js 应用程序。
在本指南结束时，您将拥有一个已准备好开始内容翻译的 Next.js 应用。
在本指南中，我们将涵盖以下内容：
安装
配置
使用
测试您的应用
部署
前置条件
- 一个使用 App Router 的 Next.js 应用程序
- 对 Next.js 和 JavaScript 的基本了解
安装
安装 gt-next 和 gtx-cli 包：
npm i gt-next
npm i --save-dev gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cli自动设置： 我们有一个实验性的设置向导，可以帮助您使用 gt-next 设置项目。
通过运行 npx gtx-cli@latest 来试用。您仍需要手动国际化字符串，但它会帮助您开始。
查看设置向导参考指南了解更多信息。
或者，如果您希望您的 AI 工具（如 Claude Code、Cursor 或 Windsurf）自动设置您的项目， 您可以使用我们的 mcp server。
配置
withGTConfig
withGTConfig 函数是用于在 Next.js 应用程序中初始化 SDK 的函数。
将其放置在您的 next.config.[js|ts] 文件中。
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Your next.config.ts options
};
export default withGTConfig(nextConfig, {
// Additional GT configuration options
});查看 withGTConfig API 参考 了解更多信息。
GTProvider
gt-next 还导出了一个 GTProvider 组件。该组件用于为 Next.js 应用程序中的客户端组件提供上下文。
GTProvider 和 withGTConfig 协同工作，为您的应用程序提供上下文。
此上下文包括：
- 管理用户的当前语言环境
- 该语言环境的相关翻译
useGThook 的上下文useTranslationshook 的上下文
首先，将 GTProvider 组件添加到应用程序的根布局中。它应该尽可能高地放置在组件树中。
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}如果您有多个根布局，请在每个布局中都放置 GTProvider。
接下来，在项目根目录中创建一个 gt.config.json 文件。
此文件用于配置 gtx-cli 工具和 gt-next 库。
{
"defaultLocale": "en",
"locales": ["fr", "es"]
}您应该自定义 defaultLocale 和 locales 以匹配您的项目。查看支持的语言环境列表了解更多信息。
withGTConfig 将自动检测项目中的 gt.config.json 文件，并使用它来配置 SDK。
环境变量
设置以下环境变量：
GT_API_KEY="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID确保您的 API 密钥变量仅在开发环境中设置！它不应该在生产环境中设置。
您可以通过创建 General Translation 账户 获得免费的 API 密钥和项目 ID。
创建账户后，导航到开发 API 密钥页面获取您的开发 API 密钥和项目 ID。
或者，您也可以使用 CLI 工具命令 npx gtx-cli auth 为您的项目生成 API 密钥和项目 ID，保存到您的 .env.local 文件中。
使用方法
太好了！如果您已经按照上述步骤操作，您的 Next.js 应用现在已经设置好使用 gt-next 了。
下一步是国际化您的内容。 在这里，我们将简要概述在您的应用程序中翻译内容的不同方法。
<T> 组件
<T> 组件是在您的应用程序中翻译 JSX 内容的主要组件。
要使用它，只需将您想要翻译的 JSX 包装在 <T> 组件中。
import { T } from 'gt-next';
<T>
<div>Your content</div>
</T>如果您有动态内容，您需要使用变量组件来传入动态值。
import { T, Var } from 'gt-next';
<T>
<div>Hello, <Var>{name}</Var>!</div>
</T>查看翻译 JSX 指南了解更多信息。
useGT Hook
useGT hook 是一个 React hook，它返回一个可用于翻译字符串的函数。
import { useGT } from 'gt-next'
const translate = useGT();
translate('Hello, world!');useGT hook 可以在客户端和服务器端组件中使用。
对于异步组件，请使用异步的 getGT() 函数。
查看翻译字符串 指南了解更多信息。
利用热重载翻译功能将有助于国际化您的应用程序。
要启用此功能，请确保在您的开发环境中设置了 GT_API_KEY 和 GT_PROJECT_ID 环境变量。
测试你的应用
恭喜你！🥳 如果你已经按照上面的步骤操作，你的应用现在已经支持多语言了！让我们来看看它的实际效果吧。
在不同语言下查看你的应用
将 <LocaleSelector> 组件添加到你的应用中。
这样你就可以为你的应用选择不同的语言了。
提示： 你也可以跳过这一步，直接在浏览器设置中更改你的语言。
以开发模式启动你的 Next.js 应用。
npm run dev yarn run dev bun run dev pnpm run dev 在你喜欢的浏览器中打开你的应用（通常地址为 http://localhost:3000）。
故障排查
部署
太好了！如果你对你的翻译和应用的功能感到满意，现在可以部署你的应用程序了。
gt-next 在生产环境下的行为与开发环境略有不同。具体来说，除了 <Tx> 组件和 tx 函数外，运行时不会进行任何翻译。
这意味着你需要在部署应用程序之前，在构建过程中完成内容的翻译。
幸运的是，gtx-cli 工具提供了一个 translate 命令，可以自动翻译你的内容。
首先，你需要从 General Translation platform 获取一个生产环境 API 密钥。
请注意，这个密钥与你的开发环境 API 密钥不同，并且以 gtx-api- 开头，而不是 gtx-dev-。
你可以在这里了解开发环境和生产环境密钥的区别。
将这个环境变量添加到你的 CI/CD 流水线中。
GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>请确保 GT_API_KEY 不要 以 NEXT_PUBLIC_ 作为前缀！
如果加上了，你的 API 密钥可能会被公开暴露。
运行 translate 命令来翻译你的内容。
npx gtx-cli translate你可以通过 gt.config.json 文件配置 translate 命令的行为。
更多信息请参阅 CLI 工具 参考指南。
将 translate 命令添加到你的构建流程中。
{
"scripts": {
"build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
}
}总结
- 在本指南中，我们介绍了如何使用
gt-next设置你的 Next.js 应用 - 我们简要介绍了在应用中翻译内容的不同方法。
- 我们还讲解了在内容国际化后如何部署你的应用。
下一步
这份指南怎么样？