# react-native: 迁移
URL: https://generaltranslation.com/zh/docs/react-native/guides/migration.mdx
---
title: 迁移
description: 了解如何将项目迁移到 gt-react-native
---

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


## 概述

本指南将介绍如何将已使用 i18n 库的项目迁移到 `gt-react-native`，以及所需的步骤。

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

## 前提条件

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

## 为什么要迁移？

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

这里只举几个例子：

* **不再需要 JSON 文件：** 无需再用 JSON 文件管理翻译。
  所有内容都直接和代码写在一起，本来就该如此。
* **自动翻译：** 使用我们的 CLI 工具生成高质量、结合上下文的翻译。
  你再也不用等翻译了。
* **在开发时试验：** 借助翻译热重载，轻松在开发环境中试验翻译效果。

## 设置

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

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

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

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

      <Tab value="pnpm">
        ```bash
        pnpm add gt-react-native
        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-native'
    import config from './gt.config.json'

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

    如需更详细的步骤，请参阅[项目快速开始](/docs/react-native)指南。
  </Step>

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

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

    如需了解每个选项的更多细节，请参阅[迁移策略](#strategies)部分。
  </Step>
</Steps>

## 迁移策略 [#strategies]

### 方案 1：完整迁移整个项目

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

设置好项目后，你需要搜索旧 i18n 库的所有使用位置，并将它们替换为 `gt-react-native`。

如果你的应用使用了 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-native`，但仍想继续使用旧 i18n 库中的字典，
并且只对新内容使用 GT 的内联功能。

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

找出项目中所有旧 i18n 库的使用位置，例如 `useTranslation` Hook，并将它们替换为 `useTranslations` Hook。

`useTranslations` Hook 的行为与 `useTranslation` Hook 非常相似，因此你可以用同样的方式使用它。

<Tabs items={['之前', '之后']}>
  <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-native'
    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-native'
import dictionary from './dictionary.json'
import config from './gt.config.json'

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

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

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

这个选项最灵活，而且一次性需要改动的代码最少。

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

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

<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 工具可以获取协助你迁移项目所需的全部信息。