Next.js 快速上手
使用 gt-next 轻松为 Next.js 应用实现国际化
前提条件： Next.js App Router、基础 JavaScript 知识
安装
安装 gt-next 和 gtx-cli 包：
npm i gt-next 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配置
withGTConfig
withGTConfig 函数用于在你的 Next.js 应用中初始化 SDK。将其添加到 next.config.[js|ts] 文件中：
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// 您现有的 Next.js 配置
};
export default withGTConfig(nextConfig. {
// 其他 GT 配置选项
});GTProvider
GTProvider 组件为客户端组件提供翻译上下文。它负责管理 locale 状态和翻译，并启用 useGT 与 useTranslations 两个钩子。
将 GTProvider 添加到根布局中：
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}在项目根目录创建一个 gt.config.json 文件：
{
"defaultLocale": "en",
"locales": ["fr", "es", "de"]
}为你的项目自定义 locales。有关可用选项，请参阅受支持的 locales。
环境变量
在用于开发时热重载的 .env.local 文件中添加：
GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"仅限开发环境： 请不要在生产环境中设置 GT_API_KEY——它只用于开发时的热重载。
在 dash.generaltranslation.com 免费获取 API Keys，或运行：
npx gtx-cli auth使用
现在你可以开始为内容做国际化了。主要有两种方式：
使用 <T> 的 JSX 内容
将 JSX 元素用 <T> 组件包裹起来以进行翻译：
import { T } from 'gt-next';
function Welcome() {
return (
<T>
<h1>欢迎使用我们的应用程序！</h1>
</T>
);
}import { T, Var } from 'gt-next';
function Greeting({ user }) {
return (
<T>
<p>你好，<Var>{user.name}</Var>！</p>
</T>
);
}更多信息请参见《使用 <T> 组件》指南。
使用 useGT 处理纯文本字符串
适用于在 useGT 钩子中处理的属性、标签和纯文本：
import { useGT } from 'gt-next';
function ContactForm() {
const t = useGT();
return (
<input
placeholder={t('请输入您的邮箱')}
aria-label={t('邮箱输入框')}
/>
);
}对于服务器组件，请使用 getGT，而不要使用 useGT。
更多信息请参阅字符串翻译指南。
测试你的应用
通过切换语言来验证你的翻译效果：
-
使用
<LocaleSelector>添加一个语言/locale 下拉选择器：import { LocaleSelector } from 'gt-next'; function App() { return <LocaleSelector />; } -
启动开发服务器：
npm run devyarn run devbun run devpnpm run dev -
访问 localhost:3000，并通过下拉选择器切换语言。
在开发环境中，翻译为按需加载（会有短暂的加载时间）；在生产环境中，内容将预先完成翻译。
故障排查
部署
在生产环境中，需要预先完成内容翻译，因为运行时翻译已被禁用（<Tx> 和 tx 函数除外）。
-
从 dash.generaltranslation.com 获取生产环境 API key。
生产环境密钥以
gtx-api-开头（不同于开发环境密钥，其前缀为gtx-dev-）。了解更多环境差异。 -
将其添加到 CI/CD 环境：
GT_PROJECT_ID=your-project-id GT_API_KEY=gtx-api-your-production-key切勿为生产密钥添加
NEXT_PUBLIC_前缀——它们必须仅在服务端使用。 -
运行 translate 命令以翻译内容：
npx gtx-cli translate你可以通过
gt.config.json配置文件调整 translate 命令的行为。更多信息请参阅 CLI 工具 参考指南。
-
更新构建脚本，在构建前先执行翻译：
package.json { "scripts": { "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>" } }
下一步
这份指南怎么样？