# General Translation Platform: uploadSourceFiles URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Загрузите исходные файлы в проект перед постановкой задач перевода в очередь. Справочник по API для uploadSourceFiles. Загружает исходные файлы на платформу General Translation для обработки перевода. Обычно это первый шаг в workflow перевода файлов — перед настройкой проекта или постановкой задач перевода в очередь. ## Обзор [#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 ``` *Примечание: для `uploadSourceFiles` в экземпляре GT должны быть указаны `apiKey` (или `devApiKey`) и `projectId`.* ## Как это работает [#how-it-works] * **Кодировка файла.** Текстовое содержимое автоматически кодируется в кодировке Base64 для безопасной передачи. Двоичное содержимое `LOTTIE` уже должно быть в кодировке 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` **Type** `{ source: FileUpload }[]` · **Обязательно** Исходные файлы для загрузки. Каждый элемент содержит объект `FileUpload` в ключе `source`: | поле | Description | Type | Optional | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | | `content` | Необработанное текстовое содержимое или двоичное содержимое в кодировке Base64 для `LOTTIE`. | `string` | Нет | | `fileName` | Уникальный идентификатор файла, обычно путь и имя файла. | `string` | Нет | | `fileFormat` | Формат файла. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Нет | | `transformFormat` | Принимается общим типом `FileUpload`, но не отправляется этим методом. Задайте формат вывода в ссылке на файл, передаваемой в [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Да | | `dataFormat` | Формат данных внутри файла (`ICU`, `I18NEXT`, `JSX` или `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Да | | `locale` | Локаль содержимого исходного файла. | `string` | Нет | | `branchId` | Ветвь, в которую нужно загрузить файл. Если не указано, используется ветвь по умолчанию. | `string` | Да | | `incomingBranchId` | Входящая ветвь, используемая при отслеживании переводов с учётом ветвей. | `string` | Да | | `checkedOutBranchId` | Текущая выбранная ветвь, используемая при отслеживании переводов с учётом ветвей. | `string` | Да | | `formatMetadata` | Метаданные, специфичные для формата, сохраняемые вместе с исходным файлом. | `GTJsonFormatMetadata \| FormatMetadata` | Да | | `versionId` | ID версии для продвинутых сценариев использования. | `string` | Да | | `fileId` | ID файла для продвинутых сценариев использования. | `string` | Да | ### `options` **Тип** `UploadFilesOptions` · **Обязательно** Параметры загрузки: | Поле | Описание | Тип | Необязательное | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | | `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 }; ``` Каждый `FileReference` имеет следующую структуру: ```typescript type FileReference = { fileId: string; versionId: string; branchId: string; // текущий API может не возвращать это поле для ветки по умолчанию fileName: string; fileFormat: FileFormat; transformFormat?: FileFormat; // этот метод загрузки не заполняет данное поле dataFormat?: DataFormat; }; ``` Тип из библиотеки объявляет `branchId` обязательным, однако текущий API может опускать его, когда выбирается ветка по умолчанию. Кроме того, он не заполняет `transformFormat`; задайте это поле перед передачей ссылки в [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files), если требуется преобразование формата. ## Примеры [#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', 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 для безопасной передачи. Передавайте двоичное содержимое `LOTTIE` как ZIP-файл `.lottie` в кодировке Base64. * Имена файлов должны быть уникальными идентификаторами и обычно включать путь к файлу. * Поле `locale` в каждом файле должно соответствовать параметру `sourceLocale`. * Для больших файлов или большого их количества может потребоваться увеличить значение тайм-аута. * Ссылки на файлы, возвращаемые этим методом, нужны для последующих операций и содержат `branchId` для версионирования при поддержке веток. * **Поддерживаемые форматы:** [`FileFormat`](/docs/platform/core/reference/types/file-format). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.