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

title: uploadTranslations
description: Загрузите существующие файлы перевода, соответствующие исходным файлам. Справочник по API для uploadTranslations.

---

Загружает файлы перевода, соответствующие ранее загруженным исходным файлам. Используйте эту функцию с General Translation, если у вас уже есть переводы — например, при миграции существующих переводов или загрузке переводов, проверенных человеком, — вместо того чтобы генерировать их через сервис перевода.

## Обзор [#overview]

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

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

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

Сигнатура:

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

*Примечание: для `uploadTranslations` в экземпляре GT должны быть указаны `apiKey` (или `devApiKey`) и `projectId`. Сначала необходимо загрузить соответствующие исходные файлы с помощью [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files).*

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

* **Ссылка `source`.** Объект `source` в каждой записи — это ссылка на уже загруженный исходный файл; его содержимое не нужно.
* **Переводы.** Каждый элемент массива `translations` должен содержать контент и целевую локаль.
* **Управление версиями.** Возвращаемые ссылки на файлы включают `branchId` для версионирования с поддержкой веток.

## Параметры [#parameters]

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

### `files` [#files]

**Тип** `{ source: FileUpload; translations: FileUpload[] }[]` · **Обязательно**

Каждая запись связывает ссылку на исходный файл с соответствующими переведёнными файлами:

```typescript
{
  source: FileUpload; // ссылка на существующий исходный файл (содержимое не требуется)
  translations: FileUpload[]; // переведённые файлы с содержимым
}
```

Ссылка `source` (объект `FileUpload`) использует следующие поля:

| Поле         | Описание                                                                                                                        | Тип          | Необязательно |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
| `fileName`   | Имя файла, соответствующее ранее загруженному исходному файлу.                                                                  | `string`     | Нет           |
| `fileFormat` | Формат файла. Один из: `GTJSON`, `JSON`, `PO`, `POT`, `YAML`, `MDX`, `MD`, `TS`, `JS`, `HTML`, `TXT` или `TWILIO_CONTENT_JSON`. | `FileFormat` | Нет           |
| `fileId`     | ID исходного файла.                                                                                                             | `string`     | Да            |
| `versionId`  | ID версии исходного файла.                                                                                                      | `string`     | Да            |

Для каждого перевода (объект `FileUpload`) используются следующие поля:

| Поле         | Описание                                                                                                                        | Тип          | Необязательно |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
| `content`    | Необработанное содержимое переведённого файла в виде строки.                                                                    | `string`     | Нет           |
| `fileName`   | Имя файла перевода.                                                                                                             | `string`     | Нет           |
| `fileFormat` | Формат файла. Один из: `GTJSON`, `JSON`, `PO`, `POT`, `YAML`, `MDX`, `MD`, `TS`, `JS`, `HTML`, `TXT` или `TWILIO_CONTENT_JSON`. | `FileFormat` | Нет           |
| `locale`     | Целевая локаль перевода.                                                                                                        | `string`     | Нет           |
| `fileId`     | ID файла.                                                                                                                       | `string`     | Да            |
| `versionId`  | ID версии.                                                                                                                      | `string`     | Да            |

### `options` [#options]

**Type** `UploadFilesOptions` · **Обязательно**

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

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

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

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

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

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

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

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

```typescript
// Базовое использование: загрузка переводов для ранее загруженных исходных файлов
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Предполагается, что исходный файл был загружен ранее
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id',
    },
    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
// Полный процесс: загрузка исходных файлов, затем их переводов
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Шаг 1: Загрузка исходных файлов
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',
});

// Шаг 2: Загрузка существующих переводов
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      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
// Пакетная загрузка переводов для нескольких исходных файлов
import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map((sourceRef) => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId,
    },
    translations: targetLocales
      .map((locale) => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale,
          };
        } catch {
          // Файл перевода для данной локали не существует
          return null;
        }
      })
      .filter(Boolean),
  }));

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

  return result;
}
```

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

* Сначала нужно загрузить исходные файлы с помощью [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files).
* Объект `source` в каждой записи ссылается на существующий исходный файл — само содержимое там не нужно.
* Каждый перевод в массиве `translations` должен включать содержимое и целевую локаль.
* Этот метод полезен при миграции существующих переводов или загрузке переводов, проверенных вручную.
* Ссылки на файлы включают `branchId` для версионирования с поддержкой веток.