概览

在 gtx-cli 2.3.0 中，我们更新了 translate 和 upload 命令的行为，并提升了翻译流水线的可观测性。

Translate

过去，translate 会同时触发翻译操作 并且 在后台执行一次性的项目初始化（生成你在 dashboard 上看到的上下文和术语表）。

在较小的项目中，这个过程很快；但在较大的代码库中，初始化可能耗时过长，触发超时，看起来就像翻译失败了一样。

虽然用户会以为 translate 失败了，但初始化实际上会异步完成，翻译也会生成但不会被下载，导致体验不完整且令人困惑。

Setup

Setup 现在是一个单独的步骤。我们对它进行了优化，使超时变得极少。

但因为我们意识到 setup 仍然可能失败，翻译流程不再“依赖” setup 成功完成。现在的流水线大致如下：

• Upload： 发送文件并确认成功。
• Setup（仅在需要时）： 启动一个 setup 任务并等待；如果失败或超时，我们继续往下执行。
• Translate： 基于你已经上传的文件创建翻译任务。

如果 setup 能在规定时间内完成，那当然最好。如果它失败或超时，我们仍然会继续执行，并告诉你发生了什么。你依然会得到翻译结果。

当你运行 npx gtx-cli translate 时，你将会看到：

开始翻译...

待翻译文件：
  - your/file/path.mdx
  - ...

正在上传文件至 General Translation API...
✔ 文件上传成功

正在配置项目...

# 如果配置成功
配置已完成。

# 如果配置超时
⚠ 配置超时 — 跳过配置继续执行：等待配置生成时超时

# 如果配置失败
⚠ 配置失败 — 跳过配置继续执行：<error message>

# 无论如何，都将继续执行翻译
正在创建 12 个翻译任务
[0/12] 翻译已完成
your/file/path.mdx [es]

通过这一更改，即使在极小概率的情况下初始化失败，我们现在也可以保证你的翻译仍然会被生成。

我们也很满意这一点带来的好处：它让你更清楚地了解我们是如何、在什么地方生成影响你翻译结果的内容，并且让你可以放心地添加新的初始化步骤，因为这些步骤永远不会阻止翻译的进行。

上传

我们还让 upload 变得更加灵活。早期版本默认你总是会同时上传源文件及其翻译，这并不适用于所有工作流。现在你可以：

• 仅上传 源文件（暂时没有任何翻译）。
• 同时上传 源文件 + 翻译。

我们仍会根据你的代码仓库结构和配置自动检测翻译。上传后，你会立即在控制台中看到文件。

如果你的 gt.config.json 是这样的：

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

运行 npx gtx-cli upload：

# 仅源文件（未找到本地翻译）：
开始上传...

待上传文件：
  - src/i18n/en/common.json -> es, fr
  ...

正在上传 1 个文件至 General Translation...
✔ 文件上传成功

完成！

# 在控制面板中，您将看到：
#   src/i18n/en/common.json
# 暂无对应的翻译文件。

如果存在本地翻译且已被自动检测到：

开始上传...

待上传文件：
  - src/i18n/en/common.json -> es, fr

正在向 General Translation 上传 3 个文件...
✔ 文件上传成功

完成！

# 在控制面板中，您将看到：
#   src/i18n/en/common.json
# 以及语言下拉菜单中的西班牙语和法语译文。

如果某个 locale 的翻译文件缺失，我们会上传源文案，并跳过该缺失的翻译。

如果你已有本地翻译，但只想上传源文案，请在运行 upload 之前从 gt.config.json 中移除这些 locales：

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

上传会覆盖现有翻译

注意： 当你运行 upload 时，我们为某个文件/语言区域检测并上传到服务器的任何翻译文件，都会替换当前为该文件/语言区域存储的内容。

• 若只想上传源文档，请在执行 upload 之前，从 gt.config.json 中移除目标语言区域。
• 如果你需要先审查改动，请使用一个单独的项目，或在上传前先导出现有翻译。
• 缺失的翻译会被跳过，已存在的翻译会被替换。