# General Translation Platform: queryFileData
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/query-file-data.mdx
---

title: queryFileData
description: アップロード済みファイルまたは翻訳済みファイルの翻訳状況とメタデータを確認します。queryFileData の API リファレンス。

---

General Translation で、1 つ以上のソースファイルまたは翻訳ファイルに関するデータを照会します。翻訳の進行状況の監視、完了状況の確認、利用可能な翻訳の確認に使用できます。

## 概要 [#overview]

問い合わせるソースファイルおよび/または翻訳済みファイルを指定したオブジェクトを `queryFileData` に渡します。指定した各ファイルのメタデータが返されます。

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

const result = await gt.queryFileData({
  sourceFiles: [{ fileId: 'file-123', versionId: 'version-456', branchId: 'branch-789' }],
  translatedFiles: [
    { fileId: 'file-123', versionId: 'version-456', branchId: 'branch-789', locale: 'es' },
  ],
});
```

シグネチャ:

```typescript
queryFileData(
  data: FileDataQuery,
  options?: CheckFileTranslationsOptions
): Promise<FileDataResult>
```

*注: `queryFileData` を使用するには、GT インスタンスに `apiKey` (または `devApiKey`) と `projectId` の設定が必要です。*

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

* **完了。** 翻訳は、`completedAt` が `null` でなければ完了です。
* **ライフサイクル。** 翻訳は完了していても、公開 (`publishedAt`) される前に承認 (`approvedAt`) が必要な場合があります。
* **バッチ監視。** 複数の翻訳ジョブにまたがるステータスを効率的に確認するために、多数のファイルを一度に照会できます。
* **バージョン管理。** すべてのファイル照会では、ブランチ対応のバージョン管理のために `branchId` が必要です。

## パラメーター [#parameters]

| パラメーター                | 説明                           | 型                              | 任意  | デフォルト |
| --------------------- | ---------------------------- | ------------------------------ | --- | ----- |
| [`data`](#data)       | source と翻訳ファイルのクエリを含むオブジェクト。 | `FileDataQuery`                | いいえ | —     |
| [`options`](#options) | リクエストの設定。                    | `CheckFileTranslationsOptions` | はい  | —     |

### `data` [#data]

**型** `FileDataQuery` · **必須**

クエリ対象のファイル。ソースファイルと翻訳済みファイルに分かれます:

```typescript
type FileDataQuery = {
  sourceFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
  }[];
  translatedFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
    locale: string;
  }[];
};
```

| フィールド             | 説明              | 型          | 任意 |
| ----------------- | --------------- | ---------- | -- |
| `sourceFiles`     | ソースファイルクエリの配列。  | `object[]` | はい |
| `translatedFiles` | 翻訳済みファイルクエリの配列。 | `object[]` | はい |

### `options` [#options]

**型** `CheckFileTranslationsOptions` · **任意**

| フィールド     | 説明                     | 型        | 任意 |
| --------- | ---------------------- | -------- | -- |
| `timeout` | リクエストのタイムアウト時間 (ミリ秒) 。 | `number` | はい |

## 戻り値 [#returns]

**型** `Promise<FileDataResult>`

要求されたソースファイルおよび翻訳済みファイルのメタデータを含む `FileDataResult` が返されます：

```typescript
type FileDataResult = {
  sourceFiles?: {
    branchId: string;
    fileId: string;
    versionId: string;
    fileName: string;
    fileFormat: string;
    dataFormat: string | null;
    createdAt: string;
    updatedAt: string;
    publishedAt: string | null;
    locales: string[];
    sourceLocale: string;
  }[];
  translatedFiles?: {
    fileId: string;
    versionId: string;
    branchId: string;
    locale: string;
    fileFormat: string;
    dataFormat: string | null;
    completedAt: string | null;
    approvedAt: string | null;
    publishedAt: string | null;
    createdAt: string;
    updatedAt: string;
  }[];
};
```

| Property          | 説明              | 型          |
| ----------------- | --------------- | ---------- |
| `sourceFiles`     | ソースファイルのデータの配列。 | `object[]` |
| `translatedFiles` | 翻訳ステータスデータの配列。  | `object[]` |

## 例 [#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 translatedFileQueries = targetLocales.map((locale) => ({
  fileId,
  versionId,
  branchId,
  locale,
}));

while (true) {
  const result = await gt.queryFileData({
    translatedFiles: translatedFileQueries,
  });

  const allCompleted = result.translatedFiles?.every((file) => file.completedAt !== null);

  if (allCompleted) {
    break;
  }

  await new Promise((resolve) => setTimeout(resolve, 1000));
}

// (5) ファイルをダウンロードする
const downloadResult = await gt.downloadFileBatch(
  translatedFileQueries.map(({ fileId, branchId, locale }) => ({
    fileId,
    branchId,
    locale,
  }))
);
```

## メモ [#notes]

* `completedAt` が `null` でなければ、その翻訳は完了しています。
* 翻訳が完了していても、公開 (`publishedAt`) される前に承認 (`approvedAt`) が必要な場合があります。
* 複数の翻訳ジョブを監視する際の効率的なステータス確認には、このメソッドを使用してください。
* すべてのファイルクエリでは、ブランチ対応のバージョン管理のために `branchId` が必要です。