迁移
了解如何将项目迁移至 gt-next
概览
本指南将介绍如何将已使用 i18n 库的项目迁移到 gt-next 的具体步骤。
我们还将提供一些实用提示与建议，帮助您尽可能顺利地完成迁移。
先决条件
- 一个目前使用其他 i18n 库的项目。
- 对
gt-next库有基本了解。
为什么迁移？
将你的项目迁移到 gt-next 的理由有很多。
以下仅举几例：
- 告别 JSON 文件： 再也不需要在 JSON 文件中管理翻译。 所有内容都与代码内联，放在最合适的位置。
- 自动翻译： 使用我们的 CLI（命令行界面）工具生成高质量、上下文感知的翻译。 再也不用等待翻译到位。
- 在开发环境中试验： 在开发阶段轻松试验翻译，支持翻译热重载。
设置
安装 gt-next 和命令行工具 gtx-cli（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在项目根目录创建一个 gt.config.json 文件，其中包含 defaultLocale 属性和 locales 数组。
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}然后，将 <GTProvider> 组件添加到应用的根布局。
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}接着，在 next.config.js 中添加 withGTConfig。
import withGTConfig from 'gt-next/config'
const nextConfig = {
// Your next.config.ts options
}
export default withGTConfig(nextConfig, {
// Your GT configuration
})更详细的步骤请参阅快速入门指南。
现在你有 3 个选项：
- 将整个项目完全迁移到
gt-next，并移除旧的 i18n 库。 - 完全迁移项目，但继续使用旧 i18n 库的 dictionaries。
- 暂时保留旧的 i18n 库，仅将项目的部分迁移到
gt-next。
各选项的更多详情，请参见迁移策略部分。
迁移策略
选项 1：完整迁移整个项目
这是最直接的做法，但也意味着需要在一次提交中进行最多的代码修改。
在完成项目设置后，你需要搜索所有旧版 i18n 库的使用并将其替换为 gt-next。
如果你的应用使用了 React hooks（例如 useTranslations），请在代码库中搜索所有出现的 useTranslations 并将其替换为 useGT。
接着，你需要把所有字符串键替换为对应的实际字符串值。
例如，如果你的旧代码如下所示：
{
"hello": {
"description": "你好，世界！"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}你需要将它替换为：
export default function MyComponent() {
const t = useGT()
return <div>{t('你好,世界!')}</div>
}
// 或
export default function MyComponent() {
return <T>你好,世界!</T>
}对你旧版 i18n 库的所有使用处都执行此操作。
选项 2：完整迁移项目，但继续使用旧 i18n 库的 dictionaries
假设你想把项目迁移到 gt-next，但仍希望继续使用旧 i18n 库的 dictionaries，
并只在新增内容中使用 GT 的内联功能。
在这种情况下，你可以采用与选项 1 类似的方法：
找到旧 i18n 库的所有使用位置，例如 useTranslations hooks，并将它们替换为来自 gt-next 的 useTranslations hooks。
useTranslations hook 的行为与其他 i18n 库中的 useTranslations hooks 非常相似，你可以用相同的方式使用它。
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}在配置方面，你需要在项目根目录或 src 目录下创建一个 dictionary.[js|ts|json] 文件。
将旧 dictionary 文件的内容复制到这个新文件中。
next.config.js 中的初始化函数 withGTConfig 会自动检测项目根目录或 src 目录下的 dictionary 文件。
参见 dictionaries 指南了解更多详情。
选项 3：暂时继续使用旧的 i18n 库，仅将项目的部分内容迁移到 gt-next
该选项灵活性最高，一次性所需的代码改动最少。
在这种情况下，你可以采取与选项 2 相似的做法，但只将项目的一部分迁移到 gt-next。
例如，你可以在部分组件中继续使用旧的 i18n 库，仅在其他组件和新增内容中使用 gt-next。
不推荐该选项，因为你需要在同一项目中同时维护两套不同的 i18n 库，这可能较为复杂并且容易引发错误。
迁移建议
1. 尽量使用 useGT 钩子或 <T> 组件
在条件允许时，我们建议优先使用 useGT 钩子或 <T> 组件。
这样做将使后续编辑内容更容易，也能让你的代码库更易读。
2. 将 useTranslations 钩子用于现有内容
useTranslations 钩子能让你继续沿用现有的 dictionaries。
我们提供它是为了简化迁移流程，但不建议在新内容中使用。
3. 使用 AI
如果您使用 AI 协助迁移项目，我们提供了 LLMs.txt 和 LLMs-full.txt，可在以下位置获取：
本指南如何?