# General Translation Platform: downloadFileBatch
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Download multiple translated files in batches. API reference for downloadFileBatch.

Fetch source or translation files in batches of up to 100 instead of making many individual [`downloadFile`](/docs/platform/core/reference/gt-class-methods/translation/download-file) calls, which reduces network overhead.

## Overview [#overview]

Call `downloadFileBatch` with an array of file requests. Each request can target a translation (with a `locale`) or a source file (without one).

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

Signature:

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

*Note: `downloadFileBatch` requires an API key (including the deprecated `devApiKey` alias), plus `projectId` on the GT instance. Batches run concurrently by default.*

## How it works [#how-it-works]

- **Order.** Match each result to its request by its `fileId`, `branchId`, `versionId`, and `locale` rather than by its position in the response.
- **Locale codes.** If only one requested spelling or alias matches a returned locale, that spelling is used. Otherwise, returned locales follow the [constructor rules](/docs/platform/core/reference/gt-class/constructor#how-it-works). Equivalent requested spellings may share a response label.
- **Partial success.** A successful response can contain fewer files than requested. A rejected batch request rejects the aggregate, without rolling back or stopping batches already started.
- **Readiness.** Use [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) to verify files are ready before downloading.
- **Binary formats.** Text formats return decoded UTF-8 data. `LOTTIE` remains base64-encoded so callers can reconstruct the binary `.lottie` file without corrupting its bytes.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`requests`](#requests) | Array of file request objects. | `DownloadFileBatchRequest` | No | — |
| [`options`](#options) | Configuration for the download request. | `DownloadFileBatchOptions` | Yes | — |

### `requests` [#requests]

**Type** `DownloadFileBatchRequest` · **Required**

An array of file requests:

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

| Field | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `fileId` | Unique identifier of the file to download. | `string` | No | — |
| `branchId` | Branch to download from. | `string` | Yes | default branch |
| `locale` | Target locale for the translation. Omit to download the source file. | `string` | Yes | — |
| `versionId` | Version ID to download. | `string` | Yes | latest version |
| `useLatestAvailableVersion` | If `true` and the specified `versionId` is not found, fall back to the latest available version instead of failing. | `boolean` | Yes | `false` |

### `options` [#options]

**Type** `DownloadFileBatchOptions` · **Optional**

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `timeout` | Request timeout in milliseconds. | `number` | Yes |

## Returns [#returns]

**Type** `Promise<DownloadFileBatchResult>`

Resolves to a `DownloadFileBatchResult` containing downloaded files and a count, but no `pending` details. For those, use generated `downloadFiles` through the [API client](/docs/platform/core/reference/api-client#endpoint-helpers), which returns base64 content:

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

type DownloadedFile = {
  id: string;
  branchId: string;
  fileId: string;
  versionId: string;
  locale?: string; // present when the file is a translation
  fileName?: string; // present for source files (when locale is absent)
  data: string; // UTF-8 text, or base64 for binary formats
  metadata: JsonObject;
  fileFormat: FileFormat;
};
```

| Property | Description | Type |
| --- | --- | --- |
| `files` | Array of downloaded file objects. | `DownloadedFile[]` |
| `count` | Number of files successfully downloaded. | `number` |
| `files[].id` | Unique identifier of the downloaded file record. | `string` |
| `files[].branchId` | Branch ID. | `string` |
| `files[].fileId` | File ID. | `string` |
| `files[].versionId` | Version ID. | `string` |
| `files[].locale` | Locale of the file, present when it is a translation. | `string` (optional) |
| `files[].fileName` | Original file name, present for source files. | `string` (optional) |
| `files[].data` | UTF-8 file content for text formats, or base64-encoded binary content for `LOTTIE`. | `string` |
| `files[].metadata` | Format-specific metadata for the file. | `JsonObject` |
| `files[].fileFormat` | Format of the file (`JSON`, `MDX`, and so on). | [`FileFormat`](/docs/platform/core/reference/types/file-format) |

## Examples [#examples]

```typescript title="index.ts"
import { GT } from 'generaltranslation';
import type { FileUpload } from 'generaltranslation/types';

const fileContents = '{"greeting":"Hello"}';
const filePath = 'en.json';

// (1) Create a GT instance
const targetLocales = ['es', 'fr', 'de'];
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// (2) Upload the file
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [{ source: fileUpload }];
const { uploadedFiles } = await gt.uploadSourceFiles(files, { sourceLocale: 'en' });

// (3) Enqueue the file translation job
const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: targetLocales,
});

// (4) Wait for all translations to be completed
const { fileId, versionId, branchId } = uploadedFiles[0];
const result = await gt.awaitJobs(enqueueResult, { timeoutSeconds: 300 });

if (!result.complete || result.jobs.some((job) => job.status !== 'completed')) {
  throw new Error('Translations are not ready to download');
}

// (5) Download all translations in a batch
const downloadResult = await gt.downloadFileBatch(
  targetLocales.map((locale) => ({
    fileId,
    versionId,
    branchId,
    locale,
  }))
);

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

## Notes [#notes]

- Text files are returned as UTF-8 strings. Decode `LOTTIE` data from base64 to write the binary `.lottie` file.
- Use [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) to verify files are ready for download first.
- Match results to requests by their file, version, branch, and locale identifiers rather than by position.
- Partial successful responses differ from request failures: a rejected batch request rejects the aggregate.

## Sitemap

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