# General Translation Platform: uploadSourceFiles
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Upload source files to a project before queueing translation. API reference for uploadSourceFiles.

Uploads source files to the General Translation platform for translation processing. This is usually the first step in a file translation workflow, before setting up a project or queueing translation jobs.

## Overview [#overview]

Call `uploadSourceFiles` with an array of files and an options object that sets the source locale. It returns the uploaded file references you use in later steps.

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

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

Signature:

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

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

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

- **File encoding.** Text content is automatically base64-encoded for safe transmission. Binary `LOTTIE` content must already be base64-encoded.
- **File references.** The returned file references (including `fileId`, `versionId`, and `branchId`) are required inputs for later operations.
- **Typical workflow.** `uploadSourceFiles` is the entry point of the file pipeline: upload source files, then [`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project) → [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) → [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) → [`downloadFileBatch`](/docs/platform/core/reference/gt-class-methods/translation/download-file-batch).

## Parameters [#parameters]

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

### `files`

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

The source files to upload. Each entry wraps a `FileUpload` under a `source` key:

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `content` | Raw text content, or base64-encoded binary content for `LOTTIE`. | `string` | No |
| `fileName` | Unique file identifier, typically the file path plus name. | `string` | No |
| `fileFormat` | Format of the file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No |
| `transformFormat` | Accepted by the shared `FileUpload` type but not sent by this method. Set the output format on the file reference passed to [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Yes |
| `dataFormat` | Format of the data within the file (`ICU`, `I18NEXT`, `JSX`, or `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Yes |
| `locale` | Locale of the source file content. | `string` | No |
| `branchId` | Branch to upload the file into. Uses the default branch when omitted. | `string` | Yes |
| `incomingBranchId` | Incoming branch used by branch-aware translation tracking. | `string` | Yes |
| `checkedOutBranchId` | Checked-out branch used by branch-aware translation tracking. | `string` | Yes |
| `formatMetadata` | Format-specific metadata stored with the source file. | `GTJsonFormatMetadata \| FormatMetadata` | Yes |
| `versionId` | Version ID, for advanced use cases. | `string` | Yes |
| `fileId` | File ID, for advanced use cases. | `string` | Yes |

### `options`

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

Configuration for the upload:

| Field | Description | Type | Optional |
| --- | --- | --- | --- |
| `sourceLocale` | Source locale for the upload. 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[]; // references for subsequent operations
  count: number; // number of files successfully uploaded
  message: string; // status message from the API
};
```

Each `FileReference` has the shape:

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string; // the current API can omit this for the default branch
  fileName: string;
  fileFormat: FileFormat;
  transformFormat?: FileFormat; // not populated by this upload method
  dataFormat?: DataFormat;
};
```

The library type declares `branchId` as required, but the current API can omit it when it selects the default branch. It also does not populate `transformFormat`; set that field before passing a reference to [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) when you need format conversion.

## Examples [#examples]

```typescript
// Basic usage: upload JSON translation files
import { GT } from 'generaltranslation';
import fs from 'fs';

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

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

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

console.log(`Uploaded ${result.count} files`);
result.uploadedFiles.forEach((file) => {
  console.log(`  ${file.fileName}: ${file.fileId} (branch: ${file.branchId})`);
});
```

```typescript
// With explicit data format specification
const files = [
  {
    source: {
      content: '{"welcome": "Welcome, {name}!"}',
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'ICU' as const, // ICU message format
      locale: 'en',
    },
  },
  {
    source: {
      content: '{"greeting": "Hello {{name}}"}',
      fileName: 'i18next.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'I18NEXT' as const,
      locale: 'en',
    },
  },
];

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

```typescript
// Batch upload with error handling
import { glob } from 'glob';
import path from 'path';

async function uploadAllJsonFiles() {
  try {
    // Find all JSON files
    const jsonPaths = await glob('./locales/en/**/*.json');

    const files = jsonPaths.map((filePath) => ({
      source: {
        content: fs.readFileSync(filePath, 'utf8'),
        fileName: path.relative('./locales/en', filePath),
        fileFormat: 'JSON' as const,
        locale: 'en',
      },
    }));

    console.log(`Uploading ${files.length} files...`);

    const result = await gt.uploadSourceFiles(files, {
      sourceLocale: 'en',
      timeout: 60000, // 60 second timeout for large uploads
    });

    if (result.count !== files.length) {
      console.warn(`Expected ${files.length} files, but only ${result.count} uploaded`);
    }

    return result.uploadedFiles;
  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

## Notes [#notes]

- Text content is automatically base64-encoded for safe transmission. Pass binary `LOTTIE` content as a base64-encoded `.lottie` ZIP file.
- File names should be unique identifiers, typically including the file path.
- The `locale` field in each file should match the `sourceLocale` option.
- Large files or many files may require increased timeout values.
- File references returned from this method are needed for subsequent operations, and include `branchId` for versioning with branch support.
- **Supported formats:** [`FileFormat`](/docs/platform/core/reference/types/file-format).

## Sitemap

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