# General Translation Platform: downloadFileBatch
URL: https://generaltranslation.com/ja/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) 呼び出しを行う代わりに、最大 100 件ずつのバッチでソースファイルまたは翻訳ファイルを取得でき、ネットワークのオーバーヘッドを減らせます。

## 概要 [#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 インスタンスに API キー (非推奨のエイリアスである `devApiKey` も可) と `projectId` の設定が必要です。バッチはデフォルトで並行して実行されます。*

## 仕組み [#how-it-works]

* **順序。** レスポンス内の位置ではなく、`fileId`、`branchId`、`versionId`、`locale` を使用して、各結果を対応するリクエストに関連付けます。
* **ロケールコード。** 返されたロケールに一致する、リクエスト時の表記またはエイリアスが1つだけの場合は、その表記が使用されます。それ以外の場合、返されるロケールは[コンストラクターのルール](/docs/platform/core/reference/gt-class/constructor#how-it-works)に従います。同等の表記を複数指定してリクエストした場合、それらのレスポンスで同じラベルが共有されることがあります。
* **部分的な成功。** 成功したレスポンスでも、含まれるファイルがリクエストした数より少ない場合があります。バッチリクエストが1つでも拒否されると全体の結果も拒否されますが、すでに開始されたバッチがロールバックされたり停止されたりすることはありません。
* **準備状況。** ダウンロードする前に、[`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) を使用してファイルの準備ができていることを確認してください。
* **バイナリ形式。** テキスト形式ではデコード済みの UTF-8 データが返されます。呼び出し元がバイトを破損させずにバイナリ `.lottie` ファイルを再構築できるよう、`LOTTIE` はBase64エンコードされたままです。

## パラメータ [#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]

**Type** `DownloadFileBatchOptions` · **任意**

| Field     | Description            | Type     | Optional |
| --------- | ---------------------- | -------- | -------- |
| `timeout` | リクエストのタイムアウト時間 (ミリ秒) 。 | `number` | はい       |

## 戻り値 [#returns]

**型** `Promise<DownloadFileBatchResult>`

ダウンロードされたファイルと件数を含む `DownloadFileBatchResult` を返しますが、`pending` の詳細は含まれません。これらが必要な場合は、[API クライアント](/docs/platform/core/reference/api-client#endpoint-helpers)から生成された `downloadFiles` を使用してください。こちらは base64 形式のコンテンツを返します:

```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`     | File ID。                                                 | `string`                                                        |
| `files[].versionId`  | バージョン ID。                                                | `string`                                                        |
| `files[].locale`     | ファイルのロケール。翻訳ファイルの場合に含まれます。                               | `string` (任意)                                             |
| `files[].fileName`   | 元のファイル名。ソースファイルの場合に含まれます。                                | `string` (任意)                                             |
| `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"
import { GT } from 'generaltranslation';
import type { FileUpload } from 'generaltranslation/types';

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

// (1) GTインスタンスを作成する
const targetLocales = ['es', 'fr', 'de'];
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// (2) ファイルをアップロードする
const fileUpload: 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, { timeoutSeconds: 300 });

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

// (5) すべての翻訳をバッチでダウンロードする
const downloadResult = await gt.downloadFileBatch(
  targetLocales.map((locale) => ({
    fileId,
    versionId,
    branchId,
    locale,
  }))
);

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

## メモ [#notes]

* テキストファイルは UTF-8 文字列として返されます。バイナリ `.lottie` ファイルを書き込むには、`LOTTIE` データを base64 からデコードしてください。
* まず [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) を使って、ファイルをダウンロード可能な状態かどうかを確認してください。
* 結果は位置ではなく、ファイル、バージョン、ブランチ、ロケールの識別子 でリクエストと照合してください。
* 一部のみ成功したレスポンスは、リクエストの失敗とは異なります。バッチリクエストが 1 つでも拒否されると、集約結果全体が拒否されます。

## Sitemap

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