# General Translation Platform: uploadTranslations
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/translation/upload-translations.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Upload existing translated files that correspond to source files. API reference for uploadTranslations.

Uploads existing translations for source files that are already in the project. Use it when migrating translations or uploading human-reviewed ones instead of generating them through the translation service.

## Overview [#overview]

Call `uploadTranslations` with an array of translation uploads and an options object. Each upload includes the complete source content used to identify an already uploaded source file, plus one or more translated files.

```typescript
const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' });

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en',
});
```

Signature:

```typescript
uploadTranslations(
  files: { source: FileUpload; translations: FileUpload[] }[],
  options: UploadFilesOptions
): Promise<UploadFilesResponse>
```

*Note: `uploadTranslations` requires an `apiKey` (or `devApiKey`) and `projectId` on the GT instance.*

## How it works [#how-it-works]

- **Existing source.** Upload the source first. The `source` object is still a complete `FileUpload`, including content and locale; the API derives missing IDs from that data and uses the resulting IDs to find the existing source version.
- **Translations.** Each item in the `translations` array must include content and a target locale.
- **File encoding.** Text content is automatically base64-encoded. Binary `LOTTIE` translations must already contain base64-encoded `.lottie` ZIP data.
- **Versioning.** Returned file references include `branchId` for versioning with branch support.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`files`](#files) | Array of source files with their translations. | `{ source: FileUpload; translations: FileUpload[] }[]` | No | — |
| [`options`](#options) | Configuration options for the upload. | `UploadFilesOptions` | No | — |

### `files`

**Type** `{ source: FileUpload; translations: FileUpload[] }[]` · **Required**

Each entry pairs a complete source file with its translated files:

```typescript
{
  source: FileUpload; // source content and metadata
  translations: FileUpload[]; // translated files with content
}
```

The `source` value uses these `FileUpload` fields:

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `content` | Raw source text, or base64-encoded binary content for `LOTTIE`. | `string` | No |
| `fileName` | File name matching the previously uploaded source file. | `string` | No |
| `fileFormat` | Format of the file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No |
| `locale` | Locale of the source content. | `string` | No |
| `dataFormat` | Format of the data within the source file (`ICU`, `I18NEXT`, `JSX`, or `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Yes |
| `formatMetadata` | Format-specific metadata accepted with the source descriptor; it does not change the existing source record. | `GTJsonFormatMetadata \| FormatMetadata` | Yes |
| `branchId` | Branch containing the previously uploaded source. Uses the default branch when omitted. | `string` | Yes |
| `fileId` | File ID of the source file. | `string` | Yes |
| `versionId` | Version ID of the source file. | `string` | Yes |
| `transformFormat` | Accepted by `FileUpload` and validated locally, but not used by this upload endpoint. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Yes |
| `incomingBranchId` | Accepted by `FileUpload` but not sent by this method. | `string` | Yes |
| `checkedOutBranchId` | Accepted by `FileUpload` but not sent by this method. | `string` | Yes |

Each translation (a `FileUpload`) uses these fields:

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `content` | Raw translated text, or base64-encoded binary content for `LOTTIE`. | `string` | No |
| `fileName` | Required by `FileUpload`; the stored translation uses the source file name. | `string` | No |
| `fileFormat` | Format of the file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No |
| `locale` | Target locale of the translation. | `string` | No |
| `dataFormat` | Format of the translated data (`ICU`, `I18NEXT`, `JSX`, or `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Yes |
| `fileId` | Accepted and sent by the client, but ignored by the endpoint; the translation inherits the source file ID. | `string` | Yes |
| `versionId` | Accepted and sent by the client, but ignored by the endpoint; the translation inherits the source version ID. | `string` | Yes |
| `branchId` | Accepted and sent by the client, but ignored by the endpoint; the translation inherits the source branch. | `string` | Yes |
| `transformFormat` | Accepted by `FileUpload` but not sent by this method. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Yes |
| `formatMetadata` | Accepted by `FileUpload` but not sent by this method. | `GTJsonFormatMetadata \| FormatMetadata` | Yes |
| `incomingBranchId` | Accepted by `FileUpload` but not sent by this method. | `string` | Yes |
| `checkedOutBranchId` | Accepted by `FileUpload` but not sent by this method. | `string` | Yes |

### `options`

**Type** `UploadFilesOptions` · **Required**

Configuration for the upload:

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `sourceLocale` | Source locale for the request. Also updates the project's default locale when it differs. | `string` | No |
| `modelProvider` | Accepted by the shared options type but not sent by this upload method. Set the provider on [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) instead. | `string` | Yes |
| `timeout` | Request timeout in milliseconds. | `number` | Yes |

*Note: `branchId` is not an upload option. It is a per-file field on each file object, not part of `UploadFilesOptions`.*

## Returns [#returns]

**Type** `Promise<UploadFilesResponse>`

Resolves to an `UploadFilesResponse` containing the uploaded file references and a summary:

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // uploaded file references
  count: number; // number of files successfully uploaded
  message: string; // status message from the API
};
```

## Examples [#examples]

```typescript
// Basic usage: upload translations for previously uploaded source files
import { GT } from 'generaltranslation';
import fs from 'fs';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

const files = [
  {
    // This exact source must already have been uploaded.
    source: {
      content: fs.readFileSync('./locales/en/common.json', 'utf8'),
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'es',
      },
      {
        content: fs.readFileSync('./locales/fr/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'fr',
      },
    ],
  },
];

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en',
});

console.log(`Uploaded ${result.count} translation files`);
```

```typescript
// Complete workflow: upload source files, then their translations
import { GT } from 'generaltranslation';
import fs from 'fs';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

// Step 1: Upload source files
const sourceFiles = [
  {
    source: {
      content: fs.readFileSync('./locales/en/messages.json', 'utf8'),
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
];

const { uploadedFiles } = await gt.uploadSourceFiles(sourceFiles, {
  sourceLocale: 'en',
});

// Step 2: Upload existing translations
const translationFiles = [
  {
    source: {
      content: sourceFiles[0].source.content,
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      locale: sourceFiles[0].source.locale,
      fileId: uploadedFiles[0].fileId,
      versionId: uploadedFiles[0].versionId,
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'es',
      },
      {
        content: fs.readFileSync('./locales/de/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'de',
      },
    ],
  },
];

const translationResult = await gt.uploadTranslations(translationFiles, {
  sourceLocale: 'en',
});

console.log(`Uploaded ${translationResult.count} translations`);
```

```typescript
// Batch upload translations for multiple source files
import fs from 'node:fs';
import { GT } from 'generaltranslation';
import type { FileUpload } from 'generaltranslation/types';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

async function uploadAllTranslations(
  sourceFiles: FileUpload[],
  targetLocales: string[]
) {
  const files = sourceFiles.map((source) => ({
    source,
    translations: targetLocales
      .map((locale) => {
        const translationPath = `./locales/${locale}/${source.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: source.fileName,
            fileFormat: source.fileFormat,
            locale,
          };
        } catch {
          // Translation file doesn't exist for this locale
          return null;
        }
      })
      .filter((file): file is FileUpload => file !== null),
  }));

  const result = await gt.uploadTranslations(files, {
    sourceLocale: 'en',
    timeout: 60000,
  });

  return result;
}
```

## Notes [#notes]

- The `source` object in each entry must include content, file name, file format, and locale.
- The source version identified by that object must already exist in the project.
- Each translation in the `translations` array must include content and a target locale.
- This method is useful for migrating existing translations or uploading human-reviewed translations.
- File references include `branchId` for versioning with branch support.

## Sitemap

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