概览

本指南将介绍如何将已使用某款 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 库的字典

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

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

找到旧 i18n 库的所有使用位置，例如 useTranslation 钩子，并将它们替换为 useTranslations 钩子。

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

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 工具即可访问所需的所有信息，帮助你完成项目迁移。