# General Translation Platform: Tradurre i file
URL: https://generaltranslation.com/it/docs/platform/core/guides/translating-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Come caricare, tradurre e scaricare file con la libreria generaltranslation.

La libreria `generaltranslation` può tradurre interi file sorgente. Questa pagina illustra i flussi di lavoro per il caricamento, l'accodamento, il controllo dello stato e il download dei file.

## Prima di iniziare [#before-start]

Assicurati di aver completato il [Quickstart](/docs/platform/core/quickstart) per installare `generaltranslation` e inizializzare la classe [GT](/docs/platform/core/reference/gt-class/constructor).

## Come funziona la traduzione dei file [#file-translation-works]

I file vengono tradotti tramite job:

1. Carica il file sorgente.
2. Accoda il file per la traduzione.
3. Verifica lo stato della traduzione.
4. Scarica il file tradotto.

La traduzione dei file richiede più chiamate perché i progetti spesso traducono molti file. Suddividere il processo in passaggi separati ti offre più flessibilità nell'uso dell'API: rende più semplice raggruppare i file in batch, ritentare i job non riusciti, eseguire il polling dei job e scaricare l'output quando è pronto.

Il caricamento crea i record dei file sorgente. La chiamata a [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) può quindi avviare un job per ogni coppia di file sorgente e impostazione regionale di destinazione che richiede ancora lavoro. (Per ulteriori informazioni, consulta i metodi [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) e [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data)).

Per i file SVG, passa il sorgente XML in UTF-8 con `fileFormat: 'SVG'`. La traduzione aggiorna i nodi di testo preservando forme e stili. Un passaggio di layout asincrono può ricentrare il testo e accorciare le traduzioni in eccesso mantenendo le dimensioni dei caratteri originali, quindi attendi che il file sia completo prima di scaricarlo. L'XML malformato viene rifiutato.

## 1. Carica il file sorgente [#upload]

Per esempio, questa guida traduce questo file JSON in inglese:

```json
{
  "hello": "Hello",
  "world": "World"
}
```

Leggi il file, formatta il contenuto, quindi chiama [uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) per caricare i file.

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

// (i) Leggi il contenuto di un file
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) Formatta il contenuto del file
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) Carica il file
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);
```

La risposta restituisce un elenco di riferimenti ai file. Questo ti consente, in seguito, di accodare il file per la traduzione, verificarne lo stato e scaricare il file tradotto.

```ts title="Output"
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    branchId: '123456789',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]
```

## 2. Accoda il file per la traduzione [#enqueue]

Usa [enqueueFiles](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) con il riferimento al file caricato e i locale di destinazione. In questo esempio, tradurremo in spagnolo (`es`).

```typescript title="src/index.ts"
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  branchId: uploadedFiles[0].branchId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};

const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
    sourceLocale: 'en',
    targetLocales: ['es'],
  }
);
```

La risposta restituisce un risultato contenente informazioni sul job.

```ts title="Output"
{
  jobData: {
    'job-123456': {
      sourceFileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      targetLocale: 'es',
      projectId: 'your-project-id',
      force: false
    }
  },
  locales: ['es'],
  message: 'Successfully enqueued 1 file translation jobs in 1 batch(es)'
}
```

## 3. Verifica lo stato del file [#status]

Usa [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) per verificare se il file tradotto è completo e pronto per il download.

```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];

const status = await gt.queryFileData({
  translatedFiles: [
    {
      fileId,
      versionId,
      branchId,
      locale: 'es',
    },
  ],
});
```

Se il file è ancora in corso di traduzione, `completedAt` è `null`. Una volta completato, contiene un timestamp:

```ts title="Output"
{
  translatedFiles: [
    {
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      locale: 'es',
      completedAt: '2024-01-15T12:00:00Z'
    }
  ]
}
```

## 4. Scarica il file tradotto [#download]

Infine, scarica il file tradotto utilizzando il metodo [downloadFile](/docs/platform/core/reference/gt-class-methods/translation/download-file).

```typescript title="src/index.ts"
const content = await gt.downloadFile({
  fileId,
  versionId,
  branchId,
  locale: 'es',
});
```

La risposta restituisce il contenuto del file tradotto. In questo esempio viene restituito:

```json title="Output"
{
  "hello": "Hola",
  "world": "Mundo"
}
```

## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/locale-codes

## Sitemap

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