# gt: General Translation CLI tool: gt upload
URL: https://generaltranslation.com/zh/docs/cli/reference/commands/upload.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 将源文件和译文上传到 General Translation 平台。gt upload 命令的 API 参考。

将项目的源文件以及任何现有译文上传到 General Translation 平台，并同步本地文件，以便后续管理、入队处理和跟踪。可将它与 [`gt enqueue`](/docs/cli/reference/commands/enqueue) 和 [`gt download`](/docs/cli/reference/commands/download) 搭配使用，把翻译流程拆分到不同的 CI 阶段。参见[管理译文](/docs/cli/guides/managing-translations#split)。

*注意：仅限生产环境使用。需要生产环境的 `GT_API_KEY` 和 `GT_PROJECT_ID`。*

```bash
npx gt upload
```

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

1. 读取 `gt.config.json`，确定要 upload 的文件。
2. 收集所有可翻译的 源文件。
3. 对每个文件计算哈希，生成 `fileId` (基于文件路径) 和 `versionId` (基于文件内容) 。
4. 查询 API，确定哪些文件是新增或已更改的。
5. 检测文件移动——内容相同但路径不同——并保留现有翻译。
6. 上传新增和已更改的 源文件，以及所有 本地翻译文件 的 translation files。
7. 应用已配置的 CDN publish 和 unpublish 规则。`--publish` 会将 发布 设为全局默认值，而针对单个文件显式设置的 `publish: false` 规则仍会让这些文件被排除在外。

## 标志 [#flags]

`upload` 注册了共享的[翻译标志](/docs/cli/reference/commands/translate#flags)，但只使用与收集、上传和发布文件相关的选项。主要选项如下。

| 参数                          | 描述                           | 类型         | 可选 | 默认值              |
| --------------------------- | ---------------------------- | ---------- | -- | ---------------- |
| `--api-key <key>`           | 生产环境 API Key。                | `string`   | 是  | `GT_API_KEY`     |
| `--project-id <id>`         | 项目 ID。                       | `string`   | 是  | `GT_PROJECT_ID`  |
| `-c, --config <path>`       | 配置文件的路径。                     | `string`   | 是  | `gt.config.json` |
| `--locales <locales...>`    | 额外的目标区域设置，会追加到配置中的 locales。  | `string[]` | 是  | —                |
| `--default-locale <locale>` | 项目的源区域设置。                    | `string`   | 是  | `en`             |
| `--publish`                 | 将发布作为全局默认行为；各文件显式设置的排除项仍然生效。 | `boolean`  | 是  | `false`          |

<Callout type="warn">
  在 `gt` 2.20.1 中，`upload` 接受 `--dry-run`，但仍会上传文件。其共享的 `--timeout` 标志用于控制翻译等待时间，对该命令没有影响。若要在不上传的情况下查看收集到的文件，请使用 [`gt stage --dry-run`](/docs/cli/reference/commands/stage)。
</Callout>

## 示例 [#example]

```bash
# 第一阶段：上传源文件（此命令）
npx gt upload

# 第二阶段：将翻译加入队列
npx gt enqueue

# 第三阶段：准备就绪后下载
npx gt download
```

## 其他说明 [#notes]

* `upload` 会收集所有已配置类型中可翻译的源文件 (JSON、YAML、Markdown、MDX 等) ，以及所有本地翻译文件。
* 内容仍与 `gt-lock.json` 匹配的现有翻译会被跳过。其他本地翻译会被上传，并可能替换已存储的翻译；若没有锁文件，则所有本地翻译都会被上传。
* 由于它会根据每个文件的路径和内容计算哈希值，因此移动后的文件 (内容相同、路径不同) 会保留已有翻译，而不会被重新翻译。
* 发布前请先在项目“设置”中启用 CDN。如果发布失败，上传仍视为成功，CLI 会发出一条警告。

## Sitemap

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