# generaltranslation: General Translation Core SDK: downloadFileBatch
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/download-file-batch.mdx
---
title: downloadFileBatch
description: 用于在单个请求中下载多个文件的 downloadFileBatch 方法 API 参考
---

## 概述

`downloadFileBatch` 方法可通过一次批量请求下载多个源文件或译文文件。

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

<Callout>
  **批量下载效率：**
  此方法已针对单次 API 调用下载多个文件进行了优化；与多次单独调用 `downloadFile` 相比，可减少网络开销并提升性能。
</Callout>


## 参考

### 参数

| 名称         | 类型                         | 描述         |
| ---------- | -------------------------- | ---------- |
| `requests` | `DownloadFileBatchRequest` | 文件请求对象的数组  |
| `options?` | `DownloadFileBatchOptions` | 下载请求的可选配置项 |

#### DownloadFileBatchRequest

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

| Name                         | Type      | Description                                                    |
| ---------------------------- | --------- | -------------------------------------------------------------- |
| `fileId`                     | `string`  | 要下载文件的唯一标识符                                                    |
| `branchId?`                  | `string`  | 要下载的分支 ID。如果未提供，则使用默认分支                                        |
| `locale?`                    | `string`  | 翻译的目标区域设置。如果未提供，则下载源文件                                         |
| `versionId?`                 | `string`  | 要下载的版本 ID。如果未提供，则使用最新版本                                        |
| `useLatestAvailableVersion?` | `boolean` | 如果为 `true` 且找不到指定的 `versionId`，则会回退到最新可用版本，而不是直接失败。默认为 `false` |


#### DownloadFileBatchOptions

| 名称         | 类型       | 说明           |
| ---------- | -------- | ------------ |
| `timeout?` | `number` | 请求超时时长 (毫秒)  |

### 返回值

`Promise<DownloadFileBatchResult>` - 包含下载的文件及其元数据。

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

| 属性      | 类型       | 描述        |
| ------- | -------- | --------- |
| `files` | `File[]` | 已下载文件对象数组 |
| `count` | `number` | 成功下载的文件数量 |


#### 文件结构

```typescript
type File = {
  fileId: string;
  branchId?: string;
  locale?: string;
  versionId?: string;
  fileName: string;
  data: string;
}
```

| 属性          | 类型       | 描述                 |
| ----------- | -------- | ------------------ |
| `fileId`    | `string` | 文件 ID              |
| `branchId`  | `string` | 分支 ID              |
| `locale`    | `string` | 文件的区域设置 (如果是翻译文件)  |
| `versionId` | `string` | 版本 ID              |
| `fileName`  | `string` | 原始文件名              |
| `data`      | `string` | UTF-8 字符串形式的文件内容   |

***


## 示例

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

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

if (!result.complete) {
  console.error('部分任务未能在规定时间内完成');
}

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

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

***


## 注意事项

* 文件会以 UTF-8 字符串形式返回
* 请先使用 [`queryFileData`](/docs/core/class/methods/translation/query-file-data) 确认文件已可供下载
* 在可能的情况下，返回文件的顺序会与请求项的顺序一致
* 批量中的单个文件下载失败不会导致整个批量请求失败

## 后续步骤

* 单个文件下载请参阅 [`downloadFile`](/docs/core/class/methods/translation/download-file)
* 请参阅 [`queryFileData`](/docs/core/class/methods/translation/query-file-data) 确认文件是否已可供下载
* 启动翻译任务请参阅 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)