概览

本指南将讲解如何将已使用某个 i18n 库的项目迁移到 gt-react 的具体步骤。

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

先决条件

• 一个已在使用其他 i18n 库的项目。
• 对 gt-react 库的基础了解。

为什么迁移？

将你的项目迁移到 gt-react 的理由有很多。

以下是其中的一些：

• 告别 JSON 文件： 再也不用在 JSON 文件里管理翻译了。 你的所有文案都与代码内联，回到最合适的位置。
• 自动翻译： 使用我们的 CLI 工具生成高质量、具备上下文感知的翻译。 你再也不用为等待翻译而发愁。
• 开发环境中试验： 在开发阶段轻松试验翻译，支持翻译热重载。

设置

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

{
  "defaultLocale": "en",
  "locales": ["en", "fr", "es"]
}

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

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

迁移策略

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

这个选项最为直接，但也意味着需要在一次迭代中进行最多的代码改动。

完成项目设置后，你需要搜索旧 i18n 库的所有使用位置，并将其替换为 gt-react。

如果你的应用使用了 React hooks（例如 useTranslation），请在代码库中搜索所有 useTranslation 的引用，并将它们替换为 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-react，但仍希望沿用旧 i18n 库中的 dictionaries， 并仅在新内容中使用 GT 的行内特性。

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

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

useTranslations hook 的行为与 useTranslation hooks 非常相似，你可以以相同方式使用它。

import { useTranslation } from 'react-i18next'
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

import { useTranslations } from 'gt-react'
export default function MyComponent() {
  const t = useTranslations()
  return <div>{t('hello.description')}</div>
}

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

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

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

更多详情请参阅dictionaries指南。

选项 3：暂时继续使用旧版 i18n 库，仅将项目的部分内容迁移到 gt-react

这是最灵活的选项，一次性需要修改的代码也最少。

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

例如，你可以在部分组件中继续使用旧版 i18n 库，而在其他组件和新增内容中仅使用 gt-react。

迁移指南

1. 尽量使用 useGT 钩子或 <T> 组件

在可行的情况下，我们建议使用 useGT 钩子或 <T> 组件。

这将使后续编辑内容更轻松，并让代码库更易于阅读。

2. 对现有内容使用 useTranslations 钩子

useTranslations 钩子非常适合继续沿用你现有的 dictionaries。

我们提供它是为了方便迁移，但不建议在新内容中使用。

3. 使用 AI

如果你使用 AI 来协助迁移项目，我们提供了 LLMs.txt 和 LLMs-full.txt：

• LLMs.txt
• LLMs-full.txt

这些文件包含本手册的全部内容，你的 AI 工具可据此获取所需的所有信息，帮助你完成项目迁移。