# gt: General Translation CLI tool: gt init
URL: https://generaltranslation.com/zh/docs/cli/reference/commands/init.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 运行 General Translation 的设置向导来配置项目。gt init 命令的 API 参考。

`init` 是默认命令——直接运行 `npx gt` (不带任何命令) 时，会执行它。

该向导会检测你的框架，并根据项目情况安装依赖、配置框架、创建 `gt.config.json`，以及生成凭据。有关详细步骤，请参阅[配置 CLI](/docs/cli/guides/configuring)。

```bash
npx gt init
```

## 工作方式 [#how-it-works]

1. 检测你的框架。对于 Next.js App Router 或 Mintlify 项目，它会改为提示你连接 [Locadex](/docs/platform/locadex/quickstart) AI 智能体。
2. 对于基于 React 的项目，可选择安装相应的运行时库，并配置框架 (实验性) 。Next.js App Router 应用会添加 [`GTProvider`](/docs/react/reference/components/gt-provider) 和 `withGTConfig`。Vite 应用会添加一个在现有应用入口之前运行的 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 引导程序。TanStack Start 应用会添加 `gt-tanstack-start`、`src/loadTranslations.ts`、`src/start.ts` 中的 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware)、`src/router.tsx` 中的 [`initializeGT`](/docs/react/tanstack-start/setup#initialize)，以及 root 路由中的 [`GTProvider`](/docs/react/reference/components/gt-provider)。其他 React 应用仅安装该库。
3. 解析默认区域设置和目标区域设置，并创建或更新 `gt.config.json`。`--locales` 会替换已配置的区域设置列表，`--file-formats` 会替换设置流程提供的格式；其他格式及无关设置均会保留。如果 `gt.config.json` 无效，设置会在做出任何更改之前终止。对于本地 Vite 或 TanStack Start 存储，还会创建一个 [`loadTranslations`](/docs/react/reference/functions/load-translations) 文件和空的目标区域设置文件。
4. 当配置的工作流需要持久安装 CLI 时，将 `gt` 安装为开发依赖。Vite 框架设置不会添加 `gt`；请继续使用 `npx gt` 运行它。
5. 可选择选取或创建项目，并在 `.env.local` 中预配一个开发运行时密钥。设置流程仅在此步骤中登录，且登录发生在更改文件之前；如果提供了显式的 tooling key 或已保存的登录信息，则会直接使用。对于本地 Vite 和 TanStack Start 设置，会询问是否启用实时开发翻译 (默认为否) ；若选择否，则跳过登录、项目发现和密钥创建。

*注意：React 设置步骤仍处于实验阶段，可能不适用于所有项目。请检查它所做的更改。*

### 项目选择与运行时凭据

如果已配置项目 ID，则直接复用。否则，向导会列出[可访问的项目](/docs/platform/openapi/reference/project/list-projects)供你选择，或提示你创建新项目。创建项目时，请选择你有权创建项目的 Organization。如果没有可用的 Organization，请在 Dashboard 中创建一个，或联系管理员获取访问权限。在交互模式下，项目名称默认为应用目录名称；无界面创建则必须提供 `--project-name`。创建时会使用你所选的源区域设置。

选择现有项目无需 Organization 的项目创建权限。但预配密钥仍需具备密钥写入授权，以及委派运行时生成的权限。显式指定的 tooling key 若无效或权限不足，绝不会回退到登录凭据。

预配会创建一个名为 `Development key (gt init)` 的密钥，且该密钥仅具有 `project:translations:generate` 权限。它会写入项目 ID 和开发密钥，但不会打印 secret，也不会更改已有的 `GT_API_KEY`。此运行时密钥不能用于后续 CLI 管理命令的身份验证；请使用你的登录会话，或另行限定范围的 tooling key。 (参见[凭据](/docs/cli/guides/configuring#credentials)。)

如果同一项目已有框架运行时凭据，则可跳过预配。仅限服务器端使用、且已配置项目 ID 和 `GT_API_KEY` 的设置同样会跳过预配；而在浏览器中进行翻译的框架不会将不带前缀的 `GT_API_KEY` 视为运行时密钥。

生成的变量为 `GT_PROJECT_ID` 和 `GT_DEV_API_KEY`。对于在浏览器中进行翻译的框架，会添加以下前缀：

* Next.js (App Router 和 Pages Router) ：`NEXT_PUBLIC_`
* Vite 和 TanStack Start：`VITE_`
* Gatsby：`GATSBY_`
* React：`REACT_APP_`
* Redwood：`REDWOOD_ENV_`

其他设置使用不带前缀的变量。开发密钥仅限本地开发使用；生产环境凭据请参见 [Next.js 凭据](/docs/react/nextjs/config#credentials)。切勿在已部署的浏览器或移动端 bundle 中包含 API Key。

## 选项 [#flags]

选项可以预先回答向导中的问题，这样运行时只会询问剩下的问题。同样的配置和凭据选项也适用于 [`gt configure`](/docs/cli/reference/commands/configure)。

### 设置模式

| 参数                    | 说明                                                                              | 类型        | 可选 | 默认值              |
| --------------------- | ------------------------------------------------------------------------------- | --------- | -- | ---------------- |
| `--no-interactive`    | 不显示任何提示。在修改文件前停止，并列出仍需提供的选项。当 stdin 或 stdout 不是终端时自动启用。                         | `boolean` | 是  | `false`          |
| `--json`              | 将登录、交接和结果事件以 JSON Lines 格式写入 stdout，其余输出均写入 stderr。启用此选项即隐含 `--no-interactive`。 | `boolean` | 是  | `false`          |
| `--defaults`          | 对于所有未通过选项或 `gt.config.json` 指定的本地配置项，一律采用推荐值。不会创建项目或密钥。                         | `boolean` | 是  | —                |
| `--no-defaults`       | 不提供推荐的默认值。                                                                      | `boolean` | 是  | —                |
| `-c, --config <path>` | 配置文件路径。                                                                         | `string`  | 是  | `gt.config.json` |

### 配置

| 参数                              | 描述                                                                                                                                                      | 类型         | 可选 | 默认值                                           |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -- | --------------------------------------------- |
| `--src <paths...>`              | 应用源代码的 glob 模式。                                                                                                                                         | `string[]` | 是  | [特定于框架](/docs/cli/reference/config#src)       |
| `--default-locale <locale>`     | 默认区域设置，例如 `en`。                                                                                                                                         | `string`   | 是  | 使用 `--defaults` 时为 `en`                       |
| `--locales <locales...>`        | 目标区域设置，例如 `fr es`。将替换已配置的列表。                                                                                                                            | `string[]` | 是  | —                                             |
| `--storage <storage>`           | 框架翻译的存储位置：`local` 或 `cdn`。`gt-vue` 仅支持 `local`。                                                                                                         | `string`   | 是  | 使用 `--defaults` 时为 `local`                    |
| `--translations-dir <path>`     | 本地翻译文件的存放目录。                                                                                                                                            | `string`   | 是  | 使用 `--defaults` 时特定于框架                        |
| `--file-formats <formats...>`   | `json`、`md`、`mdx`、`ts`、`js`、`yaml` 或 `none`。将替换已配置的上述格式；已配置的其他格式会被保留，并给出警告。                                                                             | `string[]` | 是  | 在框架项目中使用 `--defaults` 时为 `none`               |
| `--file-patterns <patterns...>` | 包含 `[locale]` 的 `<format>=<glob>` 模式，例如 `json=./locales/[locale]/*.json`。同时会选中对应的格式。                                                                    | `string[]` | 是  | 使用 `--defaults` 时为 `./**/[locale]/*.<format>` |
| `--package-manager <id>`        | 用于安装依赖的包管理器：`npm`、`yarn_v1`、`yarn_v2`、`pnpm`、`bun` 或 `deno`。自动检测时会逐级向上查找，直至 Git 根目录，依据最近的 `packageManager` 或 `devEngines` 字段、锁文件或可识别的 workspace 标识进行判断。 | `string`   | 是  | 自动检测                                          |

### 项目与开发凭据

| 参数                      | 描述                                                                                    | 类型        | 可选 | 默认值                        |
| ----------------------- | ------------------------------------------------------------------------------------- | --------- | -- | -------------------------- |
| `--dev-credentials`     | 将项目 ID 和新的开发密钥保存到 `.env.local`。使用 `--no-dev-credentials` 可跳过此步骤。                      | `boolean` | 是  | —                          |
| `--live-translations`   | 本地 Vite 或 TanStack Start 存储：配置实时开发翻译，此操作会创建一个开发密钥。使用 `--no-live-translations` 可跳过此步骤。 | `boolean` | 是  | 使用 `--defaults` 时为 `false` |
| `--project-id <id>`     | 开发凭据所使用的现有项目。                                                                         | `string`  | 是  | —                          |
| `--create-project`      | 为开发凭据创建新项目。                                                                           | `boolean` | 是  | `false`                    |
| `--org-id <id>`         | 新项目所属的 Organization。仅当你有权访问多个 Organization 时才需要指定。                                    | `string`  | 是  | —                          |
| `--project-name <name>` | 新项目的名称。                                                                               | `string`  | 是  | 出现提示时为应用目录名称               |

### 框架设置

这些选项仅适用于 `gt init`。在 `gt-vue` 项目中，`gt init` 接受 [`gt configure`](/docs/cli/reference/commands/configure) 的选项，并跳过 React 设置。

| 参数                        | 描述                                                                                                                                 | 类型        | 可选 | 默认值                        |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------- | -- | -------------------------- |
| `--locadex`               | Mintlify 和 Next.js App Router：通过 GitHub 将设置工作交由 Locadex AI 智能体完成。使用 `--no-locadex` 可在本地进行设置。                                       | `boolean` | 是  | 使用 `--defaults` 时为 `false` |
| `--react-setup`           | React 项目：安装该库；对于 Next.js App Router、Vite 或 TanStack Start，还会添加相应的设置代码 (参见[工作方式](#how-it-works)) 。使用 `--no-react-setup` 可保持应用源代码不变。 | `boolean` | 是  | 使用 `--defaults` 时为 `true`  |
| `--framework <framework>` | 指定 `--react-setup` 所用的 React 框架，将覆盖自动检测结果。                                                                                         | `string`  | 是  | 使用 `--defaults` 时为自动检测结果   |
| `--format`                | Next.js App Router：使用检测到的格式化工具，对设置过程中修改的文件进行格式化。使用 `--no-format` 可跳过此步骤。                                                           | `boolean` | 是  | 使用 `--defaults` 时为 `true`  |

## 无界面运行 [#headless]

非交互式运行会按以下顺序解析每个答案：先读取对应的选项，再读取 `gt.config.json`；如果设置了 `--defaults`，最后采用推荐值。如果仍有答案缺失，命令会在修改任何文件之前退出，并列出需要传入的选项。默认情况下不会创建开发凭据。对于本地 Vite 和 TanStack Start 存储，请传入 `--live-translations` 并附带项目 ID 或 `--create-project --project-name <name>`，或者传入 `--no-live-translations`。对于其他配置，请使用 `--dev-credentials` 或 `--no-dev-credentials`。请勿混用 `--[no-]live-translations` 和 `--[no-]dev-credentials` 这两组选项；CLI 会在修改任何文件之前拒绝所有此类组合。如果项目已有运行时凭据，则跳过此步骤。

只有在需要预配凭据，且既没有 tooling key 也没有已保存的登录信息时，setup 才会执行登录。在没有终端的环境中，登录会使用设备代码，并等待用户批准，不会打开浏览器。使用 `--json` 时，命令每行输出一个 JSON 对象，并通过其 `type` 字段加以区分：

* `authorization_required` — `verificationUri`、`userCode`，以及 `verificationUriComplete` (如可用) 。
* `handoff` — Locadex GitHub `url`，附带 `reason: "locadex"`。
* `result` — `command`、`outcome` (`success`、`needs_human_action` 或 `failed`) 、`completedSteps`，以及 `url`、用于后续手动操作的 `actions`、`missingOptions` 和 `error` (如存在) 。

`completedSteps` 不会列出未发生变化的 `gt.config.json` 和生成的 translation-loader 文件。当其中任一文件发生变化时，对应步骤会标明该文件是新建的还是已更新的。

## 示例 [#example]

```bash
# 运行完整的设置向导
npx gt init

# 不带任何命令运行 gt 效果相同
npx gt

# 无界面本地设置：不创建新项目或开发密钥
npx gt init --no-interactive --defaults --locales fr es --no-dev-credentials --json
```

## 其他说明 [#notes]

* `init` 与 [`gt configure`](/docs/cli/reference/commands/configure) 共用配置、加载器、CLI 安装和凭据流程，并额外增加实验性的 React 设置步骤。它不会运行 [`gt setup`](/docs/cli/reference/commands/setup)，该命令会上传你的源文件。
* 在 monorepo 中，请从具体的应用目录运行 `init`。如果在包含 `pnpm-workspace.yaml` 或 `workspaces` 字段的 workspace 根目录下运行，该命令会直接停止且不更改任何文件，除非其中只列出了该应用本身。
* Electron 应用程序不支持自动设置。
* 使用 `gt-react` 或 `gt-next` 不需要 API Key 和项目 ID——只有在调用 General Translation API 时才需要它们。
* 如果实验性的 React 设置不适用于你的项目，请参照 [React](/docs/react/react-quickstart) 文档手动进行设置。
* 预配开发凭据时必须已安装 Git。请确保 `.env.local` 不被跟踪且已加入 Git 忽略列表，并沿用仓库的常规 Git 配置。Init 会拒绝不安全的文件位置或 Git 覆盖配置。符号链接必须指向一个已存在且满足相同安全要求的常规文件。已有的无关环境变量会被保留。
* 请一次只运行一个设置命令。如果无法更新 `.env.local` (包括因存在不受支持的多行赋值而失败的情况) ，新创建的项目或键可能会残留。此前的配置和依赖更改不会被回滚。

## Sitemap

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