# General Translation React SDKs (gt-react, gt-next, gt-react-native): 迁移 i18n 库
URL: https://generaltranslation.com/zh/docs/react/guides/migrating-i18n-libraries.mdx
---

title: 迁移 i18n 库
description: 如何将现有 React 国际化设置迁移至 General Translation，同时保留当前翻译。
related:
  links:
    - /docs/react/guides/translating-with-dictionaries
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/configuring

---

每次迁移一个完整功能或路由，以便在迁移过程中持续测试区域设置选择、翻译输出和后备内容行为。

## 开始之前 [#before-start]

完成所用框架的 Quickstart，并让现有 i18n provider 保持启用状态，直到其最后一个使用方完成迁移：

* [React SPA Quickstart](/docs/react/react-spa-quickstart)
* [Next.js Quickstart](/docs/react/nextjs-quickstart)
* [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart)
* [React Native Quickstart](/docs/react/react-native-quickstart)

记录当前的源区域设置、支持的区域设置、后备内容行为和区域设置 URL 格式。迁移内容前，请在 `gt.config.json` 中使用相同的值。

## 选择迁移策略 [#strategies]

### 使用源内容替换键

如果希望可翻译文案与渲染它的组件放在一起，请选择此方法。

对于 JSX，使用 [`<T>`](/docs/react/reference/components/t) 替换键查找；对于字符串，使用 [`useGT`](/docs/react/reference/hooks/use-gt)：

```tsx
// 迁移前
const { t } = useTranslation();
return <h1>{t('home.welcome')}</h1>;

// 迁移后
return (
  <T>
    <h1>Welcome back</h1>
  </T>
);
```

从旧字典中复制源区域设置的值，而非翻译后的值。General Translation 会将该源内容及其周围结构作为翻译上下文。

### 保留现有字典

如果稳定的键是内容工作流的一部分，或没有必要替换所有查找操作，请选择此方案。

将源字典移至[字典设置](/docs/react/guides/translating-with-dictionaries)，然后用 [`useTranslations`](/docs/react/reference/hooks/use-translations) 替换旧钩子：

```tsx
// 迁移前
import { useTranslation } from 'react-i18next';

const { t } = useTranslation();
return <h1>{t('home.welcome')}</h1>;

// 迁移后
import { useTranslations } from 'gt-react';

const t = useTranslations();
return <h1>{t('home.welcome')}</h1>;
```

在 Next.js 中，将 `dictionary.json`、`dictionary.ts` 或 `dictionary.js` 放在项目根目录或 `src/` 目录下。[`withGTConfig`](/docs/react/nextjs/config) 会自动检测。

### 暂时同时运行两个库

如果要在独立部署的路由或功能之间分阶段迁移，请选择此方法。两个库可以同时运行；如果两个集成都使用 provider，这些 provider 也可以共存。每个字符串应由一个库负责翻译，且两个库必须使用相同的活动区域设置。

<Callout type="warn">
  两个 i18n 库可能会对活动区域设置、cookie、URL 路由和后备内容规则产生不一致的理解。请确定唯一的区域设置来源，测试已迁移和未迁移路由之间的导航，并在旧 provider 的最后一个使用方不再使用后立即将其移除。
</Callout>

## 迁移一个功能 [#migrate-feature]

1. 选择一个路由或组件，列出它读取的所有旧翻译键。
2. 复制源区域设置中的文本，以及所有插值和复数规则。
3. 根据所选策略，将每个查找替换为 [`<T>`](/docs/react/reference/components/t)、[`useGT`](/docs/react/reference/hooks/use-gt) 或 [`useTranslations`](/docs/react/reference/hooks/use-translations)。
4. 保留变量本身，不要将其当前值插入源文本。
5. 运行 [`npx gt translate`](/docs/cli/reference/commands/translate)。
6. 测试源区域设置、所有目标区域设置、缺失翻译时的后备内容以及区域设置切换。
7. 仅当 repository 中不再引用旧键时，才移除旧键。

重复此流程，直到旧 provider 和依赖项不再被使用，然后移除其配置、生成的文件和 build 命令。

## 保留现有翻译 [#preserve-translations]

保留源字典可保留键，但现有目标语言文件不会自动导入 General Translation。迁移期间请继续加载这些字典，或通过 [Core 上传工作流](/docs/platform/core/reference/gt-class-methods/translation/upload-translations)上传已审校的翻译。

不要将翻译后的字符串手动复制到 [`<T>`](/docs/react/reference/components/t) 中作为源内容。请在代码中保留原始源语言，并根据同一源版本核对导入的翻译。
## Next steps

- /docs/react/guides/translating-with-dictionaries
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/configuring