概览

本指南将带你逐步了解如何使用 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 教程，将代码库配置为使用 gt-next 或 gt-react。

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

npx gtx-cli configure

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

请参阅API 参考以了解 translate 命令的更多信息。

翻译语言文件（第三方 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 dashboard 中创建一个项目。

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

3. 然后，将你的 API key 和 project ID 添加到环境变量中。

GT_API_KEY=<你的 API 密钥>
GT_PROJECT_ID=<你的项目 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（内容分发网络）时，选择“否”。

2. 运行：

npx gtx-cli generate

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

每个文件的内容相同，并会与项目中之前的任何翻译合并。

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

注意事项

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

下一步

• 查看CLI API 参考以了解更多信息。