# General Translation Platform: downloadFileBatch
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Скачивание нескольких переведённых файлов одним запросом. Справочник API для downloadFileBatch.

Получайте несколько исходных файлов или файлов перевода одним запросом вместо множества отдельных вызовов [`downloadFile`](/docs/platform/core/reference/gt-class-methods/translation/download-file), что позволяет уменьшить сетевые издержки.

## Обзор [#overview]

Вызовите `downloadFileBatch`, передав массив запросов на файлы. Каждый запрос может относиться либо к переводу (с `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;
}[];
```

| Field                       | Description                                                                                                 | Type      | Optional | Default            |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- | --------- | -------- | ------------------ |
| `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; // присутствует для исходных файлов (когда локаль отсутствует)
  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 для текстовых форматов или двоичное содержимое в кодировке Base64 для `LOTTIE`. | `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. Декодируйте данные `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.