概览

本指南将带你逐步使用 General Translation 的 CLI 工具（gtx-cli）为你的项目提供翻译。

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

该 CLI 工具负责将你的项目连接至 General Translation 的 AI 翻译服务。

你可以通过多种方式使用 CLI 工具，请根据你的使用场景跳转到相应章节。

安装

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

npm i 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 教程完成对代码库的设置。

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

npx gtx-cli configure

2. 接下来，你需要在 General Translation dashboard 中创建一个项目。

创建项目后，你需要生成用于生产环境的 API key。前往 “API Keys” 页面并点击 “Create API Key” 按钮。

3. 然后，将你的 API key 和 project 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 文件，包含一些基础配置，例如项目的默认 locale 和支持的 locales。

2. 接下来，你需要在 General Translation 控制台 中创建一个项目。

创建项目后，你需要生成用于生产环境的 API key。前往“API Keys”页面并点击“Create API Key”按钮。

3. 然后，将你的 API key 和项目 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

此命令会为你的默认 locale 以及在项目中配置的所有其他 locales 生成一个源文件。

每个文件的内容相同，并会与项目中已有的任何历史译文合并。

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

注意事项

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

后续步骤

• 请参阅CLI API 参考以了解更多信息。