# General Translation Platform: uploadSourceFiles
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx
---

title: uploadSourceFiles
description: Загрузите исходные файлы в Project перед постановкой задач перевода в очередь. Справочник по API для uploadSourceFiles.

---

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

## Обзор [#overview]

Вызовите `uploadSourceFiles`, передав массив файлов и объект параметров, в котором задаётся исходная локаль. Метод возвращает ссылки на загруженные файлы, которые используются на следующих шагах.

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

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

Сигнатура:

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

*Примечание: для `uploadSourceFiles` в экземпляре GT должны быть указаны `apiKey` (или `devApiKey`) и `projectId`.*

## Как это работает [#how-it-works]

* **Кодировка файла.** Содержимое файла автоматически кодируется в Base64 для безопасной передачи.
* **Ссылки на файлы.** Возвращаемые ссылки на файлы (включая `fileId`, `versionId` и `branchId`) обязательны для последующих операций.
* **Типичный workflow.** `uploadSourceFiles` — точка входа в файловый pipeline: загрузите исходные файлы, затем [`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]

| Параметр              | Описание                               | Тип                        | Необязательный | По умолчанию |
| --------------------- | -------------------------------------- | -------------------------- | -------------- | ------------ |
| [`files`](#files)     | Массив исходных файлов для загрузки.   | `{ source: FileUpload }[]` | Нет            | —            |
| [`options`](#options) | Параметры конфигурации загрузки.       | `UploadFilesOptions`       | Нет            | —            |

### `files` [#files]

**Type** `{ source: FileUpload }[]` · **Обязательно**

Исходные файлы для загрузки. Каждый элемент содержит объект `FileUpload` в ключе `source`:

| Field             | Description                                                                                                                    | Type                                                            | Optional |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------- |
| `content`         | Сырое содержимое файла в виде строки.                                                                                          | `string`                                                        | Нет      |
| `fileName`        | Уникальный идентификатор файла, обычно путь и имя файла.                                                                       | `string`                                                        | Нет      |
| `fileFormat`      | Формат файла. Один из `GTJSON`, `JSON`, `PO`, `POT`, `YAML`, `MDX`, `MD`, `TS`, `JS`, `HTML`, `TXT` или `TWILIO_CONTENT_JSON`. | `FileFormat`                                                    | Нет      |
| `transformFormat` | Выходной формат для сгенерированных переводов.                                                                                 | `FileFormat`                                                    | Да       |
| `dataFormat`      | Формат данных внутри файла (ICU, I18NEXT, JSX).                                                                                | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Да       |
| `locale`          | Локаль содержимого исходного файла.                                                                                            | `string`                                                        | Нет      |
| `branchId`        | Ветвь, в которую нужно загрузить файл. Если не указано, используется ветвь по умолчанию.                                       | `string`                                                        | Да       |
| `versionId`       | ID версии для продвинутых сценариев использования.                                                                             | `string`                                                        | Да       |
| `fileId`          | ID файла для продвинутых сценариев использования.                                                                              | `string`                                                        | Да       |

### `options` [#options]

**Тип** `UploadFilesOptions` · **Обязательно**

Параметры загрузки:

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

*Примечание: `branchId` не является параметром загрузки. Это поле каждого объекта файла, а не часть `UploadFilesOptions`.*

## Возвращает [#returns]

**Тип** `Promise<UploadFilesResponse>`

Результатом будет `UploadFilesResponse`, содержащий ссылки на загруженные файлы и сводку:

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // ссылки для последующих операций
  count: number; // количество успешно загруженных файлов
  message: string; // сообщение о статусе от API
};
```

Каждый `FileReference` имеет следующую структуру:

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  transformFormat?: FileFormat; // формат вывода, запрошенный для сгенерированных переводов
  dataFormat?: DataFormat;
};
```

## Примеры [#examples]

```typescript
// Базовое использование: загрузка файлов перевода JSON
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
// С явным указанием формата данных
const files = [
  {
    source: {
      content: '{"welcome": "Welcome, {name}!"}',
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'ICU' as const, // формат сообщений ICU
      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
// Пакетная загрузка с обработкой ошибок
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();
```

## Примечания [#notes]

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