# General Translation Platform: uploadSourceFiles URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Carica i file sorgente in un progetto prima di mettere in coda la traduzione. API Reference per uploadSourceFiles. Carica i file sorgente nella piattaforma General Translation per l'elaborazione della traduzione. Di solito è il primo passaggio in un workflow di traduzione di file, prima di configurare un progetto o mettere in coda i job di traduzione. ## Panoramica [#overview] Chiama `uploadSourceFiles` con un array di file e un oggetto options che specifica l'impostazione regionale sorgente. Restituisce i riferimenti ai file caricati che userai nei passaggi successivi. ```typescript const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' }); const result = await gt.uploadSourceFiles(files, { sourceLocale: 'en', }); ``` Firma: ```typescript uploadSourceFiles( files: { source: FileUpload }[], options: UploadFilesOptions ): Promise ``` *Nota: `uploadSourceFiles` richiede una `apiKey` (o `devApiKey`) e un `projectId` nell'istanza GT.* ## Come funziona [#how-it-works] * **Codifica dei file.** Il contenuto testuale viene codificato automaticamente in base64 per una trasmissione sicura. Il contenuto binario `LOTTIE` deve essere già codificato in base64. * **Riferimenti ai file.** I riferimenti ai file restituiti (inclusi `fileId`, `versionId` e `branchId`) sono input necessari per le operazioni successive. * **Workflow tipico.** `uploadSourceFiles` è il punto di ingresso della pipeline dei file: carica i file sorgente, quindi [`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). ## Parametri [#parameters] | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | --------------------- | --------------------------------------------- | -------------------------- | ----------- | ----------- | | [`files`](#files) | Array di file sorgente da caricare. | `{ source: FileUpload }[]` | No | — | | [`options`](#options) | Opzioni di configurazione per il caricamento. | `UploadFilesOptions` | No | — | ### `files` **Tipo** `{ source: FileUpload }[]` · **Obbligatorio** I file sorgente da caricare. Ogni entry contiene un `FileUpload` nella chiave `source`: | Campo | Descrizione | Tipo | Facoltativo | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- | | `content` | Contenuto di testo non elaborato o contenuto binario codificato in Base64 per `LOTTIE`. | `string` | No | | `fileName` | Identificatore univoco del file, in genere il percorso del file più il nome. | `string` | No | | `fileFormat` | Formato del file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No | | `transformFormat` | Accettato dal tipo condiviso `FileUpload` ma non inviato da questo metodo. Imposta il formato di output sul riferimento al file passato a [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Sì | | `dataFormat` | Formato dei dati all'interno del file (`ICU`, `I18NEXT`, `JSX` o `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Sì | | `locale` | Impostazione regionale del contenuto del file sorgente. | `string` | No | | `branchId` | Branch in cui caricare il file. Se omesso, viene usato il branch predefinito. | `string` | Sì | | `incomingBranchId` | Branch in ingresso usato dal tracciamento delle traduzioni basato sui branch. | `string` | Sì | | `checkedOutBranchId` | Branch di cui è stato effettuato il checkout, usato dal tracciamento delle traduzioni basato sui branch. | `string` | Sì | | `formatMetadata` | Metadati specifici del formato memorizzati insieme al file sorgente. | `GTJsonFormatMetadata \| FormatMetadata` | Sì | | `versionId` | ID versione, per casi d'uso avanzati. | `string` | Sì | | `fileId` | ID file, per casi d'uso avanzati. | `string` | Sì | ### `options` **Tipo** `UploadFilesOptions` · **Obbligatorio** Configurazione per l'upload: | Campo | Descrizione | Tipo | Facoltativo | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- | | `sourceLocale` | Impostazione regionale sorgente per l'upload. Aggiorna anche l'impostazione regionale predefinita del progetto quando differisce. | `string` | No | | `modelProvider` | Accettato dal tipo di opzioni condiviso, ma non inviato da questo metodo di upload. Imposta invece il provider su [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | `string` | Sì | | `timeout` | Timeout della richiesta in millisecondi. | `number` | Sì | *Nota: `branchId` non è un'opzione di upload. È un campo per file in ciascun oggetto file, non fa parte di `UploadFilesOptions`.* ## Valore restituito [#returns] **Tipo** `Promise` Restituisce un `UploadFilesResponse` contenente i riferimenti ai file caricati e un riepilogo: ```typescript type UploadFilesResponse = { uploadedFiles: FileReference[]; // riferimenti per le operazioni successive count: number; // numero di file caricati con successo message: string; // messaggio di stato dall'API }; ``` Ogni `FileReference` ha la seguente forma: ```typescript type FileReference = { fileId: string; versionId: string; branchId: string; // l'API attuale può omettere questo campo per il branch predefinito fileName: string; fileFormat: FileFormat; transformFormat?: FileFormat; // non popolato da questo metodo di upload dataFormat?: DataFormat; }; ``` Il tipo della library dichiara `branchId` come obbligatorio, ma l'API attuale può ometterlo quando seleziona il branch predefinito. Inoltre non popola `transformFormat`: imposta questo campo prima di passare un riferimento a [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) quando serve una conversione di formato. ## Esempi [#examples] ```typescript // Utilizzo di base: upload di file di traduzione 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 // Con specifica esplicita del formato dati const files = [ { source: { content: '{"welcome": "Welcome, {name}!"}', fileName: 'messages.json', fileFormat: 'JSON' as const, dataFormat: 'ICU' as const, // formato 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', timeout: 30000, }); ``` ```typescript // Caricamento in batch con gestione degli errori import { glob } from 'glob'; import path from 'path'; async function uploadAllJsonFiles() { try { // Trova tutti i file 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, // timeout di 60 secondi per caricamenti di grandi dimensioni }); 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(); ``` ## Note [#notes] * Il contenuto testuale viene codificato automaticamente in Base64 per garantire una trasmissione sicura. Trasmetti il contenuto binario `LOTTIE` come file ZIP `.lottie` codificato in Base64. * I nomi dei file devono essere identificatori univoci e in genere includono il percorso del file. * Il campo `locale` in ogni file deve corrispondere all'opzione `sourceLocale`. * File di grandi dimensioni o un numero elevato di file potrebbero richiedere valori di timeout più alti. * I riferimenti ai file restituiti da questo metodo sono necessari per le operazioni successive e includono `branchId` per il controllo delle versioni con supporto dei branch. * **Formati supportati:** [`FileFormat`](/docs/platform/core/reference/types/file-format). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.