迁移

概述

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

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

前置条件

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

为什么要迁移？

你可能有很多理由想要将你的项目迁移到 gt-next。

以下是其中的一些原因：

不再需要 JSON 文件： 再也不用在 JSON 文件中管理翻译了。所有内容都与代码内联存放，归于其应在之处。
自动翻译： 使用我们的 CLI 工具生成高质量、具备上下文感知的翻译。你再也不用等待翻译完成。
开发环境中实验： 在开发环境中轻松尝试翻译，支持翻译热重载。

设置

安装 gt-next 和 gtx-cli CLI 工具。

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

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

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

gt.config.json

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

然后，将 <GTProvider> 组件添加到应用的根布局中。

app/layout.tsx

import { GTProvider } from 'gt-next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  )
}

接下来，将 withGTConfig 添加到您的 next.config.js 文件中。

next.config.ts

import withGTConfig from 'gt-next/config'
const nextConfig = {
  // Your next.config.ts options
}
export default withGTConfig(nextConfig, {
  // Your GT configuration
})

更详细的步骤请参见快速开始指南。

此时，您有 3 个选择：

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

有关每个选择的更多详细信息，请参见迁移策略部分。

迁移策略

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

这个选项是最直接的，但也需要一次性进行最多的代码更改。

在设置好项目后，你需要搜索旧 i18n 库的所有实例，并将它们替换为 gt-next。

如果你的应用使用了 React hooks，比如 useTranslations，请在代码库中搜索所有 useTranslations 实例，并将它们替换为 useGT。

然后，你需要将所有字符串键替换为它们的实际字符串值。

例如，如果你的旧代码是这样的：

dictionary.json

{
  "hello": {
    "description": "Hello, world!"
  }
}

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

你需要将其替换为：

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-next，但想继续使用旧 i18n 库的字典，并且只对新内容使用 GT 内联功能。

在这种情况下，你可以做类似选项 1 的事情：

找到旧 i18n 库的所有实例，比如 useTranslations hooks，并将它们替换为 gt-next 的 useTranslations hooks。

useTranslations hook 的行为与其他 i18n 库中的 useTranslations hooks 非常相似，你可以以相同的方式使用它。

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

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