# General Translation Platform: uploadSourceFiles URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx --- title: uploadSourceFiles description: Carica i file sorgente in un Project 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 Project 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 dei file viene codificato automaticamente in Base64 per una trasmissione sicura. * **Riferimenti ai file.** I riferimenti ai file restituiti (inclusi `fileId`, `versionId` e `branchId`) sono input necessari per le operazioni successive. * **Flusso di lavoro 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` [#files] **Tipo** `{ source: FileUpload }[]` · **Obbligatorio** I file sorgente da caricare. Ogni entry contiene un `FileUpload` nella chiave `source`: | Campo | Descrizione | Tipo | Facoltativo | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- | | `content` | Contenuto raw del file come stringa. | `string` | No | | `fileName` | Identificatore univoco del file, in genere il percorso del file più il nome. | `string` | No | | `fileFormat` | Formato del file. Uno tra `GTJSON`, `JSON`, `PO`, `POT`, `YAML`, `MDX`, `MD`, `TS`, `JS`, `HTML`, `TXT` o `TWILIO_CONTENT_JSON`. | `FileFormat` | No | | `transformFormat` | Formato di output richiesto per le traduzioni generate. | `FileFormat` | Sì | | `dataFormat` | Formato dei dati all'interno del file (ICU, I18NEXT, JSX). | [`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ì | | `versionId` | ID versione, per casi d'uso avanzati. | `string` | Sì | | `fileId` | ID file, per casi d'uso avanzati. | `string` | Sì | ### `options` [#options] **Tipo** `UploadFilesOptions` · **Obbligatorio** Configurazione per l'upload: | Campo | Descrizione | Tipo | Facoltativo | | --------------- | ---------------------------------------------------------------- | -------- | ----------- | | `sourceLocale` | L'impostazione regionale sorgente per tutti i file caricati. | `string` | No | | `modelProvider` | Preferenza del provider del modello AI. | `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; fileName: string; fileFormat: FileFormat; transformFormat?: FileFormat; // formato di output richiesto per le traduzioni generate dataFormat?: DataFormat; }; ``` ## 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', modelProvider: 'gpt-4', 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 del file viene codificato automaticamente in Base64 per garantire una trasmissione sicura. * 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. * I formati di file supportati sono `GTJSON`, `JSON`, `PO`, `POT`, `YAML`, `MDX`, `MD`, `TS`, `JS`, `HTML`, `TXT` e `TWILIO_CONTENT_JSON` — consulta il tipo `FileFormat` per l'elenco completo.