使用指南

概述

本指南将带您了解如何使用 General Translation 的 CLI 工具（gtx-cli）来翻译您的项目。

该 CLI 工具兼容任何 i18n 库，无论您使用的是 gt-next、gt-react，还是第三方库，如 next-intl 或 react-i18next。

CLI 工具负责将您的项目连接到 General Translation 的 AI 翻译服务。

CLI 工具有多种使用方式，请根据您的使用场景跳转到相关章节。

安装

要安装 CLI 工具，请运行以下命令：

npm i --save-dev gtx-cli

yarn add --dev gtx-cli

bun add --dev gtx-cli

pnpm add --save-dev gtx-cli

使用场景

翻译 GT 项目

CLI 工具可用于翻译使用 gt-next 或 gt-react 的项目。

本指南假设您已经根据 gt-next 或 gt-react 教程设置了代码库来使用 gt-next 或 gt-react。

1. 首先，您需要配置项目的 GT 设置。

npx gtx-cli configure

2. 接下来，您需要在 General Translation 仪表板 中创建一个项目。

创建项目后，您需要生成一个生产 API 密钥。导航到"API Keys"页面并点击"Create API Key"按钮。

3. 然后，将您的 API 密钥和项目 ID 添加到环境变量中。

GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>

4. 最后，运行翻译命令。

npx gtx-cli translate

有关 translate 命令的更多信息，请参阅 API 参考。

翻译语言文件（第三方 i18n 库或独立 GT 项目）

CLI 工具允许您为第三方 i18n 库或使用 gt-next 或 gt-react 的独立实现翻译语言文件。

大多数 i18n 库依赖 JSON 文件来存储翻译数据。 CLI 工具可用于自动将这些 JSON 文件翻译成您所需的语言。

1. 首先，您需要配置项目的 GT 设置。

npx gtx-cli configure

此命令将在项目根目录中创建一个 gt.config.json 文件，包含一些基本配置设置，如项目的默认语言环境和支持的语言环境。

2. 接下来，您需要在 General Translation 仪表板 中创建一个项目。

创建项目后，您需要生成一个生产 API 密钥。导航到"API Keys"页面并点击"Create API Key"按钮。

3. 然后，将您的 API 密钥和项目 ID 添加到环境变量中。

GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>

4. 最后，运行翻译命令。

npx gtx-cli translate

为 GT 项目生成语言文件

CLI 工具可用于为使用 gt-next 或 gt-react 的项目生成语言文件。

如果你希望使用自己的翻译服务商，这个用例会很有用。

与其他 i18n 库不同，gt-next 和 gt-react 支持内联翻译，这意味着没有传统的 JSON 文件结构来为每种语言存储键值对。

这意味着为了追踪文本的更改，GT 库会在源代码中存储原始文本的哈希值。

这种内部数据结构（包含哈希值）不便于操作，因此 CLI 工具提供了一个便捷的命令来为你的项目生成语言文件。

1. 首先，你需要配置项目的 GT 设置。

npx gtx-cli configure

当被询问是否要将翻译保存到 GT CDN 时，选择“No”选项。

2. 运行：

npx gtx-cli generate

此命令会为你的默认语言环境以及你为项目配置的所有其他语言环境生成一个源文件。

每个文件的内容都是相同的，并且会与你项目中已有的任何翻译合并。

更多关于 generate 命令的信息，请参见 API 参考。

注意事项

• gtx-cli translate 用于为你的项目自动生成翻译。
• 如果你正在使用第三方 i18n 库，可以在每次项目变更时自动更新所有翻译 JSON 文件。只需在构建或 CD 流程中的构建命令之前添加 gtx-cli translate 命令，即可自动为你的项目添加翻译。

后续步骤

• 有关更多信息，请参阅 CLI API 参考。
• 如果你想在开发过程中看到实时翻译（类似热重载），请查看 <T> 组件。