# generaltranslation: General Translation Core SDK: querySourceFile
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/query-source-file.mdx
---
title: querySourceFile
description: querySourceFile 方法的 API 参考，用于获取源文件和翻译信息
---

## 概述

`querySourceFile` 方法用于获取某个源文件及其所有关联翻译的完整信息。
其中包括文件元数据、所有区域设置的翻译状态，以及创建、完成、批准和发布的时间戳。

```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`);
```


## 参考

### 参数

| 名称         | 类型                             | 描述                 |
| ---------- | ------------------------------ | ------------------ |
| `data`     | `FileQuery`                    | 用于指定要获取哪个文件的文件查询对象 |
| `options?` | `CheckFileTranslationsOptions` | 请求的可选配置项           |

#### FileQuery

| 名称           | 类型       | 描述             |
| ------------ | -------- | -------------- |
| `fileId`     | `string` | 要查询的文件的唯一标识符   |
| `versionId?` | `string` | 特定文件版本的可选版本 ID |
| `branchId?`  | `string` | 特定分支的可选分支 ID   |

#### CheckFileTranslationsOptions

| 名称         | 类型       | 说明           |
| ---------- | -------- | ------------ |
| `timeout?` | `number` | 请求超时时长 (毫秒)  |

### 返回值

`Promise<FileQueryResult>` - 包含所有区域设置的源文件信息和翻译状态。

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


#### 源文件属性

| Property             | Type             | Description                 |
| -------------------- | ---------------- | --------------------------- |
| `id`                 | `string`         | 内部数据库 ID                    |
| `fileId`             | `string`         | 文件唯一标识符                     |
| `versionId`          | `string`         | 版本标识符                       |
| `branchId`           | `string`         | 分支标识符                       |
| `sourceLocale`       | `string`         | 源语言区域设置                     |
| `fileName`           | `string`         | 原始文件名                       |
| `fileFormat`         | `string`         | 文件格式 (JSON、MD、MDX 等)        |
| `dataFormat`         | `string \| null` | 文件内的数据格式 (ICU、I18NEXT、JSX)  |
| `createdAt`          | `string`         | 文件创建时间的 ISO 时间戳             |
| `updatedAt`          | `string`         | 最后更新时间的 ISO 时间戳             |
| `approvalRequiredAt` | `string \| null` | 请求审批时的 ISO 时间戳              |
| `locales`            | `string[]`       | 此文件的目标区域设置列表                |

#### 翻译属性

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

***

## 示例

```typescript title="index.ts" copy
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(`Branch: ${result.sourceFile.branchId}`);
  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');
```

***


## 说明

* 返回所有目标区域设置的源文件及其翻译状态
* 翻译时间戳遵循以下生命周期：`createdAt` -&gt; `completedAt` -&gt; `approvedAt` -&gt; `publishedAt`
* 时间戳为 null 表示该阶段尚未到达
* 源文件中的 `locales` 数组会显示所有已配置用于翻译的目标区域设置
* 响应中包含 `branchId`，以便在支持分支的情况下进行正确的版本控制
* 可使用此方法进行详细报告、进度跟踪和文件管理工作流

## 后续步骤

* 参见 [`queryFileData`](/docs/core/class/methods/translation/query-file-data)，批量检查特定翻译的状态
* 参见 [`downloadFile`](/docs/core/class/methods/translation/download-file)，下载已完成的翻译
* 参见 [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)，为文件启动翻译任务
* 参见 [`getProjectData`](/docs/core/class/methods/translation/get-project-data)，了解项目级信息