# General Translation Platform: Translating files
URL: https://generaltranslation.com/en-GB/docs/platform/core/guides/translating-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to upload, translate, and download files with the generaltranslation library.

The `generaltranslation` library can translate full source files. This page explains the workflows for uploading, queuing, checking status, and downloading files.

## Before you start [#before-start]

Make sure you've completed the [Quickstart](/docs/platform/core/quickstart) to install `generaltranslation` and initialise the [GT](/docs/platform/core/reference/gt-class/constructor) class.

## How file translation works [#file-translation-works]

Files are translated as jobs:

1. Upload the source file.
2. Queue the file for translation.
3. Check translation status.
4. Download the translated file.

File translation uses multiple calls because projects often translate many files. Separate steps give you more flexibility when using the API, making it easier to process files in batches, retry failed work, poll jobs, and download output when ready.

Uploading creates source-file records. Calling [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) can then launch one job for each source-file and target-locale pair that still requires work. (See the [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) and [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) methods for more information).

For SVG files, pass the UTF-8 XML source with `fileFormat: 'SVG'`. Translation updates text nodes while preserving shapes and styles. An asynchronous layout pass can recentre text and shorten overflowing translations while preserving authored font sizes, so wait until the file is complete before downloading it. Malformed XML is rejected.

## 1. Upload the source file [#upload]

For example, this guide translates this English JSON file:

```json
{
  "hello": "Hello",
  "world": "World"
}
```

Read the file, format its contents, and then call [uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) to upload files.

```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import type { FileUpload } from 'generaltranslation/types';

// (i) Read the contents of a file
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) Format the file contents
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) Upload the file
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);
```

The response returns a list of file references. This allows you to queue the file for translation later, check its status, and download the translated file.

```ts title="Output"
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    branchId: '123456789',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]
```

## 2. Queue the file for translation [#enqueue]

Use [enqueueFiles](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) with the uploaded file reference and target locales. In this example, we will translate it into Spanish (`es`).

```typescript title="src/index.ts"
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  branchId: uploadedFiles[0].branchId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};

const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
    sourceLocale: 'en',
    targetLocales: ['es'],
  }
);
```

The response includes a result with job information.

```ts title="Output"
{
  jobData: {
    'job-123456': {
      sourceFileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      targetLocale: 'es',
      projectId: 'your-project-id',
      force: false
    }
  },
  locales: ['es'],
  message: 'Successfully enqueued 1 file translation jobs in 1 batch(es)'
}
```

## 3. Check file status [#status]

Use [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) to check whether the translated file is complete and ready for download.

```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];

const status = await gt.queryFileData({
  translatedFiles: [
    {
      fileId,
      versionId,
      branchId,
      locale: 'es',
    },
  ],
});
```

If the file is still being translated, `completedAt` is `null`. Once complete, it contains a timestamp:

```ts title="Output"
{
  translatedFiles: [
    {
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      locale: 'es',
      completedAt: '2024-01-15T12:00:00Z'
    }
  ]
}
```

## 4. Download the translated file [#download]

Finally, download the translated file with the [downloadFile](/docs/platform/core/reference/gt-class-methods/translation/download-file) method.

```typescript title="src/index.ts"
const content = await gt.downloadFile({
  fileId,
  versionId,
  branchId,
  locale: 'es',
});
```

The response returns the translated file content. This example returns:

```json title="Output"
{
  "hello": "Hola",
  "world": "Mundo"
}
```

## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/locale-codes

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.