# generaltranslation: General Translation Core SDK: enqueueFiles
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/enqueue-files.mdx
---
title: enqueueFiles
description: enqueueFiles 方法的 API 参考，用于将文件翻译任务加入队列
---

## 概述

`enqueueFiles` 方法会为之前已上传的源文件将翻译任务加入队列。
该方法接收文件引用，并为指定的目标区域设置创建翻译任务。

```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']
});
```

<Callout type="info">
  只有在文件上传后，才能将其加入翻译队列。
</Callout>


## 参考

### 参数

| 名称        | 类型                   | 描述                     |
| --------- | -------------------- | ---------------------- |
| `files`   | `FileReferenceIds[]` | 由先前已上传文件的文件引用 ID 组成的数组 |
| `options` | `EnqueueOptions`     | 翻译任务的配置选项              |

#### FileReferenceIds 结构

```typescript
type FileReferenceIds = {
  fileId: string;
  versionId: string;
  branchId?: string;
  fileName?: string;
  fileFormat?: FileFormat;
  dataFormat?: DataFormat;
}
```

| 名称            | 类型           | 说明                         |
| ------------- | ------------ | -------------------------- |
| `fileId`      | `string`     | 唯一文件标识符                    |
| `versionId`   | `string`     | 版本标识符                      |
| `branchId?`   | `string`     | 分支标识符 (可选)                 |
| `fileName?`   | `string`     | 文件名 (可选)                   |
| `fileFormat?` | `FileFormat` | 文件格式 (JSON、MD 等)           |
| `dataFormat?` | `DataFormat` | 文件内的数据格式 (ICU、I18NEXT、JSX) |

#### EnqueueOptions

| 名称                 | 类型         | 描述                                |
| ------------------ | ---------- | --------------------------------- |
| `sourceLocale?`    | `string`   | 翻译时使用的源区域设置 (默认为实例的 sourceLocale) |
| `targetLocales`    | `string[]` | 翻译时使用的目标区域设置数组                    |
| `requireApproval?` | `boolean`  | 翻译在发布前是否需要批准                      |
| `modelProvider?`   | `string`   | 翻译时使用的特定 AI 模型提供商                 |
| `force?`           | `boolean`  | 即使翻译已存在，也强制重新翻译                   |
| `timeout?`         | `number`   | 请求超时时间 (以毫秒为单位)                   |

### 返回值

`Promise<EnqueueFilesResult>` - 包含任务信息和处理详情。

```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;
}
```

| 属性        | 类型                       | 描述                              |
| --------- | ------------------------ | ------------------------------- |
| `jobData` | `Record<string, object>` | 以作业 ID 为键的记录，其中每个值都包含该翻译任务的详细信息 |
| `locales` | `string[]`               | 翻译任务的目标区域设置列表                   |
| `message` | `string`                 | API 返回的状态消息                     |

***

## 示例

```typescript title="index.ts" copy
// (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(`翻译任务已创建：${enqueueResult.jobId}`);

// (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
  }))
);
```

***


## 注意事项

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

## 后续步骤

* 请参阅 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files)，在加入队列前先上传文件
* 请参阅 [`queryFileData`](/docs/core/class/methods/translation/query-file-data)，监控翻译进度
* 请参阅 [`downloadFile`](/docs/core/class/methods/translation/download-file)，获取已完成的译文
* 请参阅 [`checkJobStatus`](/docs/core/class/methods/translation/check-job-status)，检查任务状态