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

title: querySourceFile
description: 获取源文件元数据及相关翻译信息。querySourceFile 的 API 参考。

---

使用 General Translation 获取源文件及其所有翻译的完整信息。其中包括文件元数据、各个区域设置下的翻译状态，以及创建、完成、批准和发布的时间戳。

## 概览 [#overview]

调用 `querySourceFile`，并传入用于标识该文件的 query。该方法会返回源文件的元数据，以及每个区域设置对应的一条翻译条目。

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

const result = await gt.querySourceFile({
  fileId: 'file-123',
  versionId: 'version-456',
});

console.log(`Source file: ${result.sourceFile.fileName}`);
console.log(`Available in ${result.translations.length} locales`);
```

签名：

```typescript
querySourceFile(
  data: FileQuery,
  options?: CheckFileTranslationsOptions
): Promise<FileQueryResult>
```

*注意：`querySourceFile` 要求在 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。*

## 工作原理 [#how-it-works]

* **完整的翻译状态。** 返回源文件以及每个目标区域设置的翻译状态。
* **时间戳的生命周期。** 翻译时间戳按 `createdAt` → `completedAt` → `approvedAt` → `publishedAt` 的顺序流转。时间戳为 `null` 表示尚未进入该阶段。
* **已配置的区域设置。** 源文件中的 `locales` 数组列出了为翻译配置的所有目标区域设置。

## 参数 [#parameters]

| 参数                    | 描述                | 类型                             | 可选 | 默认值 |
| --------------------- | ----------------- | ------------------------------ | -- | --- |
| [`data`](#data)       | 用于指定要获取哪个文件的文件查询。 | `FileQuery`                    | 否  | —   |
| [`options`](#options) | 请求的配置。            | `CheckFileTranslationsOptions` | 是  | —   |

### `data` [#data]

**类型** `FileQuery` · **必填**

用于标识要查询的文件：

| 字段          | 描述                  | 类型       | 可选 |
| ----------- | ------------------- | -------- | -- |
| `fileId`    | 要查询文件的唯一标识符。        | `string` | 否  |
| `versionId` | 特定文件版本的 Version ID。 | `string` | 是  |
| `branchId`  | 特定分支的 Branch ID。    | `string` | 是  |

### `options` [#options]

**类型** `CheckFileTranslationsOptions` · **可选**

| 字段        | 描述                | 类型       | 可选 |
| --------- | ----------------- | -------- | -- |
| `timeout` | 请求超时时间 (以毫秒为单位) 。 | `number` | 是  |

## 返回值 [#returns]

**类型** `Promise<FileQueryResult>`

解析结果为一个 `FileQueryResult`，其中包含源文件信息以及所有区域设置的翻译状态：

```typescript
type FileQueryResult = {
  sourceFile: {
    id: string;
    fileId: string;
    versionId: string;
    sourceLocale: string;
    fileName: string;
    fileFormat: string;
    dataFormat: string | null;
    createdAt: string;
    updatedAt: string;
    locales: string[];
  };
  translations: {
    locale: string;
    completedAt: string | null;
    approvedAt: string | null;
    publishedAt: string | null;
    createdAt: string | null;
    updatedAt: string | null;
  }[];
};
```

源文件属性：

| 属性             | 说明                           | 类型               |
| -------------- | ---------------------------- | ---------------- |
| `id`           | 内部数据库 ID。                    | `string`         |
| `fileId`       | 文件的唯一标识符。                    | `string`         |
| `versionId`    | 版本标识符。                       | `string`         |
| `sourceLocale` | 源语言的区域设置。                    | `string`         |
| `fileName`     | 原始文件名。                       | `string`         |
| `fileFormat`   | 文件格式 (JSON、MD、MDX 等) 。       | `string`         |
| `dataFormat`   | 文件内的数据格式 (ICU、I18NEXT、JSX) 。 | `string \| null` |
| `createdAt`    | 文件创建时间的 ISO 时间戳。             | `string`         |
| `updatedAt`    | 文件最后更新时间的 ISO 时间戳。           | `string`         |
| `locales`      | 此文件的目标区域设置列表。                | `string[]`       |

翻译属性：

| 属性            | 说明                 | 类型               |
| ------------- | ------------------ | ---------------- |
| `locale`      | 目标区域设置代码。          | `string`         |
| `completedAt` | 翻译完成时间的 ISO 时间戳。   | `string \| null` |
| `approvedAt`  | 翻译获批时间的 ISO 时间戳。   | `string \| null` |
| `publishedAt` | 翻译发布时间的 ISO 时间戳。   | `string \| null` |
| `createdAt`   | 翻译任务创建时间的 ISO 时间戳。 | `string \| null` |
| `updatedAt`   | 翻译最后更新时间的 ISO 时间戳。 | `string \| null` |

## 示例 [#examples]

```typescript title="index.ts"
import { GT } from 'generaltranslation';

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

async function getFileInfo(fileId: string, versionId?: string) {
  const result = await gt.querySourceFile({
    fileId,
    versionId,
  });

  console.log('=== Source File Info ===');
  console.log(`Name: ${result.sourceFile.fileName}`);
  console.log(`Format: ${result.sourceFile.fileFormat}`);
  console.log(`Source Locale: ${result.sourceFile.sourceLocale}`);
  console.log(`Created: ${new Date(result.sourceFile.createdAt).toLocaleString()}`);
  console.log(`Updated: ${new Date(result.sourceFile.updatedAt).toLocaleString()}`);

  console.log('\n=== Translation Status ===');
  result.translations.forEach((translation) => {
    console.log(`${translation.locale}:`);
    console.log(
      `  Created: ${translation.createdAt ? new Date(translation.createdAt).toLocaleString() : 'Not started'}`
    );
    console.log(
      `  Completed: ${translation.completedAt ? new Date(translation.completedAt).toLocaleString() : 'In progress'}`
    );
    console.log(
      `  Published: ${translation.publishedAt ? new Date(translation.publishedAt).toLocaleString() : 'Not published'}`
    );
  });

  return result;
}

const fileInfo = await getFileInfo('file-123', 'version-456');
```

## 注意事项 [#notes]

* 返回所有目标区域设置的源文件及其翻译状态。
* 翻译时间戳遵循 `createdAt` → `completedAt` → `approvedAt` → `publishedAt` 的生命周期；时间戳为 `null` 表示该阶段尚未达到。
* 源文件中的 `locales` 数组会显示为翻译配置的所有目标区域设置。
* 可使用此方法进行详细报告、进度跟踪和文件管理工作流。