# General Translation Platform: downloadFile
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/download-file.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 翻译完成后下载单个翻译后的文件。downloadFile 的 API 参考。

使用 General Translation 以 UTF-8 字符串形式下载单个文件的内容。根据你是否传入区域设置，它会返回源文件或对应的翻译。

## 概览 [#overview]

使用文件描述符调用 `downloadFile`。如需下载译文，请包含 `locale` (区域设置) ；如需下载源文件，则省略该参数。

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

签名：

```typescript
downloadFile(
  file: {
    fileId: string;
    branchId?: string;
    locale?: string;
    versionId?: string;
    useLatestAvailableVersion?: boolean;
  },
  options?: DownloadFileOptions
): Promise<string>
```

*注意：`downloadFile` 要求 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。下载翻译时，它仅适用于已完成的翻译——请先用 [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) 确认状态。*

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

* **源文件与翻译。** 提供 `locale` 时，文件必须已有解析后的受支持区域设置的已完成的翻译。未提供 `locale` 时，则返回源文件。
* **区域设置解析。** 请求的区域设置会被解析为用于存储的受支持区域设置。例如，`ja-JP` 会解析为 `ja`；不同的受支持区域设置 (如 `en-GB`) 保持不变。
* **保留原始格式。** 返回的字符串与原始源文件格式一致；对于翻译内容，所有可翻译文本都会转换为目标区域设置。
* **失败。** 如果找不到文件，调用会失败。

## 参数 [#parameters]

| 参数                    | 描述              | 类型                    | 可选 | 默认值 |
| --------------------- | --------------- | --------------------- | -- | --- |
| [`file`](#file)       | 用于指定要下载文件的文件信息。 | `object`              | 否  | —   |
| [`options`](#options) | 下载请求的配置。        | `DownloadFileOptions` | 是  | —   |

### `file` [#file]

**类型** `object` · **必填**

用于标识要下载的文件：

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

### `options` [#options]

**类型** `DownloadFileOptions` · **可选**

| 字段        | 说明            | 类型       | 可选 |
| --------- | ------------- | -------- | -- |
| `timeout` | 请求超时时间 (毫秒) 。 | `number` | 是  |

## 返回值 [#returns]

**类型** `Promise<string>`

解析结果为源文件内容的 UTF-8 字符串，格式与原始源文件相同。对于翻译，所有可翻译文本都会转换为目标区域设置。

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

console.log('Spanish translation:', spanishContent);
```

## 备注 [#notes]

* 以 UTF-8 字符串形式返回已下载的文件。
* 提供 `locale` 时，文件必须已完成其解析后的受支持区域设置的翻译。
* 未提供 `locale` 时，返回源文件。
* 如果找不到文件，调用会失败。

## Sitemap

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