# generaltranslation: General Translation Core SDK: uploadSourceFiles
URL: https://generaltranslation.com/ru/docs/core/class/methods/translation/upload-source-files.mdx
---
title: uploadSourceFiles
description: Справка по API для метода uploadSourceFiles, который загружает исходные файлы для перевода
---

## Обзор

Метод `uploadSourceFiles` загружает исходные файлы на платформу General Translation для дальнейшей обработки перевода.
Обычно это первый шаг в процессе перевода — перед настройкой проектов и постановкой заданий на перевод в очередь.

```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;
"
/>


## Справка

### Параметры

| Имя       | Тип                        | Описание                            |
| --------- | -------------------------- | ----------------------------------- |
| `files`   | `{ source: FileUpload }[]` | Массив исходных файлов для загрузки |
| `options` | `UploadFilesOptions`       | Параметры загрузки                  |

#### Структура FileUpload

| Имя           | Тип          | Описание                                                                    |
| ------------- | ------------ | --------------------------------------------------------------------------- |
| `content`     | `string`     | Исходное содержимое файла в виде строки                                     |
| `fileName`    | `string`     | Уникальный идентификатор файла (обычно путь к файлу и имя)                  |
| `fileFormat`  | `FileFormat` | Формат файла (JSON, MDX, MD, XML и т. д.)                                   |
| `dataFormat?` | `DataFormat` | Необязательный формат данных внутри файла (ICU, I18NEXT, JSX)               |
| `locale`      | `string`     | Локаль содержимого исходного файла                                          |
| `versionId?`  | `string`     | Необязательный идентификатор версии для продвинутых сценариев использования |
| `fileId?`     | `string`     | Необязательный идентификатор файла для продвинутых сценариев использования  |

#### UploadFilesOptions

| Имя              | Тип      | Описание                                                       |
| ---------------- | -------- | -------------------------------------------------------------- |
| `sourceLocale`   | `string` | Исходная локаль для всех загружаемых файлов                    |
| `branchId?`      | `string` | Необязательный идентификатор ветки для загрузки                |
| `modelProvider?` | `string` | Необязательное указание предпочтительного провайдера модели ИИ |
| `timeout?`       | `number` | Тайм-аут запроса в миллисекундах                               |

### Возвращает

`Promise<UploadFilesResponse>` — содержит результаты загрузки и ссылки на файлы.

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

| Свойство        | Тип               | Описание                                                    |
| --------------- | ----------------- | ----------------------------------------------------------- |
| `uploadedFiles` | `FileReference[]` | Массив ссылок на загруженные файлы для последующих операций |
| `count`         | `number`          | Количество успешно загруженных файлов                       |
| `message`       | `string`          | Сообщение о состоянии от API                                |


#### Структура FileReference

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

***


## Примеры

### Базовое использование

Загрузите JSON-файлы перевода:

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


### С указанием формата данных

Загрузите файлы, явно указав формат данных:

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


### Пакетная загрузка с обработкой ошибок

Загрузите несколько файлов с полной обработкой ошибок:

```typescript copy
import { glob } from 'glob';
import path from 'path';

async function uploadAllJsonFiles() {
  try {
    // Найти все JSON-файлы
    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 секунд для больших загрузок
    });

    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();
```

***


## Примечания

* Содержимое файлов автоматически кодируется в Base64 для безопасной передачи
* Имена файлов должны быть уникальными идентификаторами и обычно включать путь к файлу
* Поле `locale` в каждом файле должно соответствовать параметру `sourceLocale`
* Для больших файлов или большого количества файлов может потребоваться увеличить тайм-аут
* Ссылки на файлы, возвращаемые этим методом, нужны для последующих операций
* Ссылки на файлы включают `branchId` для корректного управления версиями при использовании ветвления
* Поддерживаемые форматы файлов включают JSON, MD, MDX, XML и другие — полный список см. в типе `FileFormat`

## Следующие шаги

* См. [`setupProject`](/docs/core/class/methods/translation/setup-project), чтобы подготовить загруженные файлы к переводу
* См. [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files), чтобы запустить задачи перевода
* См. [`uploadTranslations`](/docs/core/class/methods/translation/upload-translations), чтобы загрузить существующие переводы
* См. `FileUpload` для подробной информации о структуре файла