# gt-react: General Translation React SDK: 迁移
URL: https://generaltranslation.com/zh/docs/react/guides/migration.mdx
---
title: 迁移
description: 了解如何将项目迁移至 gt-react
---

{/* 自动生成：请勿直接编辑。请在 content/docs-templates/ 中编辑 template。 */}


## 概述

本指南将介绍将已在使用 i18n 库的项目迁移到 `gt-react` 所需的步骤。

我们还会提供一些提示和建议，帮助你尽可能顺利地完成迁移。

## 前提条件

* 你当前有一个正在使用其他 i18n 库的项目。
* 对 `gt-react` 库有基本了解。

## 为什么要迁移？

你可能有很多理由想把项目迁移到 `gt-react`。

这里只列出几个：

* **不再需要 JSON 文件：** 无需再用 JSON 文件管理翻译。
  所有内容都直接和代码写在一起，各归其位。
* **自动翻译：** 使用我们的 CLI 工具生成高质量、具备上下文感知能力的翻译。
  你再也不用等待翻译完成了。
* **在开发环境中试验：** 借助翻译热重载，轻松在开发环境中试验翻译效果。

## 设置

<Steps>
  <Step>
    安装 `gt-react` 和 `gt` CLI 工具。

    <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
      <Tab value="npm">
        ```bash
        npm i gt-react
        npm i gt
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add gt-react
        yarn add --dev gt
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add gt-react
        bun add --dev gt
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add gt-react
        pnpm add --save-dev gt
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    在项目根目录创建一个 `gt.config.json` 文件，其中包含 `defaultLocale` 属性和 `locales` 数组。

    ```json title="gt.config.json" copy
    {
      "defaultLocale": "en",
      "locales": ["en", "fr", "es"]
    }
    ```

    将 `<GTProvider>` 组件添加到应用根部，并将 `config` 对象展开为属性传入。

    ```tsx
    import { GTProvider } from 'gt-react'
    import config from './gt.config.json'

    <GTProvider {...config}>
      <App />
    </GTProvider>
    ```

    更详细的步骤请参阅[项目快速入门](/docs/react)指南。
  </Step>

  <Step>
    此时，你有 3 个选项：

    1. 将整个项目完全迁移到 `gt-react`，并移除旧的 i18n 库。
    2. 完全迁移项目，但继续使用旧 i18n 库中的字典。
    3. 暂时继续使用旧的 i18n 库，只将项目的一部分迁移到 `gt-react`。

    各选项的详细说明请参阅[迁移策略](#strategies)部分。
  </Step>
</Steps>

## 迁移策略 [#strategies]

### 选项 1：完整迁移整个项目

这个方案最直接，但也意味着你需要一次性修改最多的代码。

设置好项目后，你需要找出旧 i18n 库的所有使用位置，并将其替换为 `gt-react`。

如果你的应用使用了 React Hook (如 `useTranslation`) ，请在代码库中搜索所有 `useTranslation` 的使用位置，并将其替换为 `useGT`。

然后，你还需要把所有字符串键替换成对应的实际字符串值。

例如，如果你之前的代码如下：

```json title="dictionary.json"
{
  "hello": {
    "description": "Hello, world!"
  }
}
```

```tsx
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}
```

你需要把它替换为：

```tsx
export default function MyComponent() {
  const { t } = useGT()
  return <div>{t('Hello, world!')}</div>
}
// 或
export default function MyComponent() {
  return <T>Hello, world!</T>
}
```

对旧 i18n 库的所有使用处都这样处理。


### 选项 2：完全迁移你的项目，但继续使用旧 i18n 库中的字典

假设你想把项目迁移到 `gt-react`，但仍希望继续使用旧 i18n 库中的字典，
并且只对新内容使用 GT 的内联功能。

在这种情况下，你可以采用与选项 1 类似的做法：

找出旧 i18n 库的所有用法，例如 `useTranslation` Hook，并将它们替换为 `useTranslations` Hook。

`useTranslations` Hook 的行为与 `useTranslation` Hook 非常相似，用法也基本一致。

<Tabs items={['Before', 'After']}>
  <Tab value="Before">
    ```tsx
    import { useTranslation } from 'react-i18next'
    export default function MyComponent() {
      const { t } = useTranslation()
      return <div>{t('hello.description')}</div>
    }
    ```
  </Tab>

  <Tab value="After">
    ```tsx
    import { useTranslations } from 'gt-react'
    export default function MyComponent() {
      const t = useTranslations()
      return <div>{t('hello.description')}</div>
    }
    ```
  </Tab>
</Tabs>

在设置方面，你需要在项目根目录或 `src` 目录下创建一个 `dictionary.[js|ts|json]` 文件。
将旧字典文件中的内容复制到这个新文件中，然后把它传给 `GTProvider` 组件。

```tsx
import { GTProvider } from 'gt-react'
import dictionary from './dictionary.json'
import config from './gt.config.json'

<GTProvider {...config} dictionary={dictionary}>
  <App />
</GTProvider>
```

更多详情请参阅[字典](/docs/react/guides/dictionaries)指南。


### 方案 3：暂时继续使用旧的 i18n 库，只将项目的一部分迁移到 `gt-react`

这个方案最灵活，而且一次性需要修改的代码最少。

在这种情况下，你可以采用与方案 2 类似的做法，但只将项目的一部分迁移到 `gt-react`。

例如，你可以继续在某些组件中使用旧的 i18n 库，只在其他组件和新内容中使用 `gt-react`。

<Callout type="warn">
  不建议使用此方案，因为你需要在项目中同时维护两个不同的 i18n 库，这会增加复杂性，也可能导致 bug。
</Callout>

## 迁移建议

### 1. 尽可能使用 `useGT` Hook 或 `<T>` 组件

在条件允许的情况下，我们建议尽量使用 `useGT` Hook 或 `<T>` 组件。

这样一来，后续编辑内容会更轻松，代码库的可读性也会更高。

### 2. 对现有内容使用 `useTranslations` Hook

`useTranslations` Hook 是继续使用现有字典的一种很好的方式。

我们提供它是为了让迁移更容易，但不建议将它用于新内容。

### 3. 使用 AI

如果你正借助 AI 辅助迁移项目，我们提供了 `LLMs.txt` 和 `LLMs-full.txt`，可通过以下链接获取：

* [LLMs.txt](/llms.txt)
* [LLMs-full.txt](/llms-full.txt)

这些文件包含了本文档的全部内容，因此你的 AI 工具可以获取帮助你迁移项目所需的全部信息。