querySourceFile
API reference for the querySourceFile method to retrieve 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 statuses across all locales, and timestamps for creation, completion, approval, and publication.
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
| Name | Type | Description |
|---|---|---|
data | FileQuery | File query object specifying which file to retrieve |
options? | CheckFileTranslationsOptions | Optional configuration for the request |
FileQuery
| Name | Type | Description |
|---|---|---|
fileId | string | Unique identifier of the file to query |
versionId? | string | Optional version ID for the specific file version |
CheckFileTranslationsOptions
| Name | Type | Description |
|---|---|---|
timeout? | number | Request 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
| Property | Type | Description |
|---|---|---|
id | string | Internal database ID |
fileId | string | Unique file identifier |
versionId | string | Version identifier |
sourceLocale | string | Source language locale |
fileName | string | Original file name |
fileFormat | string | File format (JSON, MD, MDX, etc.) |
dataFormat | string | null | Data format within file (ICU, I18NEXT, JSX) |
createdAt | string | ISO timestamp of file creation |
updatedAt | string | ISO timestamp of last update |
approvalRequiredAt | string | null | ISO timestamp when approval was requested |
locales | string[] | List of target locales for this file |
Translation Properties
| Property | Type | Description |
|---|---|---|
locale | string | Target locale code |
completedAt | string | null | ISO timestamp when the translation was completed |
approvedAt | string | null | ISO timestamp when the translation was approved |
publishedAt | string | null | ISO timestamp when the translation was published |
createdAt | string | null | ISO timestamp when the translation job was created |
updatedAt | string | null | ISO timestamp of the last translation update |
Example
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:
createdAt→completedAt→approvedAt→publishedAt - Null timestamps indicate that a stage hasn’t been reached yet
- The
localesarray in the source file lists all target locales configured for translation - Use this method for detailed reporting, progress tracking, and file‑management workflows
Next steps
- See
checkFileTranslationsfor lightweight status checks of specific translations - See
downloadTranslatedFileto download completed translations - See
enqueueFilesto start translation jobs for files - See
getProjectDatafor project-level information
How is this guide?