# generaltranslation: General Translation Core SDK: queryFileData
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/query-file-data.mdx
---
title: queryFileData
description: 用于查询源文件和翻译文件数据的 queryFileData 方法 API 参考
---

## 概述

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


## 参考文档

### 参数

| 名称         | 类型                             | 说明                |
| ---------- | ------------------------------ | ----------------- |
| `data`     | `FileDataQuery`                | 包含源文件和翻译文件查询条件的对象 |
| `options?` | `CheckFileTranslationsOptions` | 该请求的可选配置          |

#### FileDataQuery

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

| 名称                 | 类型         | 说明          |
| ------------------ | ---------- | ----------- |
| `sourceFiles?`     | `object[]` | 源文件查询对象数组   |
| `translatedFiles?` | `object[]` | 已翻译文件查询对象数组 |


#### CheckFileTranslationsOptions

| 名称         | 类型       | 说明               |
| ---------- | -------- | ---------------- |
| `timeout?` | `number` | 请求超时时间 (以毫秒为单位)  |

### 返回值

`Promise<FileDataResult>` - 包含源文件和翻译文件的数据。

```typescript
type FileDataResult = {
  sourceFiles?: {
    branchId: string;
    fileId: string;
    versionId: string;
    fileName: string;
    fileFormat: string;
    dataFormat: string | null;
    createdAt: string;
    updatedAt: string;
    approvalRequiredAt: string | null;
    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[]` | 翻译状态数据的数组 |

***


## 示例

### 基本用法

查询特定源文件和翻译文件中的数据：

```typescript title="index.ts" copy
// (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
  }))
);
```

***


## 说明

* 当 `completedAt` 不为 `null` 时，表示翻译已完成
* 已完成的翻译在发布 (`publishedAt`) 前，仍可能需要先通过审核 (`approvedAt`) 
* 监控多个翻译任务时，使用此方法可高效检查状态
* 所有文件查询都需要提供 `branchId`，以确保版本正确

## 后续步骤

* 查看[快速开始](/docs/core/quickstart#translate-your-first-file)，了解如何使用此方法的完整示例
* 参见 [`downloadFile`](/docs/core/class/methods/translation/download-file) 下载已完成的翻译
* 参见 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files) 创建翻译任务
* 参见 [`querySourceFile`](/docs/core/class/methods/translation/query-source-file) 获取源文件和翻译信息