# General Translation Platform: enqueueFiles
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/enqueue-files.mdx
Docs index: https://generaltranslation.com/llms.txt
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`

**类型** `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`      | 文件格式。                               | [`FileFormat`](/docs/platform/core/reference/types/file-format) | 是  |
| `transformFormat` | 生成翻译时请求的输出格式。                       | [`FileFormat`](/docs/platform/core/reference/types/file-format) | 是  |
| `dataFormat`      | 文件内的数据格式 (ICU、I18NEXT、JSX、STRING) 。 | [`DataFormat`](/docs/platform/core/reference/types/data-format) | 是  |

### `options`

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

翻译任务的配置：

| 字段              | 描述                                                 | 类型         | 可选 | 默认值               |
| --------------- | -------------------------------------------------- | ---------- | -- | ----------------- |
| `sourceLocale`  | 翻译时使用的源区域设置。                                       | `string`   | 是  | 实例 `sourceLocale` |
| `targetLocales` | 要翻译成的目标区域设置。                                       | `string[]` | 否  | —                 |
| `modelProvider` | 仅限企业版的模型提供方：`ANTHROPIC`、`OPENAI`、`XAI` 或 `GOOGLE`。 | `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' as const,
  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`，用于在支持分支的情况下进行版本管理。

## Sitemap

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