返回
gt2.23.0@generaltranslation/api0.5.0generaltranslation9.5.2cli
博客更新日志

gt 2.23.0 / @generaltranslation/api 0.5.0: 通过 CLI 登录并设置项目

通过 CLI 登录、设置项目并创建具有明确Permission的密钥，也可在脚本和智能体中以无头模式运行设置流程。

Chenxin (Cyan) Yan

gt@2.23.0 将账户登录、项目选择、按作用域创建密钥以及可脚本化的设置流程带入终端。同时发布的 @generaltranslation/api@0.5.0 和 generaltranslation@9.5.2 新增了项目发现功能，并支持自动分页。

从引导式设置开始

运行 gt init 配置你的项目。仅当需要创建项目或 密钥 时，它才会进行登录：

npx gt init

使用 gt login 可跳过设置流程直接登录，或使用 npx gt login --no-browser 在另一台设备上批准登录。两种方式都需要人工批准。

gt whoami 用于查看当前登录的身份，gt logout 用于清除已保存的登录信息。对于无人值守的工作流，请使用 CI 提供商密钥库中具有限定权限范围的 API 密钥。

从脚本和智能体运行初始化

每个初始化问题都有对应的选项。在无终端环境中，或使用 --no-interactive 时，gt init 会在修改文件之前列出所有缺失的选项；--json 则会输出登录、交接和结果事件：

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults 会采用推荐的本地选项，但不会创建任何项目或密钥。

选择项目和密钥Permission

gt init 可以选择一个你有权访问的项目，或在你拥有相应Permission的 组织 中新建项目，然后将项目 ID 和一个开发环境运行时密钥保存到 .env.local 中。

该密钥仅授予 project:translations:generate Permission：它只用于本地运行时翻译，不能用于 CLI 上传或 CI。已有的 GT_API_KEY 值不会被修改。对于 Next.js App Router 项目，会生成 NEXT_PUBLIC_GT_PROJECT_ID 和 NEXT_PUBLIC_GT_DEV_API_KEY，使客户端组件在开发环境中也能进行翻译；请确保这两个变量不会被打包进生产环境构建 (参见 Next.js 凭据) 。

如需额外创建一个项目密钥并自定义其Permission，请使用 gt api-key create：

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

你必须拥有创建密钥的Permission，并且能够授予所选的每一项 Permission。该命令只会显示一次密钥，请妥善保管。在 CI 中，请根据整个工作流的需要选择Permission，不要直接沿用这个仅用于生成的示例。切勿将 API Key 包含在已部署的浏览器端或移动端 bundle 中。

使用类型化 API 调用并检查任务结果

使用 generaltranslation/api 中的 paginate，即可遍历你的 API Key 有权访问的所有项目，无需手动处理游标：

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

使用 createApiClient 客户端时，throwOnError 调用中的 HTTP 失败现在会抛出 ApiError，HTTP 状态码存放在 code 中。

借助 API 客户端的轮询端点辅助函数，你可以等待翻译任务完成，超时时会返回 complete: false。注意，完成并不代表所有任务都已成功。下载翻译之前，请先检查任务结果。

诊断格式化功能现已通过公开的 generaltranslation/diagnostics 入口文件提供。工具无需导入完整的 Core 入口文件，即可格式化可指导操作的提示消息。

升级

  • 升级后才能列出项目和组织。 API 现在通过 items (而非 projects 或 orgs) 返回这些数据，并拒绝此变更之前签发的游标。旧版 CLI 无法在 gt init 中列出它们。直接通过 HTTP 或 SDK 调用的用户应改为读取 items，并重新开始分页。
  • 捕获抛出型调用中的 ApiError。 在 throwOnError 调用和 awaitJobs 中，HTTP 失败时会抛出 ApiError，而不再抛出解码后的响应体。未使用 throwOnError 的调用仍会在 error 中返回响应体。
  • 移动 src/gt.config.json。 CLI 不再读取该文件。请将其移至项目根目录，或传入 --config src/gt.config.json。
  • 替换 gt auth 和 --key-type。 请使用 login 进行账户认证，使用 init 进行引导式项目设置，如需额外凭据，请显式创建密钥。gt configure 并不是无副作用的替代方案：视你的设置而定，它可能会安装依赖项并配置凭据。
  • 将运行时凭据与工具凭据分开。 GT_DEV_API_KEY 仍是框架的运行时设置。仅登录并不会配置运行时 SDK 凭据。显式提供的 API Key 仍优先于 CLI 保存的登录信息；参见凭据选择。
  • 确认重试行为。 管理类 POST 请求在遇到网络或服务器端故障时不会自动重试，但启用重试后，429 响应仍可能触发重试。Core 运行时翻译对这些故障和 429 响应均不会自动重试。请勿盲目重复创建项目或密钥：每次成功的请求都会新建一个资源。
  • 保留受支持的兼容性 API。 Core 的 devApiKey 后备机制和 getProjectData 仍可使用，但已弃用。请改用 apiKey；新增的项目信息调用请优先使用 getProjectInfo。
  • 处理验证和返回结果的变更。 不受支持的模型提供商值会在请求发送前直接报错。字体上传结果中不再包含 deduped 字段。