# generaltranslation: General Translation Core SDK: uploadSourceFiles
URL: https://generaltranslation.com/en-US/docs/core/class/methods/translation/upload-source-files.mdx
---
title: uploadSourceFiles
description: API reference for the uploadSourceFiles method to upload source files for translation
---

## Overview

The `uploadSourceFiles` method uploads source files to the General Translation platform for translation processing.
This is typically the first step in a translation workflow before setting up projects or enqueueing translation jobs.

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

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

<Mermaid
  chart="
graph TD;
A[uploadSourceFiles];
B[setupProject];
C[enqueueFiles];
E[queryFileData];
F[downloadFileBatch];
A --> B;
B --> C;
C --> E;
E --> F;
"
/>




## Reference

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `files` | `{ source: FileUpload }[]` | Array of source files to upload |
| `options` | `UploadFilesOptions` | Configuration options for the upload |

#### FileUpload Structure

| Name | Type | Description |
|------|------|-------------|
| `content` | `string` | Raw file content as a string |
| `fileName` | `string` | Unique file identifier (typically file path + name) |
| `fileFormat` | `FileFormat` | Format of the file (JSON, MDX, MD, XML, etc.) |
| `dataFormat?` | `DataFormat` | Optional format of data within the file (ICU, I18NEXT, JSX) |
| `locale` | `string` | Locale of the source file content |
| `versionId?` | `string` | Optional version ID for advanced use cases |
| `fileId?` | `string` | Optional file ID for advanced use cases |

#### UploadFilesOptions

| Name | Type | Description |
|------|------|-------------|
| `sourceLocale` | `string` | The source locale for all uploaded files |
| `branchId?` | `string` | Optional branch ID to upload to |
| `modelProvider?` | `string` | Optional AI model provider preference |
| `timeout?` | `number` | Request timeout in milliseconds |

### Returns

`Promise<UploadFilesResponse>` - Contains upload results and file references.

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}
```

| Property | Type | Description |
|----------|------|-------------|
| `uploadedFiles` | `FileReference[]` | Array of uploaded file references for subsequent operations |
| `count` | `number` | Number of files successfully uploaded |
| `message` | `string` | Status message from the API |

#### FileReference Structure

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  dataFormat?: DataFormat;
  locale?: string;
}
```

---

## Examples

### Basic usage

Upload JSON translation files:

```typescript copy
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})`);
});
```

### With data format specification

Upload files with explicit data format specification:

```typescript copy
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',
  modelProvider: 'gpt-4',
  timeout: 30000
});
```

### Batch upload with error handling

Upload multiple files with comprehensive error handling:

```typescript copy
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

* File content is automatically Base64 encoded for safe transmission
* 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
* File references include `branchId` for proper versioning with branching support
* Supported file formats include JSON, MD, MDX, XML, and others - see `FileFormat` type for complete list

## Next steps

* See [`setupProject`](/docs/core/class/methods/translation/setup-project) to prepare uploaded files for translation
* See [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files) to start translation jobs
* See [`uploadTranslations`](/docs/core/class/methods/translation/upload-translations) to upload pre-existing translations
* See `FileUpload` for detailed file structure