# General Translation Platform: downloadFileBatch
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx
---

title: downloadFileBatch
description: 在一次请求中下载多个翻译后的文件。downloadFileBatch 的 API 参考。

---

使用 General Translation 可在一次批量请求中下载多个源文件或翻译文件。使用它代替多次单独调用 [`downloadFile`](/docs/platform/core/reference/gt-class-methods/translation/download-file)，以减少网络开销。

## 概览 [#overview]

使用文件请求数组调用 `downloadFileBatch`。每个请求既可以针对某个翻译 (带 `locale`/区域设置) ，也可以针对某个源文件 (不带 `locale`/区域设置) 。

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

const result = await gt.downloadFileBatch([
  { fileId: 'file-123', branchId: 'branch-456', locale: 'es' },
  { fileId: 'file-123', branchId: 'branch-456', locale: 'fr' },
  { fileId: 'file-123', branchId: 'branch-456', locale: 'de' },
]);
```

签名：

```typescript
downloadFileBatch(
  requests: DownloadFileBatchRequest,
  options?: DownloadFileBatchOptions
): Promise<DownloadFileBatchResult>
```

*注意：`downloadFileBatch` 要求 GT 实例上配置 `apiKey` (或 `devApiKey`) 和 `projectId`。它可通过一次 API 调用下载多个文件，比反复调用 `downloadFile` 更高效。*

## 工作方式 [#how-it-works]

* **顺序。** 在可能的情况下，返回的文件顺序与请求项的顺序一致。
* **部分成功。** batch 中某个文件下载失败，不会导致整个 batch 失败。
* **就绪状态。** 下载前，请使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 确认文件已就绪。

## 参数 [#parameters]

| 参数                      | 描述         | 类型                         | 可选 | 默认值 |
| ----------------------- | ---------- | -------------------------- | -- | --- |
| [`requests`](#requests) | 文件请求对象的数组。 | `DownloadFileBatchRequest` | 否  | —   |
| [`options`](#options)   | 下载请求的配置选项。 | `DownloadFileBatchOptions` | 是  | —   |

### `requests` [#requests]

**类型** `DownloadFileBatchRequest` · **必填**

文件请求数组：

```typescript
type DownloadFileBatchRequest = {
  fileId: string;
  branchId?: string;
  locale?: string;
  versionId?: string;
  useLatestAvailableVersion?: boolean;
}[];
```

| 字段                          | 描述                                               | 类型        | 可选 | 默认值     |
| --------------------------- | ------------------------------------------------ | --------- | -- | ------- |
| `fileId`                    | 要下载的文件的唯一标识符。                                    | `string`  | 否  | —       |
| `branchId`                  | 下载所使用的 分支。                                   | `string`  | 是  | 默认分支    |
| `locale`                    | 翻译的目标区域设置。省略时将下载源文件。                             | `string`  | 是  | —       |
| `versionId`                 | 要下载的版本 ID。                                       | `string`  | 是  | 最新版本    |
| `useLatestAvailableVersion` | 如果为 `true` 且未找到指定的 `versionId`，则回退到最新可用版本，而不是报错。 | `boolean` | 是  | `false` |

### `options` [#options]

**类型** `DownloadFileBatchOptions` · **可选**

| 字段        | 描述                | 类型       | 可选 |
| --------- | ----------------- | -------- | -- |
| `timeout` | 请求超时时间 (以毫秒为单位) 。 | `number` | 是  |

## 返回值 [#returns]

**类型** `Promise<DownloadFileBatchResult>`

最终返回一个 `DownloadFileBatchResult`，其中包含已下载的文件及其数量：

```typescript
type DownloadFileBatchResult = {
  files: DownloadedFile[];
  count: number;
};

type DownloadedFile = {
  id: string;
  branchId: string;
  fileId: string;
  versionId: string;
  locale?: string; // 当文件为翻译版本时存在
  fileName?: string; // 适用于源文件（当 locale 不存在时）
  data: string; // 文件内容，以 UTF-8 字符串形式表示
  metadata: JsonObject;
  fileFormat: FileFormat;
};
```

| 属性                   | 描述                      | 类型                  |
| -------------------- | ----------------------- | ------------------- |
| `files`              | 已下载文件对象的数组。             | `DownloadedFile[]`  |
| `count`              | 成功下载的文件数量。              | `number`            |
| `files[].id`         | 已下载文件记录的唯一标识符。          | `string`            |
| `files[].branchId`   | 分支 ID。                  | `string`            |
| `files[].fileId`     | 文件 ID。                  | `string`            |
| `files[].versionId`  | 版本 ID。                  | `string`            |
| `files[].locale`     | 文件的区域设置；当该文件为翻译文件时存在。   | `string` (optional) |
| `files[].fileName`   | 原始文件名；源文件时存在。           | `string` (optional) |
| `files[].data`       | 以 UTF-8 字符串表示的文件内容。     | `string`            |
| `files[].metadata`   | 文件的格式专属元数据。             | `JsonObject`        |
| `files[].fileFormat` | 文件格式 (`JSON`、`MDX` 等) 。 | `FileFormat`        |

## 示例 [#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,
});

// (4) 等待所有翻译完成
const { fileId, versionId, branchId } = uploadedFiles[0];
const result = await gt.awaitJobs(enqueueResult);

if (!result.complete) {
  console.error('Some jobs did not finish in time');
}

// (5) 批量下载所有翻译
const downloadResult = await gt.downloadFileBatch(
  targetLocales.map((locale) => ({
    fileId,
    branchId,
    locale,
  }))
);

downloadResult.files.forEach((file) => {
  console.log(`Downloaded ${file.locale}: ${file.fileName}`);
});
```

## 注意事项 [#notes]

* 文件会以 UTF-8 `string` 形式返回。
* 请先使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 确认文件已可下载。
* 在可能的情况下，文件会按请求项的顺序返回。
* `batch` 中单个文件下载失败，不会导致整个 `batch` 失败。