# General Translation Platform: uploadTranslations
URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/upload-translations.mdx
---

title: uploadTranslations
description: Carica file tradotti esistenti che corrispondono ai file sorgente. Riferimento API per uploadTranslations.

---

Carica file di traduzione che corrispondono a file sorgente caricati in precedenza. Usalo con General Translation quando hai già delle traduzioni — ad esempio, per migrare traduzioni esistenti o caricare quelle sottoposte a revisione umana — invece di generarle tramite il servizio di traduzione.

## Panoramica [#overview]

Chiama `uploadTranslations` con un array di upload di traduzioni e un oggetto options. Ogni upload fa riferimento a un file sorgente esistente e contiene uno o più file tradotti.

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

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

Firma:

```typescript
uploadTranslations(
  files: { source: FileUpload; translations: FileUpload[] }[],
  options: UploadFilesOptions
): Promise<UploadFilesResponse>
```

*Nota: `uploadTranslations` richiede un&#39;`apiKey` (o `devApiKey`) e `projectId` nell&#39;istanza GT. Devi prima caricare i file sorgente corrispondenti con [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files).*

## Come funziona [#how-it-works]

* **Riferimento alla sorgente.** L&#39;oggetto `source` in ogni voce è un riferimento a un file sorgente già caricato; il relativo contenuto non è necessario.
* **Traduzioni.** Ogni elemento dell&#39;array `translations` deve includere il contenuto e un&#39;impostazione regionale di destinazione.
* **Versionamento.** I riferimenti ai file restituiti includono `branchId` per il versionamento con supporto dei branch.

## Parametri [#parameters]

| Parametro             | Descrizione                                                       | Tipo                                                   | Facoltativo | Predefinito |
| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ | ----------- | ----------- |
| [`files`](#files)     | Array di riferimenti ai file sorgente e alle relative traduzioni. | `{ source: FileUpload; translations: FileUpload[] }[]` | No          | —           |
| [`options`](#options) | Opzioni di configurazione per il caricamento.                     | `UploadFilesOptions`                                   | No          | —           |

### `files` [#files]

**Tipo** `{ source: FileUpload; translations: FileUpload[] }[]` · **Obbligatorio**

Ogni voce abbina un riferimento a un file sorgente ai file tradotti corrispondenti:

```typescript
{
  source: FileUpload; // riferimento a un file sorgente esistente (nessun contenuto necessario)
  translations: FileUpload[]; // file tradotti con contenuto
}
```

Il riferimento `source` (un `FileUpload`) utilizza questi campi:

| Campo        | Descrizione                                                                                                                      | Tipo         | Facoltativo |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
| `fileName`   | Nome del file corrispondente al file sorgente caricato in precedenza.                                                            | `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          |
| `fileId`     | ID del file sorgente.                                                                                                            | `string`     | Sì          |
| `versionId`  | ID della versione del file sorgente.                                                                                             | `string`     | Sì          |

Ogni traduzione (un `FileUpload`) utilizza questi campi:

| Campo        | Descrizione                                                                                                                      | Tipo         | Facoltativo |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
| `content`    | Contenuto grezzo del file tradotto come stringa.                                                                                 | `string`     | No          |
| `fileName`   | Nome del file della traduzione.                                                                                                  | `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          |
| `locale`     | Impostazione regionale di destinazione della traduzione.                                                                         | `string`     | No          |
| `fileId`     | ID del file.                                                                                                                     | `string`     | Sì          |
| `versionId`  | ID della versione.                                                                                                               | `string`     | Sì          |

### `options` [#options]

**Tipo** `UploadFilesOptions` · **Obbligatorio**

Configurazione per l&#39;upload:

| Campo           | Descrizione                                       | Tipo     | Facoltativo |
| --------------- | ------------------------------------------------- | -------- | ----------- |
| `sourceLocale`  | L&#39;impostazione regionale di origine dei file. | `string` | No          |
| `modelProvider` | Provider del modello di IA preferito.             | `string` | Sì          |
| `timeout`       | Timeout della richiesta in millisecondi.          | `number` | Sì          |

*Nota: `branchId` non è un&#39;opzione di upload. È un campo a livello di singolo file in ciascun oggetto file, non fa parte di `UploadFilesOptions`.*

## Restituisce [#returns]

**Tipo** `Promise<UploadFilesResponse>`

Si risolve con un `UploadFilesResponse` che contiene i riferimenti ai file caricati e un riepilogo:

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // riferimenti ai file caricati
  count: number; // numero di file caricati con successo
  message: string; // messaggio di stato dall'API
};
```

## Esempi [#examples]

```typescript
// Utilizzo base: carica le traduzioni per i file sorgente precedentemente caricati
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Si assume che il file sorgente sia stato precedentemente caricato
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id',
    },
    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
// Flusso completo: carica i file sorgente, poi le loro traduzioni
import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Passaggio 1: carica i file sorgente
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',
});

// Passaggio 2: carica le traduzioni esistenti
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      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
// Caricamento in batch delle traduzioni per più file sorgente
import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map((sourceRef) => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId,
    },
    translations: targetLocales
      .map((locale) => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale,
          };
        } catch {
          // Il file di traduzione non esiste per questa impostazione regionale
          return null;
        }
      })
      .filter(Boolean),
  }));

  const result = await gt.uploadTranslations(files, {
    sourceLocale: 'en',
    timeout: 60000,
  });

  return result;
}
```

## Note [#notes]

* I file sorgente devono essere caricati prima con [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files).
* L&#39;oggetto `source` in ogni voce fa riferimento a un file sorgente esistente: il contenuto non è necessario.
* Ogni traduzione nell&#39;array `translations` deve includere il contenuto e un&#39;impostazione regionale di destinazione.
* Questo metodo è utile per migrare traduzioni esistenti o caricare traduzioni revisionate manualmente.
* I riferimenti ai file includono `branchId` per il versionamento con supporto per i branch.