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

title: queryFileData
description: 检查已上传文件或翻译后的文件的翻译状态和元数据。queryFileData 的 API 参考。

---

使用 General Translation 查询一个或多个源文件或翻译文件的数据。可用于监控翻译进度、检查完成状态，并查看有哪些翻译可用。

## 概览 [#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`，以支持 branch 的版本控制。

## 参数 [#parameters]

| 参数                    | 描述               | 类型                             | 可选 | 默认值 |
| --------------------- | ---------------- | ------------------------------ | -- | --- |
| [`data`](#data)       | 包含源内容和翻译文件查询的对象。 | `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;
  }[];
};
```

| Field             | Description         | Type       | Optional |
| ----------------- | ------------------- | ---------- | -------- |
| `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;
  }[];
};
```

| 属性                | 描述        | 类型         |
| ----------------- | --------- | ---------- |
| `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`，以便在支持 branch 的情况下进行版本控制。