# generaltranslation: General Translation Core SDK: uploadSourceFiles
URL: https://generaltranslation.com/it/docs/core/class/methods/translation/upload-source-files.mdx
---
title: uploadSourceFiles
description: Documentazione di riferimento API per il metodo uploadSourceFiles, che esegue l'upload dei file sorgente per la traduzione
---

## Panoramica

Il metodo `uploadSourceFiles` esegue l'upload dei file sorgente sulla piattaforma General Translation per l'elaborazione delle traduzioni.
In genere, questo è il primo passaggio di un flusso di lavoro di traduzione, prima di configurare i progetti o mettere in coda i processi di traduzione.

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

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

<Mermaid
  chart="
graph TD;
A[uploadSourceFiles];
B[setupProject];
C[enqueueFiles];
E[queryFileData];
F[downloadFileBatch];
A --> B;
B --> C;
C --> E;
E --> F;
"
/>


## Riferimento

### Parametri

| Nome      | Tipo                       | Descrizione                                |
| --------- | -------------------------- | ------------------------------------------ |
| `files`   | `{ source: FileUpload }[]` | Array di file sorgente da uploadare        |
| `options` | `UploadFilesOptions`       | Opzioni di configurazione per l&#39;upload |

#### Struttura di FileUpload

| Nome          | Tipo         | Descrizione                                                               |
| ------------- | ------------ | ------------------------------------------------------------------------- |
| `content`     | `string`     | Contenuto grezzo del file come stringa                                    |
| `fileName`    | `string`     | Identificatore univoco del file (in genere percorso + nome file)          |
| `fileFormat`  | `FileFormat` | Formato del file (JSON, MDX, MD, XML, ecc.)                               |
| `dataFormat?` | `DataFormat` | Formato facoltativo dei dati all&#39;interno del file (ICU, I18NEXT, JSX) |
| `locale`      | `string`     | Impostazione regionale del contenuto del file sorgente                    |
| `versionId?`  | `string`     | ID versione facoltativo per casi d&#39;uso avanzati                       |
| `fileId?`     | `string`     | ID file facoltativo per casi d&#39;uso avanzati                           |

#### UploadFilesOptions

| Nome             | Tipo     | Descrizione                                                       |
| ---------------- | -------- | ----------------------------------------------------------------- |
| `sourceLocale`   | `string` | L&#39;impostazione regionale di origine per tutti i file caricati |
| `branchId?`      | `string` | ID del branch opzionale in cui eseguire l&#39;upload              |
| `modelProvider?` | `string` | Preferenza facoltativa per il provider del modello di IA          |
| `timeout?`       | `number` | Timeout della richiesta in millisecondi                           |

### Restituisce

`Promise<UploadFilesResponse>` - Contiene i risultati di upload e i riferimenti ai file.

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}
```

| Proprietà       | Tipo              | Descrizione                                                        |
| --------------- | ----------------- | ------------------------------------------------------------------ |
| `uploadedFiles` | `FileReference[]` | Array di riferimenti ai file caricati per le operazioni successive |
| `count`         | `number`          | Numero di file caricati con successo                               |
| `message`       | `string`          | Messaggio di stato dell&#39;API                                    |


#### Struttura FileReference

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  dataFormat?: DataFormat;
  locale?: string;
}
```

***


## Esempi

### Utilizzo di base

Esegui l'upload dei file di traduzione JSON:

```typescript copy
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})`);
});
```


### Con specifica esplicita del formato dei dati

Esegui l'upload dei file specificando esplicitamente il formato dei dati:

```typescript copy
const files = [
  {
    source: {
      content: '{"welcome": "Welcome, {name}!"}',
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'ICU' as const, // formato dei messaggi 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',
  modelProvider: 'gpt-4',
  timeout: 30000
});
```


### Upload in batch con gestione degli errori

Esegui l'upload di più file con gestione completa degli errori:

```typescript copy
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(`Upload di ${files.length} file in corso...`);

    const result = await gt.uploadSourceFiles(files, {
      sourceLocale: 'en',
      timeout: 60000 // timeout di 60 secondi per upload di grandi dimensioni
    });

    if (result.count !== files.length) {
      console.warn(`Attesi ${files.length} file, ma solo ${result.count} uploadati`);
    }

    return result.uploadedFiles;

  } catch (error) {
    console.error('Upload non riuscito:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

***


## Note

* Il contenuto del file viene codificato automaticamente in Base64 per 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&#39;opzione `sourceLocale`
* File di grandi dimensioni o un numero elevato di file possono richiedere valori di timeout più alti
* I riferimenti ai file restituiti da questo metodo sono necessari per le operazioni successive
* I riferimenti ai file includono `branchId` per un corretto controllo delle versioni con supporto per i branch
* I formati di file supportati includono JSON, MD, MDX, XML e altri: consulta il tipo `FileFormat` per l&#39;elenco completo

## Passaggi successivi

* Consulta [`setupProject`](/docs/core/class/methods/translation/setup-project) per preparare alla traduzione i file uploadati
* Consulta [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files) per avviare i processi di traduzione
* Consulta [`uploadTranslations`](/docs/core/class/methods/translation/upload-translations) per eseguire l'upload di traduzioni già esistenti
* Consulta `FileUpload` per i dettagli sulla struttura dei file