# generaltranslation: General Translation Core SDK: downloadFile
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/download-file.mdx
---
title: downloadFile
description: 用于下载源文件或翻译后文件的 downloadFile 方法 API 参考
---

## 概述

`downloadFile` 方法会将单个文件的内容下载为 UTF-8 编码的字符串。
是否指定区域设置决定了下载的是源文件还是对应的译文。

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

// 下载翻译
const translatedContent = await gt.downloadFile({
  fileId: 'file-123',
  branchId: 'branch-456',
  locale: 'es',
  versionId: 'version-789'
});

// 下载源文件（未指定区域设置）
const sourceContent = await gt.downloadFile({
  fileId: 'file-123',
  branchId: 'branch-456'
});
```

<Callout>
  **翻译状态：**
  下载翻译时，此方法仅适用于已完成的翻译。
  请先使用 [`queryFileData`](/docs/core/class/methods/translation/query-file-data) 确认翻译已完成，再尝试下载。
</Callout>


## 参考

### 参数

| 名称         | 类型                    | 描述             |
| ---------- | --------------------- | -------------- |
| `file`     | `FileInfo`            | 指定要下载文件的文件信息对象 |
| `options?` | `DownloadFileOptions` | 下载请求的可选配置      |

#### FileInfo 结构

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

#### DownloadFileOptions

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

### 返回值

`Promise<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 spanishContent = await gt.downloadFile({
  fileId,
  branchId,
  locale: 'es'
});

console.log('西班牙语翻译：', spanishContent);
```

***


## 说明

* 以 UTF-8 字符串形式获取已下载的文件
* 提供区域设置时，文件必须已完成该区域设置的翻译
* 未提供区域设置时，返回源文件
* 如果找不到文件，则会失败

## 后续操作

* 请参阅 [`queryFileData`](/docs/core/class/methods/translation/query-file-data)，在下载前确认翻译状态
* 请参阅 [`downloadFileBatch`](/docs/core/class/methods/translation/download-file-batch)，高效下载多个文件
* 请参阅 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files)，了解文件上传流程
* 请参阅 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)，启动翻译任务
* 请参阅 [`awaitJobs`](/docs/core/class/methods/translation/await-jobs)，等待任务完成后再下载