# General Translation Platform: enqueueFiles
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/enqueue-files.mdx
---

title: enqueueFiles
description: 将已上传的源文件加入队列，以翻译成一个或多个目标区域设置。enqueueFiles 的 API 参考。

---

使用 General Translation 将先前上传的源文件加入翻译队列。它接收文件引用，并为每个目标区域设置创建一个翻译任务。

## 概览 [#overview]

调用 `enqueueFiles` 时，传入 [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 返回的文件引用，以及一个列出目标区域设置的选项对象。

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

const result = await gt.enqueueFiles(fileRefs, {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de'],
});
```

签名：

```typescript
enqueueFiles(
  files: FileReferenceIds[],
  options: EnqueueFilesOptions
): Promise<EnqueueFilesResult>
```

*注意：`enqueueFiles` 要求 GT 实例上配置 `apiKey` (或 `devApiKey`) 和 `projectId`。只有在文件上传后，才能将其加入队列。*

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

* **异步任务。** 翻译任务会异步运行。你可以使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 监控进度，或使用 [`awaitJobs`](/docs/platform/core/reference/gt-class-methods/translation/await-jobs) 等待其完成。
* **每个区域设置对应一个任务。** 返回的 `jobData` 以任务 ID 为键，每个目标区域设置都会创建一个任务。
* **版本管理。** 文件引用包含 `branchId`，以支持基于分支的版本管理。

## 参数 [#parameters]

| 参数                    | 描述               | 类型                                                                                 | 可选 | 默认 |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------- | -- | -- |
| [`files`](#files)     | 先前已上传文件的文件引用 ID。 | `FileReferenceIds[]`                                                               | 否  | —  |
| [`options`](#options) | 翻译任务的配置选项。       | [`EnqueueFilesOptions`](/docs/platform/core/reference/types/enqueue-files-options) | 否  | —  |

### `files` [#files]

**类型** `FileReferenceIds[]` · **必填**

要加入队列的文件引用：

```typescript
type FileReferenceIds = {
  fileId: string;
  versionId: string;
  branchId?: string;
  fileName?: string;
  fileFormat?: FileFormat;
  transformFormat?: FileFormat; // 生成翻译时请求的输出格式
  dataFormat?: DataFormat;
};
```

| 字段                | 描述                                                                                                     | 类型                                                              | 可选 |
| ----------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -- |
| `fileId`          | 唯一文件标识符。                                                                                               | `string`                                                        | 否  |
| `versionId`       | 版本标识符。                                                                                                 | `string`                                                        | 否  |
| `branchId`        | 分支标识符。                                                                                                 | `string`                                                        | 是  |
| `fileName`        | 文件名。                                                                                                   | `string`                                                        | 是  |
| `fileFormat`      | 文件格式。可选值为 `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT` 或 `TWILIO_CONTENT_JSON`。 | `FileFormat`                                                    | 是  |
| `transformFormat` | 生成翻译的输出格式。                                                                                             | `FileFormat`                                                    | 是  |
| `dataFormat`      | 文件内的数据格式 (ICU、I18NEXT、JSX、STRING) 。                                                                    | [`DataFormat`](/docs/platform/core/reference/types/data-format) | 是  |

### `options` [#options]

**类型** [`EnqueueFilesOptions`](/docs/platform/core/reference/types/enqueue-files-options) · **必填**

翻译任务的配置：

| 字段              | 描述                            | 类型         | 可选 | 默认值               |
| --------------- | ----------------------------- | ---------- | -- | ----------------- |
| `sourceLocale`  | 翻译时使用的源区域设置。                  | `string`   | 是  | 实例 `sourceLocale` |
| `targetLocales` | 要翻译成的目标区域设置。                  | `string[]` | 否  | —                 |
| `modelProvider` | 翻译时使用的特定 AI 模型提供方。            | `string`   | 是  | —                 |
| `force`         | 使缓存的翻译失效，并强制重新翻译，即使翻译已存在也是如此。 | `boolean`  | 是  | —                 |
| `timeout`       | 请求超时时间 (毫秒) 。                 | `number`   | 是  | —                 |

*注意：`requireApproval` 仅为 8.x 版本中的选项，在 9.0 中已不存在。*

## 返回值 [#returns]

**类型** `Promise<EnqueueFilesResult>`

该 Promise 会解析为一个 `EnqueueFilesResult`，其中包含 job 信息和处理详情：

```typescript
type EnqueueFilesResult = {
  jobData: {
    [jobId: string]: {
      sourceFileId: string;
      fileId: string;
      versionId: string;
      branchId: string;
      targetLocale: string;
      projectId: string;
      force: boolean;
      modelProvider?: string;
    };
  };
  locales: string[]; // 任务的目标区域设置
  message: string; // 来自 API 的状态消息
};
```

`jobData` 记录以 job ID 为键，每个值对应一个翻译任务。

## 示例 [#examples]

```typescript title="index.ts"
// (1) 创建 GT 实例
const targetLocales = ['es', 'fr', 'de'];
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// (2) 上传文件
const fileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [{ source: fileUpload }];
const { uploadedFiles } = await gt.uploadSourceFiles(files, { sourceLocale: 'en' });

// (3) 将文件翻译任务加入队列
const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: targetLocales,
});

console.log(`Created ${Object.keys(enqueueResult.jobData).length} translation jobs`);

// (4) 等待所有翻译完成
const { fileId, versionId, branchId } = uploadedFiles[0];
const translatedFileQueries = targetLocales.map((locale) => ({
  fileId,
  versionId,
  branchId,
  locale,
}));

while (true) {
  const result = await gt.queryFileData({
    translatedFiles: translatedFileQueries,
  });

  const allCompleted = result.translatedFiles?.every((file) => file.completedAt !== null);

  if (allCompleted) {
    break;
  }

  await new Promise((resolve) => setTimeout(resolve, 1000));
}

// (5) 下载文件
const downloadResult = await gt.downloadFileBatch(
  targetLocales.map((locale) => ({
    fileId,
    branchId,
    locale,
  }))
);
```

## 注意事项 [#notes]

* 必须先使用 [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) 上传文件内容。
* 翻译任务是异步执行的——请使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 或 [`awaitJobs`](/docs/platform/core/reference/gt-class-methods/translation/await-jobs) 监控进度。
* 文件引用包含 `branchId`，用于在支持分支的情况下进行版本管理。