# General Translation Platform: downloadFile
URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/download-file.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Scarica un file tradotto una volta completata la traduzione. Riferimento API per downloadFile.

Scarica un singolo file come testo UTF-8 decodificato, oppure in base64 per i dati binari `LOTTIE`. A seconda che venga passata o meno un'impostazione regionale, restituisce il file sorgente o la traduzione corrispondente.

## Panoramica [#overview]

Chiama `downloadFile` con un descrittore di file. Includi una `locale` per scaricare una traduzione, oppure omettila per scaricare il file sorgente.

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

// Scarica una traduzione
const translatedContent = await gt.downloadFile({
  fileId: 'file-123',
  branchId: 'branch-456',
  locale: 'es',
  versionId: 'version-789',
});

// Scarica il file sorgente (nessuna impostazione regionale specificata)
const sourceContent = await gt.downloadFile({
  fileId: 'file-123',
  branchId: 'branch-456',
});
```

Firma:

```typescript
downloadFile(
  file: {
    fileId: string;
    branchId?: string;
    locale?: string;
    versionId?: string;
    useLatestAvailableVersion?: boolean;
  },
  options?: DownloadFileOptions
): Promise<string>
```

*Nota: `downloadFile` richiede una chiave API (incluso l&#39;alias deprecato `devApiKey`), oltre a `projectId` sull&#39;istanza GT. Quando scarichi le traduzioni, funziona solo con traduzioni completate: verifica prima lo stato con [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data).*

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

* **Sorgente vs. traduzione.** Quando viene fornita un&#39;`impostazione regionale`, il file deve avere una traduzione completa per l&#39;impostazione regionale supportata risolta. Quando non viene fornita alcuna `impostazione regionale`, viene restituito il file sorgente.

- **Risoluzione dell&#39;impostazione regionale.** L&#39;impostazione regionale richiesta viene risolta nell&#39;impostazione regionale supportata utilizzata per l&#39;archiviazione. Ad esempio, `ja-JP` viene risolta in `ja`; impostazioni regionali supportate distinte come `en-GB` rimangono invariate.

* **Formato preservato.** La stringa restituita è nello stesso formato del file sorgente originale; per le traduzioni, tutto il testo traducibile viene convertito nell&#39;impostazione regionale di destinazione.
* **Risultato vuoto.** La classe delega il lavoro al download in batch e restituisce `''` se non viene restituito alcun file. In caso di errori HTTP o di trasporto, la promise viene comunque rifiutata. Non espone i dettagli sui file in sospeso.

## Parametri [#parameters]

| Parametro             | Descrizione                                              | Type                  | Facoltativo | Predefinito |
| --------------------- | -------------------------------------------------------- | --------------------- | ----------- | ----------- |
| [`file`](#file)       | Informazioni sul file che indicano quale file scaricare. | `object`              | No          | —           |
| [`options`](#options) | Configurazione della richiesta di download.              | `DownloadFileOptions` | Sì          | —           |

### `file` [#file]

**Tipo** `object` · **Obbligatorio**

Identifica il file da scaricare:

| Campo                       | Descrizione                                                                                                                            | Tipo      | Facoltativo | Predefinito          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- | -------------------- |
| `fileId`                    | Identificatore univoco del file da scaricare.                                                                                          | `string`  | No          | —                    |
| `branchId`                  | Branch da cui scaricare.                                                                                                               | `string`  | Sì          | branch predefinito   |
| `locale`                    | Impostazione regionale di destinazione della traduzione da scaricare. Omettilo per scaricare il file sorgente.                         | `string`  | Sì          | —                    |
| `versionId`                 | ID della versione del file.                                                                                                            | `string`  | Sì          | versione più recente |
| `useLatestAvailableVersion` | Se `true` e il `versionId` specificato non viene trovato, usa invece la versione disponibile più recente anziché restituire un errore. | `boolean` | Sì          | `false`              |

### `options` [#options]

**Type** `DownloadFileOptions` · **Facoltativo**

| Campo     | Descrizione                               | Type     | Facoltativo |
| --------- | ----------------------------------------- | -------- | ----------- |
| `timeout` | Timeout della richiesta, in millisecondi. | `number` | Sì          |

## Returns [#returns]

**Type** `Promise<string>`

Restituisce testo UTF-8 decodificato, base64 per `LOTTIE`, oppure `''` se non viene restituito alcun file; una stringa vuota non garantisce che l&#39;operazione sia andata a buon fine. Questo metodo di classe non è deprecato. Per i dettagli sui file in sospeso, usa il metodo generato `downloadFiles` tramite il [client API](/docs/platform/core/reference/api-client#endpoint-helpers), che restituisce il contenuto in base64.

## Esempi [#examples]

```typescript title="index.ts"
import { GT } from 'generaltranslation';
import type { FileUpload } from 'generaltranslation/types';

const fileContents = '{"greeting":"Hello"}';
const filePath = 'en.json';

// (1) Crea un'istanza GT
const targetLocales = ['es', 'fr', 'de'];
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// (2) Carica il file
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [{ source: fileUpload }];
const { uploadedFiles } = await gt.uploadSourceFiles(files, { sourceLocale: 'en' });

// (3) Accoda il job di traduzione del file
const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: targetLocales,
});

// (4) Attendi il completamento di tutte le traduzioni
const { fileId, versionId, branchId } = uploadedFiles[0];
const result = await gt.awaitJobs(enqueueResult, { timeoutSeconds: 300 });

if (!result.complete || result.jobs.some((job) => job.status !== 'completed')) {
  throw new Error('Translations are not ready to download');
}

// (5) Scarica un singolo file
const spanishContent = await gt.downloadFile({
  fileId,
  versionId,
  branchId,
  locale: 'es',
});

console.log('Spanish translation:', spanishContent);
```

## Note [#notes]

* Restituisce testo UTF-8, oppure base64 per il contenuto binario `LOTTIE`.
* Quando viene fornita un&#39;impostazione regionale, il file deve avere una traduzione completata per la relativa impostazione regionale supportata risolta.
* Quando non viene fornita alcuna impostazione regionale, viene restituito il file sorgente.
* Una risposta riuscita ma vuota restituisce `''`; in caso di errori HTTP o di trasporto, la promise viene rifiutata.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.