GT ClassMethodsTranslation
querySourceFile
querySourceFile 方法的 API 参考:获取源文件及其翻译信息
概览
querySourceFile 方法用于检索某个源文件及其所有关联译文的完整信息。
内容包括文件元数据、所有 locales 的翻译状态,以及创建、完成、审批和发布的时间戳。
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(`源文件:${result.sourceFile.fileName}`);
console.log(`支持 ${result.translations.length} 种语言`);参考资料
参数
| 名称 | 类型 | 描述 | 
|---|---|---|
| data | FileQuery | 指定要检索的文件的文件查询对象 | 
| options? | CheckFileTranslationsOptions | 请求的可选配置 | 
FileQuery
| 名称 | 类型 | 描述 | 
|---|---|---|
| fileId | string | 要查询的文件的唯一标识符 | 
| versionId? | string | 特定文件版本的可选 versionId | 
CheckFileTranslationsOptions
| 名称 | 类型 | 描述 | 
|---|---|---|
| timeout? | number | 请求超时时间(毫秒) | 
返回
Promise<FileQueryResult> - 包含源文件信息以及所有 locales 的翻译状态。
type FileQueryResult = {
  sourceFile: {
    id: string;
    fileId: string;
    versionId: 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;
  }[];
}源文件属性
| 属性 | 类型 | 说明 | 
|---|---|---|
| id | string | 内部数据库 ID | 
| fileId | string | 唯一文件标识符 | 
| versionId | string | 版本标识符 | 
| sourceLocale | string | 源语言(sourceLocale) | 
| 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[] | 此文件的目标 locales 列表 | 
翻译属性
| 属性 | 类型 | 描述 | 
|---|---|---|
| locale | string | 目标语言代码(locale code) | 
| completedAt | string | null | 翻译完成的 ISO 时间戳 | 
| approvedAt | string | null | 翻译核准的 ISO 时间戳 | 
| publishedAt | string | null | 翻译发布的 ISO 时间戳 | 
| createdAt | string | null | 翻译任务创建的 ISO 时间戳 | 
| updatedAt | string | null | 上次翻译更新的 ISO 时间戳 | 
示例
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('=== 源文件信息 ===');
  console.log(`名称: ${result.sourceFile.fileName}`);
  console.log(`格式: ${result.sourceFile.fileFormat}`);
  console.log(`源语言: ${result.sourceFile.sourceLocale}`);
  console.log(`创建时间: ${new Date(result.sourceFile.createdAt).toLocaleString()}`);
  console.log(`更新时间: ${new Date(result.sourceFile.updatedAt).toLocaleString()}`);
  
  console.log('\n=== 翻译状态 ===');
  result.translations.forEach(translation => {
    console.log(`${translation.locale}:`);
    console.log(`  创建时间: ${translation.createdAt ? new Date(translation.createdAt).toLocaleString() : '未开始'}`);
    console.log(`  完成时间: ${translation.completedAt ? new Date(translation.completedAt).toLocaleString() : '进行中'}`);
    console.log(`  发布时间: ${translation.publishedAt ? new Date(translation.publishedAt).toLocaleString() : '未发布'}`);
  });
  
  return result;
}
const fileInfo = await getFileInfo('file-123', 'version-456');注意事项
- 返回所有目标 locale 的源文件及其翻译状态
- 翻译时间戳遵循以下生命周期:createdAt→completedAt→approvedAt→publishedAt
- 时间戳为 null 表示尚未进入该阶段
- 源文件中的 locales数组显示为翻译配置的所有目标 locale
- 使用此方法进行详细报告、进度跟踪和文件管理流程
后续步骤
- 查看 checkFileTranslations,轻量化检查特定翻译的状态
- 查看 downloadTranslatedFile,下载已完成的翻译
- 查看 enqueueFiles,为文件启动翻译任务
- 查看 getProjectData,获取项目级信息
这份指南怎么样?

