迁移
了解如何将项目迁移到 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 的 hook（如 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>
}
// OR
export default function MyComponent() {
return <T>你好，世界！</T>
}对旧版 i18n 库的所有用例都执行此操作。
选项 2：完全迁移项目，但继续使用旧 i18n 库的 dictionaries
假设你要将项目迁移到 gt-next，但仍希望继续使用旧 i18n 库的 dictionaries，
并仅在新增内容中使用 GT 的内联功能。
在这种情况下，你可以采用与选项 1 类似的做法：
找到旧 i18n 库的所有使用处，例如 useTranslations 钩子，并将它们替换为来自 gt-next 的 useTranslations 钩子。
useTranslations 钩子的行为与其他 i18n 库中的 useTranslations 十分相似，你可以以同样的方式使用它。
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] 文件。
将旧字典文件的内容复制到该新文件中。
next.config.js 中的初始化函数 withGTConfig 会自动拾取项目根目录或 src 目录下的字典文件。
参阅 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：
这份指南怎么样？