GT ClassMethodsTranslation

querySourceFile

API Reference for the querySourceFile method to get source file and translation information

Overview

The querySourceFile method retrieves comprehensive information about a source file and all its associated translations. This includes file metadata, translation status across all locales, and timestamps for creation, completion, approval, and publishing.

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

Reference

Parameters

NameTypeDescription
dataFileQueryFile query object specifying which file to retrieve
options?CheckFileTranslationsOptionsOptional configuration for the request

FileQuery

NameTypeDescription
fileIdstringUnique identifier of the file to query
versionId?stringOptional version ID for the specific file version

CheckFileTranslationsOptions

NameTypeDescription
timeout?numberRequest timeout in milliseconds

Returns

Promise<FileQueryResult> - Contains source file information and translation status for all 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;
  }[];
}

Source File Properties

PropertyTypeDescription
idstringInternal database ID
fileIdstringUnique file identifier
versionIdstringVersion identifier
sourceLocalestringSource language locale
fileNamestringOriginal file name
fileFormatstringFile format (JSON, MD, MDX, etc.)
dataFormatstring | nullData format within file (ICU, I18NEXT, JSX)
createdAtstringISO timestamp of file creation
updatedAtstringISO timestamp of last update
approvalRequiredAtstring | nullISO timestamp when approval was requested
localesstring[]List of target locales for this file

Translation Properties

PropertyTypeDescription
localestringTarget locale code
completedAtstring | nullISO timestamp of translation completion
approvedAtstring | nullISO timestamp of translation approval
publishedAtstring | nullISO timestamp of translation publishing
createdAtstring | nullISO timestamp of translation job creation
updatedAtstring | nullISO timestamp of last translation update

Example

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

  • Returns the source file and translation status for all target locales
  • Translation timestamps follow the lifecycle: createdAtcompletedAtapprovedAtpublishedAt
  • Null timestamps indicate that stage hasn't been reached yet
  • The locales array in the source file shows all target locales configured for translation
  • Use this method for detailed reporting, progress tracking, and file management workflows

Next Steps

How is this guide?

querySourceFile