# gt-next: General Translation Next.js SDK: 迁移
URL: https://generaltranslation.com/zh/docs/next/guides/migration.mdx
---
title: 迁移
description: 了解如何将项目迁移至 gt-next
---
## 概述
本指南将介绍把已在使用 i18n 库的项目迁移到 gt-next 所需的步骤。
我们还会提供一些技巧和建议，帮助你尽可能顺利地完成迁移。
## 前提条件
* 当前使用其他 i18n 库的项目。
* 对 `gt-next` 库有基本的了解。
## 为什么要迁移？
你可能会出于很多原因，想把项目迁移到 gt-next。
这里仅举几例：
* **无需再使用 JSON 文件：** 不必再用 JSON 文件管理翻译。
所有内容都直接和代码写在一起，各归其位。
* **自动翻译：** 使用我们的 CLI 工具生成高质量、具备上下文感知能力的翻译。
再也不用苦等翻译完成。
* **在开发环境中试验：** 借助翻译热重载，轻松在开发过程中试验翻译效果。
## 设置
安装 `gt-next` 和 `gt` CLI 工具。
```bash
npm i gt-next 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
```
在项目根目录下创建 `gt.config.json` 文件，并添加 `defaultLocale` 属性和 `locales` 数组。
```json title="gt.config.json" copy
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}
```
然后，将 `` 组件添加到应用的根布局中。
```tsx title="app/layout.tsx" copy
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
接着，在你的 `next.config.js` 文件中添加 `withGTConfig`。
```js title="next.config.ts" copy
import { withGTConfig } from 'gt-next/config'
const nextConfig = {
// 你的 next.config.ts 选项
}
export default withGTConfig(nextConfig, {
// 你的 GT 配置
})
```
更详细的步骤请参阅[快速入门指南](/docs/next)。
此时，你有 3 个选项：
1. 将整个项目完全迁移到 `gt-next`，并移除旧的 i18n 库。
2. 将整个项目完全迁移，但继续使用旧 i18n 库中的字典。
3. 暂时继续使用旧的 i18n 库，只将项目的一部分迁移到 `gt-next`。
如需了解每个选项的更多细节，请参阅[迁移策略](#strategies)部分。
## 迁移策略 [#strategies]
### 选项 1：完整迁移整个项目
这是最直接的方案，但也需要一次性修改最多的代码。
设置好项目后，你需要搜索项目中所有旧 i18n 库的使用位置，并将它们替换为 `gt-next`。
如果你的应用使用了 React Hook (例如 `useTranslations`) ，请在代码库中搜索所有 `useTranslations` 的使用位置，并将其替换为 `useGT`。
接下来，你还需要将所有字符串键替换为对应的实际字符串值。
例如，如果你之前的代码是这样的：
```json title="dictionary.json"
{
"hello": {
"description": "Hello, world!"
}
}
```
```tsx
export default function MyComponent() {
const { t } = useTranslation()
return {t('hello.description')}
}
```
你需要将其替换为：
```tsx
export default function MyComponent() {
const gt = useGT()
return {gt('Hello, world!')}
}
// 或
export default function MyComponent() {
return Hello, world!
}
```
对旧 i18n 库的所有使用处都这样做。
### 选项 2：完全迁移项目，但继续使用旧 i18n 库中的字典
假设你想把项目迁移到 `gt-next`，但仍希望继续使用旧 i18n 库中的字典，
并且只对新内容使用 GT 的内联功能。
在这种情况下，你可以采用与选项 1 类似的做法：
找到旧 i18n 库中的所有用法，例如 `useTranslations` Hook，并将它们替换为 `gt-next` 提供的 `useTranslations` Hook。
`useTranslations` Hook 的行为与其他 i18n 库中的 `useTranslations` Hook 非常相似，因此你可以用同样的方式使用它。
```tsx
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return {t('hello.description')}
}
```
```tsx
import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return {t('hello.description')}
}
```
在配置方面，你需要在项目根目录或 `src` 目录下创建一个 `dictionary.[js|ts|json]` 文件。
然后将旧字典文件中的内容复制到这个新文件里。
`next.config.js` 中用于初始化的 `withGTConfig` 函数会自动读取项目根目录或 `src` 目录下的字典文件。
更多详情请参阅 [dictionaries](/docs/next/guides/dictionaries) 指南。
### 方案 3：暂时继续使用旧的 i18n 库，只将项目的部分内容迁移到 `gt-next`
这是最灵活的方案，而且一次性需要改动的代码最少。
在这种情况下，你可以采用与方案 2 类似的做法，但只将项目的部分内容迁移到 `gt-next`。
例如，你可以继续在某些组件中使用旧的 i18n 库，只在其他组件和新内容中使用 `gt-next`。
不建议采用此方案，因为你需要在项目中同时管理两个不同的 i18n 库，这会增加复杂性，也可能导致 bug。
## 迁移建议
### 1. 尽可能使用 `useGT` Hook 或 `` 组件
只要条件允许，我们都建议优先使用 `useGT` Hook 或 `` 组件。
这样一来，今后编辑内容会更方便，代码库的可读性也会更高。
### 2. 对现有内容使用 `useTranslations` Hook
`useTranslations` Hook 非常适合继续沿用你现有的字典。
我们提供它是为了让迁移更轻松，但不建议将它用于新内容。
### 3. 使用 AI
如果你在使用 AI 辅助项目迁移，我们提供了 `LLMs.txt` 和 `LLMs-full.txt`，可通过以下地址获取：
* [LLMs.txt](/llms.txt)
* [LLMs-full.txt](/llms-full.txt)