概览

在 generaltranslation v8 中，我们对 API 进行了重大调整，并弃用了一些 API 函数和端点。

旧版本的 API 将不再受支持。

使用 generaltranslation 低于 7.5 的版本时，很可能会出现错误。 使用 gtx-cli 低于 2.1.5 的版本时，很可能会出现错误。

---

背景与动机

为了提升开发者体验、支持后续功能演进，并让翻译管理更加轻松，我们引入了分支机制，并废弃了一些已不再使用的 API 端点。

---

功能

最新的 API 函数支持分支功能，可以为项目的不同分支创建各自独立的翻译。

现在每个文件都关联到一个分支。文件版本由 branchId、fileId 和 versionId 共同决定。

此前，文件翻译只关联到单一分支。 缓存的文件翻译默认使用该文件最近更新的版本。

在第 8 版中，更新文件翻译时，现在会使用指定分支上该文件的最新版本。 版本控制绑定到分支的历史，而不是时间戳。

新的版本控制系统与 git 的分支模型相对应：

• 在某个分支上更新源文件会创建该文件的新版本。
• 将某个分支合并到 main 分支时，会在 main 分支上的源文件与被合并分支上的源文件之间生成一个关联。
  • 后续的翻译将综合两个分支中的翻译内容。
• 检出某个分支时会创建该文件的新版本
  • 此分支上的翻译会引用 main 分支中之前的翻译。

要启用此功能，请在最新版本的 gtx-cli 中，为 gtx-cli translate 命令添加 --enable-branching 参数。

默认情况下，分支功能是关闭的，所有项目文件都关联到 main 分支。

要使用此功能，你的组织必须订阅付费方案。

更改

generaltranslation

• 弃用 checkTranslationStatus
• 弃用 downloadFile
• 将 downloadTranslatedFile 重命名为 downloadFile
  • 根据是否指定 locale，将下载源文件或对应的译文
• 修改 downloadFile 和 downloadFileBatch 的参数
• 弃用 enqueueEntries
• 修改 enqueueFiles 的参数（新增 branchIds）
• 弃用 fetchTranslations
• 弃用 shouldSetupProject
• 修改 submitUserEditDiffs 的参数（新增 branchIds，并将 id 字段设为必填）
• 修改 uploadSourceFiles 的参数（新增 branchIds）
• 修改 uploadTranslations 的参数（新增 branchIds）
• 修改 querySourceFile 的参数（新增 branchIds）
• 新增 checkJobStatus
• 新增 queryFileData
• 弃用 checkSetupStatus（请改用 checkJobStatus）
• 弃用 checkFileTranslations（请改用 queryFileData）

gtx-cli

• 为 translate 命令添加了 --enable-branching 标志
• 为 translate 命令添加了 --branch 标志
  • （可选）指定用于翻译的分支
• 为 translate 命令添加了 --disable-branch-detection 标志
  • （可选）启用后，CLI 将不会自动尝试检测要使用的分支。
  • 如果未安装 git 或项目不是 git 仓库，请使用此标志。
• 改进了翻译进度跟踪与日志输出
• 改进了翻译错误处理
• 优化了 API 性能，以避免不必要的文件上传到 API

gt-sanity

• 已更新为使用最新版本的 generaltranslation
• 翻译现在默认使用主分支。
  • 对文档草稿预览分支的支持将会在后续版本中提供。