# General Translation Platform: createTag
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/create-tag.mdx
---

title: createTag
description: 创建用于分组或标识文件版本的标签。createTag 的 API 参考。

---

使用 General Translation 创建或 upsert 一个翻译标签，将一组源文件关联到用户定义的标签 ID，并可附带一条可选消息。标签会在仪表板中以人类可读的名称而非内容哈希值来标识翻译版本。

## 概述 [#overview]

调用 `createTag` 时，传入标签 ID 以及要与之关联的文件引用。该方法会返回已创建或已更新的标签。

```typescript
const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' });

const result = await gt.createTag({
  tagId: 'v2.1.0',
  files: uploadedFiles.map((f) => ({
    fileId: f.fileId,
    versionId: f.versionId,
    branchId: f.branchId,
  })),
  message: 'Added checkout page translations',
});
```

签名：

```typescript
createTag(options: CreateTagOptions): Promise<CreateTagResult>
```

*注意：`createTag` 要求 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。*

## 工作原理 [#how-it-works]

* **Upsert。** 如果已存在相同 `tagId` 的标签，则会使用新的文件引用对其执行 upsert。
* **顺序。** 标签会在源文件上传后、翻译 setup 和 enqueueing 之前创建。
* **在 CLI 中非致命。** 在 CLI 工作流中，创建标签属于非致命操作——即使失败，也不会阻塞翻译。
* **CLI 集成。** CLI 的 `--tag` 和 `-m` 标志在内部使用此方法。

## 参数 [#parameters]

| 参数                    | 描述       | 类型                 | 可选 | 默认值 |
| --------------------- | -------- | ------------------ | -- | --- |
| [`options`](#options) | 创建标签的选项。 | `CreateTagOptions` | 否  | —   |

### `options` [#options]

**类型** `CreateTagOptions` · **必填**

创建标签时的选项：

| 字段        | 描述                                       | 类型                         | 可选 |
| --------- | ---------------------------------------- | -------------------------- | -- |
| `tagId`   | 标签的唯一标识符 (例如 `"v2.1.0"` 或 Git 提交哈希值) 。 | `string`                   | 否  |
| `files`   | 要与此标签关联的文件引用。                            | `CreateTagFileReference[]` | 否  |
| `message` | 标签的说明消息。                                 | `string`                   | 是  |

每个 `CreateTagFileReference` 都对应一个已上传的文件版本：

| 字段          | 描述            | 类型       | 可选 |
| ----------- | ------------- | -------- | -- |
| `fileId`    | 来自之前上传的文件 ID。 | `string` | 否  |
| `versionId` | 来自之前上传的版本 ID。 | `string` | 否  |
| `branchId`  | 来自之前上传的分支 ID。 | `string` | 否  |

## 返回值 [#returns]

**类型** `Promise<CreateTagResult>`

会返回一个包含已创建或已更新标签的 `CreateTagResult`：

```typescript
type CreateTagResult = {
  tag: {
    id: string;
    tagId: string;
    message: string | null;
    createdAt: string;
    updatedAt: string;
  };
};
```

| 属性              | 描述               | 类型               |
| --------------- | ---------------- | ---------------- |
| `tag.id`        | 内部标签标识符。         | `string`         |
| `tag.tagId`     | 用户提供的标签 ID。      | `string`         |
| `tag.message`   | 标签消息 (如有提供) 。    | `string \| null` |
| `tag.createdAt` | 标签创建时的 ISO 时间戳。  | `string`         |
| `tag.updatedAt` | 最后一次更新的 ISO 时间戳。 | `string`         |

## 示例 [#examples]

```typescript
// 基本用法：为上传的文件打上版本号标签
import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

// 首先上传源文件
const uploadResult = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});

// 为上传的文件打标签
const tagResult = await gt.createTag({
  tagId: 'v2.1.0',
  files: uploadResult.uploadedFiles.map((f) => ({
    fileId: f.fileId,
    versionId: f.versionId,
    branchId: f.branchId,
  })),
  message: 'Release 2.1 translations',
});

console.log(`Tagged as ${tagResult.tag.tagId}`);
```

```typescript
// 使用 git commit 哈希值创建标签
import { execSync } from 'node:child_process';

const commitHash = execSync('git rev-parse --short HEAD', {
  encoding: 'utf-8',
}).trim();
const commitMessage = execSync('git log -1 --format=%s', {
  encoding: 'utf-8',
}).trim();

const tagResult = await gt.createTag({
  tagId: commitHash,
  files: uploadResult.uploadedFiles.map((f) => ({
    fileId: f.fileId,
    versionId: f.versionId,
    branchId: f.branchId,
  })),
  message: commitMessage,
});
```

## 说明 [#notes]

* 如果已存在相同 `tagId` 的标签，则会用新的文件引用对其执行 upsert。
* 标签会在源文件上传后、翻译初始化和入队前创建。
* 在 CLI 工作流中，创建标签不是致命操作——即使失败也不会阻止翻译继续进行。
* CLI 的 `--tag` 和 `-m` 标志在内部使用此方法。