# General Translation Changelog: gtx-cli 2.3.0: 翻译运行更快、更可靠
URL: https://generaltranslation.com/zh/blog/gtx-cli_v2_3_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2025-09-12

## 概述

在 **gtx-cli 2.3.0** 中，我们更新了 [`translate`](/docs/cli/reference/commands/translate) 和 [`upload`](/docs/cli/reference/commands/upload) 命令的行为，并让翻译流水线更加透明。

***

## Translate

过去，[`translate`](/docs/cli/reference/commands/translate) 不仅会触发翻译，**还会**在后台执行一次性项目设置 (生成你在[仪表板](https://generaltranslation.com/dashboard/project/context)中看到的上下文和术语表) 。

在较小的项目中，这个过程很快；但在较大的代码库中，设置可能耗时过长并触发超时，让人误以为翻译失败了。

用户虽然会以为 [`translate`](/docs/cli/reference/commands/translate) 失败了，但实际上设置会异步完成，翻译也会生成，只是不会被下载，最终导致体验不完整且令人困惑。

### 设置

现在，设置是一个单独的步骤。我们对它进行了优化，以尽量降低超时的发生概率。

但考虑到设置仍有可能失败，翻译流程不再“依赖”设置完成。现在，整个流程大致如下：

* **上传：**上传文件并确认成功。
* **设置 (仅在需要时) ：**启动设置任务并等待；如果失败或超时，就继续往下执行。
* **翻译：**根据你已上传的文件创建翻译任务。

如果设置能及时完成，那当然最好。即使失败或超时，我们也会继续，并告知你具体发生了什么。你仍然可以拿到翻译结果。

运行 `npx gtx-cli translate` 时，你会看到：

```bash
Starting translation...

Files to translate:
  - your/file/path.mdx
  - ...

Uploading files to General Translation API...
✔ Files uploaded successfully

Setting up project...

# 如果设置成功
Setup successfully completed.

# 如果设置超时
⚠ Setup timed out — proceeding without setup: Timed out while waiting for setup generation

# 如果设置失败
⚠ Setup failed — proceeding without setup: <error message>

# 无论如何，继续执行翻译
Creating 12 translation(s)
[0/12] translations completed
your/file/path.mdx [es]
```

通过这项更改，我们现在可以保证：即使极少数情况下设置失败，你的翻译仍然会生成。

我们还认为，这能让你更清楚地了解我们如何以及在何处生成会影响翻译结果的内容；同时，也让新增设置步骤变得毫无负担，因为这些步骤绝不会阻止翻译继续进行。

***


## 上传

我们还让 [`upload`](/docs/cli/reference/commands/upload) 更灵活了。早期版本默认你总是会同时上传源文件及其翻译，这并不适用于所有工作流。现在你可以：

* 仅上传**源文件** (暂时不含翻译) 。
* 同时上传**源文件和翻译**。

我们仍会根据你的仓库结构和配置自动识别翻译。上传后，你会立即在你的[仪表板](https://generaltranslation.com/dashboard/project/translations)中看到这些文件。

如果这是你的 `gt.config.json`：

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}
```

执行 `npx gtx-cli upload`：

```bash
# 仅源文件（未找到本地翻译）：
Starting upload...

Files to upload:
  - src/i18n/en/common.json -> es, fr
  ...

Uploading 1 file(s) to General Translation...
✔ Files uploaded successfully

Done!

# 在您的仪表板中，您将看到：
#   src/i18n/en/common.json
# 暂无对应的翻译。
```

如果检测到现有的本地翻译：

```bash
Starting upload...

Files to upload:
  - src/i18n/en/common.json -> es, fr

Uploading 3 file(s) to General Translation...
✔ Files uploaded successfully

Done!

# 在您的仪表板中，您将看到：
#   src/i18n/en/common.json
# 以及区域设置下拉菜单中对应的西班牙语和法语翻译版本。
```

如果某个区域设置的翻译文件缺失，我们会上传源文本，并跳过该缺失的翻译。

如果你有本地翻译，但只想上传源文本，请在运行 [`upload`](/docs/cli/reference/commands/upload) 之前先从 `gt.config.json` 中移除 `locales`：

```json
{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}
```

### 上传会覆盖现有翻译

> **请注意：** 运行 [`upload`](/docs/cli/reference/commands/upload) 时，我们检测到并上传的某个文件/区域设置对应的任何已翻译文件，都会**覆盖**当前该文件/区域设置下已存储的内容。
>
> * 如果只想上传源文件，请在执行 [`upload`](/docs/cli/reference/commands/upload) 前先从 `gt.config.json` 中移除目标 locales。
> * 如果你需要先审核更改，请使用单独的项目，或在上传前先导出当前翻译。
> * 缺失的翻译会被跳过；已有的翻译会被覆盖。

## Sitemap

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