# General Translation Platform: downloadFileBatch
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在一次请求中下载多个翻译后的文件。downloadFileBatch 的 API 参考。

在一次请求中获取多个源文件或翻译文件，而不是多次单独调用 [`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`](/docs/platform/core/reference/gt-class-methods/translation/download-file) 更高效。*

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

* **顺序。** 根据每个结果的 `fileId`、`branchId`、`versionId` 和 `locale` 将其与对应的请求匹配，而非根据其在响应中的位置。

- **区域设置解析。** 每个请求的区域设置都会解析为用于存储的受支持区域设置。等效代码可能解析为同一条已存储的翻译；如果同时请求 `ja` 和 `ja-JP`，每个请求都会生成一个标有传入区域设置的结果。

* **部分成功。** 批量中某个文件下载失败，不会导致整个批量失败。
* **就绪状态。** 下载前，请使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 确认文件已就绪。

- **二进制格式。** 文本格式返回解码后的 UTF-8 数据。`LOTTIE` 保持为 Base64 编码，以便调用方重建二进制 `.lottie` 文件时不会损坏其字节。

## 参数 [#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 文本，二进制格式则为 base64
  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 文件内容，或 `LOTTIE` 的 Base64 编码二进制内容。 | `string`                                                        |
| `files[].metadata`   | 文件的格式专属元数据。                                   | `JsonObject`                                                    |
| `files[].fileFormat` | 文件格式 (`JSON`、`MDX` 等) 。                       | [`FileFormat`](/docs/platform/core/reference/types/file-format) |

## 示例 [#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` 形式返回。请将 `LOTTIE` 数据从 base64 解码，以写入二进制 `.lottie` 文件。
* 请先使用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 确认文件已就绪可下载。
* 请根据文件、版本、分支 和区域设置内部标识符匹配结果与请求，而非根据位置匹配。
* `批量` 中单个文件下载失败，不会导致整个 `批量` 失败。

## Sitemap

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