# General Translation Platform: uploadTranslations URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/translation/upload-translations.mdx Docs index: https://generaltranslation.com/llms.txt Description: Загрузите существующие переведённые файлы, соответствующие исходным файлам. Справочник по API для uploadTranslations. Загружает существующие переводы для исходных файлов, которые уже есть в проекте. Используйте эту функцию при миграции переводов или загрузке переводов, проверенных человеком, вместо того чтобы генерировать их через сервис перевода. ## Обзор [#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 ``` *Примечание: для `uploadTranslations` в экземпляре GT должны быть указаны `apiKey` (или `devApiKey`) и `projectId`.* ## Как это работает [#how-it-works] * **Существующий исходный файл.** Сначала загрузите исходный файл. Объект `source` по-прежнему представляет собой полный `FileUpload`, включая содержимое и локаль; API деривирует недостающие идентификаторы из этих данных и использует полученные идентификаторы для поиска существующей исходной версии. * **Переводы.** Каждый элемент массива `translations` должен содержать содержимое и целевую локаль. * **Кодирование файлов.** Текстовое содержимое автоматически кодируется в Base64. Двоичные переводы `LOTTIE` должны уже содержать ZIP-данные `.lottie` в кодировке Base64. * **Управление версиями.** Возвращаемые ссылки на файлы включают `branchId` для версионирования с поддержкой веток. ## Параметры [#parameters] | Параметр | Описание | Тип | Необязательно | По умолчанию | | --------------------- | -------------------------------------- | ------------------------------------------------------ | ------------- | ------------ | | [`files`](#files) | Массив исходных файлов и их переводов. | `{ source: FileUpload; translations: FileUpload[] }[]` | Нет | — | | [`options`](#options) | Параметры конфигурации загрузки. | `UploadFilesOptions` | Нет | — | ### `files` **Type** `{ source: FileUpload; translations: FileUpload[] }[]` · **Обязательно** Каждая запись сопоставляет полный исходный файл с его переведёнными файлами: ```typescript { source: FileUpload; // исходный контент и метаданные translations: FileUpload[]; // переведённые файлы с содержимым } ``` Значение `source` использует следующие поля `FileUpload`: | поле | Description | Type | Optional | | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | | `content` | Исходный текст в необработанном виде либо двоичное содержимое в кодировке Base64 для `LOTTIE`. | `string` | Нет | | `fileName` | Имя файла, совпадающее с ранее загруженным исходным файлом. | `string` | Нет | | `fileFormat` | Формат файла. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Нет | | `locale` | Локаль исходного содержимого. | `string` | Нет | | `dataFormat` | Формат данных внутри исходного файла (`ICU`, `I18NEXT`, `JSX` или `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Да | | `formatMetadata` | Метаданные конкретного формата, принимаемые вместе с дескриптором источника; существующую запись источника они не изменяют. | `GTJsonFormatMetadata \| FormatMetadata` | Да | | `branchId` | Ветка, содержащая ранее загруженный источник. Если не указана, используется ветка по умолчанию. | `string` | Да | | `fileId` | ID исходного файла. | `string` | Да | | `versionId` | ID версии исходного файла. | `string` | Да | | `transformFormat` | Принимается `FileUpload` и проверяется локально, но данным эндпоинтом загрузки не используется. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Да | | `incomingBranchId` | Принимается `FileUpload`, но данным методом не отправляется. | `string` | Да | | `checkedOutBranchId` | Принимается `FileUpload`, но данным методом не отправляется. | `string` | Да | Каждый перевод (объект `FileUpload`) использует следующие поля: | поле | Description | Type | Optional | | -------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | | `content` | Переведённый текст в необработанном виде либо двоичное содержимое в кодировке Base64 для `LOTTIE`. | `string` | Нет | | `fileName` | Обязательно для `FileUpload`; сохранённый перевод использует имя исходного файла. | `string` | Нет | | `fileFormat` | Формат файла. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Нет | | `locale` | Целевая локаль перевода. | `string` | Нет | | `dataFormat` | Формат переведённых данных (`ICU`, `I18NEXT`, `JSX` или `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Да | | `fileId` | Принимается и отправляется клиентом, но игнорируется эндпоинтом; перевод наследует ID исходного файла. | `string` | Да | | `versionId` | Принимается и отправляется клиентом, но игнорируется эндпоинтом; перевод наследует ID версии источника. | `string` | Да | | `branchId` | Принимается и отправляется клиентом, но игнорируется эндпоинтом; перевод наследует ветку источника. | `string` | Да | | `transformFormat` | Принимается `FileUpload`, но данным методом не отправляется. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Да | | `formatMetadata` | Принимается `FileUpload`, но данным методом не отправляется. | `GTJsonFormatMetadata \| FormatMetadata` | Да | | `incomingBranchId` | Принимается `FileUpload`, но данным методом не отправляется. | `string` | Да | | `checkedOutBranchId` | Принимается `FileUpload`, но данным методом не отправляется. | `string` | Да | ### `options` **Type** `UploadFilesOptions` · **Обязательно** Параметры загрузки: | Поле | Описание | Type | Необязательно | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | | `sourceLocale` | Исходная локаль для запроса. Также обновляет локаль проекта по умолчанию, если она отличается. | `string` | Нет | | `modelProvider` | Принимается общим типом параметров, но этим методом загрузки не отправляется. Указывайте провайдера в [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | `string` | Да | | `timeout` | Тайм-аут запроса в миллисекундах. | `number` | Да | *Примечание: `branchId` не является параметром загрузки. Это поле задаётся отдельно для каждого объекта файла и не входит в `UploadFilesOptions`.* ## Возвращает [#returns] **Тип** `Promise` Результатом выполнения будет `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: { content: fs.readFileSync('./locales/en/common.json', 'utf8'), fileName: 'common.json', fileFormat: 'JSON' as const, locale: 'en', }, 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: { content: sourceFiles[0].source.content, fileName: uploadedFiles[0].fileName, fileFormat: uploadedFiles[0].fileFormat, locale: sourceFiles[0].source.locale, 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 fs from 'node:fs'; import { GT } from 'generaltranslation'; import type { FileUpload } from 'generaltranslation/types'; const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id', }); async function uploadAllTranslations( sourceFiles: FileUpload[], targetLocales: string[] ) { const files = sourceFiles.map((source) => ({ source, translations: targetLocales .map((locale) => { const translationPath = `./locales/${locale}/${source.fileName}`; try { return { content: fs.readFileSync(translationPath, 'utf8'), fileName: source.fileName, fileFormat: source.fileFormat, locale, }; } catch { // Файл перевода для данной локали не существует return null; } }) .filter((file): file is FileUpload => file !== null), })); const result = await gt.uploadTranslations(files, { sourceLocale: 'en', timeout: 60000, }); return result; } ``` ## Примечания [#notes] * Объект `source` в каждой записи должен включать содержимое, имя файла, формат файла и локаль. * Исходная версия, определяемая этим объектом, уже должна существовать в проекте. * Каждый перевод в массиве `translations` должен включать содержимое и целевую локаль. * Этот метод полезен при миграции существующих переводов или загрузке переводов, проверенных человеком. * Ссылки на файлы включают `branchId` для версионирования с поддержкой веток. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.