# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: 通过 CLI 登录并设置项目
URL: https://generaltranslation.com/zh/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 通过 CLI 登录、设置项目并创建具有明确Permission的密钥，也可在脚本和智能体中以无头模式运行设置流程。
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

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

## 从引导式设置开始

运行 [`gt init`](/docs/cli/reference/commands/init) 配置你的项目。仅当需要创建项目或 密钥 时，它才会进行登录：

```bash
npx gt init
```

使用 [`gt login`](/docs/cli/reference/commands/login) 可跳过设置流程直接登录，或使用 [`npx gt login --no-browser`](/docs/cli/reference/commands/login#flags) 在另一台设备上批准登录。两种方式都需要人工批准。

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

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

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

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

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

## 选择项目和密钥Permission

[`gt init`](/docs/cli/reference/commands/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 凭据](/docs/react/nextjs/config#credentials)) 。

如需额外创建一个项目密钥并自定义其Permission，请使用 [`gt api-key create`](/docs/cli/reference/commands/api-key-create)：

```bash
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`](/docs/platform/core/reference/api-client) 中的 [`paginate`](/docs/platform/core/reference/api-client#pagination)，即可遍历你的 API Key 有权访问的所有项目，无需手动处理游标：

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

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

使用 `createApiClient` 客户端时，`throwOnError` 调用中的 HTTP 失败现在会抛出 [`ApiError`](/docs/platform/core/reference/api-client#api-error)，HTTP 状态码存放在 `code` 中。

借助 [API 客户端的轮询端点辅助函数](/docs/platform/core/reference/api-client#job-polling)，你可以等待翻译任务完成，超时时会返回 `complete: false`。注意，完成并不代表所有任务都已成功。下载翻译之前，请先检查任务结果。

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

## 升级

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.