# General Translation Platform: uploadTranslations URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/translation/upload-translations.mdx Docs index: https://generaltranslation.com/llms.txt Description: Carica file tradotti esistenti che corrispondono ai file sorgente. Riferimento API per uploadTranslations. Carica traduzioni esistenti per i file sorgente già presenti nel progetto. Usalo quando migri traduzioni o carichi 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 include il contenuto sorgente completo usato per identificare un file sorgente già caricato, oltre a 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 ``` *Nota: `uploadTranslations` richiede un'`apiKey` (o `devApiKey`) e `projectId` nell'istanza GT.* ## Come funziona [#how-it-works] * **Sorgente esistente.** Carica prima la sorgente. L'oggetto `source` resta un `FileUpload` completo, comprensivo di contenuto e impostazione regionale; l'API deriva gli ID mancanti da quei dati e utilizza gli ID risultanti per individuare la versione sorgente esistente. * **Traduzioni.** Ogni elemento dell'array `translations` deve includere il contenuto e un'impostazione regionale di destinazione. * **Codifica del file.** Il contenuto testuale viene automaticamente codificato in base64. Le traduzioni binarie `LOTTIE` devono già contenere dati ZIP `.lottie` codificati in base64. * **Versionamento.** I riferimenti ai file restituiti includono `branchId` per il versionamento con supporto per i branch. ## Parametri [#parameters] | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | --------------------- | --------------------------------------------------- | ------------------------------------------------------ | ----------- | ----------- | | [`files`](#files) | Array di file sorgente e delle relative traduzioni. | `{ source: FileUpload; translations: FileUpload[] }[]` | No | — | | [`options`](#options) | Opzioni di configurazione per il caricamento. | `UploadFilesOptions` | No | — | ### `files` **Tipo** `{ source: FileUpload; translations: FileUpload[] }[]` · **Obbligatorio** Ogni entry associa un file sorgente completo ai relativi file tradotti: ```typescript { source: FileUpload; // contenuto sorgente e metadati translations: FileUpload[]; // file tradotti con il relativo contenuto } ``` Il valore `source` utilizza questi campi `FileUpload`: | Campo | Descrizione | Tipo | Facoltativo | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- | | `content` | Testo sorgente non elaborato, oppure contenuto binario codificato in base64 per `LOTTIE`. | `string` | No | | `fileName` | Nome del file corrispondente al file sorgente caricato in precedenza. | `string` | No | | `fileFormat` | Formato del file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No | | `locale` | Impostazione regionale del contenuto sorgente. | `string` | No | | `dataFormat` | Formato dei dati all'interno del file sorgente (`ICU`, `I18NEXT`, `JSX` o `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Sì | | `formatMetadata` | Metadati specifici del formato accettati insieme al descrittore sorgente; non modificano il record sorgente esistente. | `GTJsonFormatMetadata \| FormatMetadata` | Sì | | `branchId` | Branch che contiene il sorgente caricato in precedenza. Se omesso, viene usato il default branch. | `string` | Sì | | `fileId` | ID file del file sorgente. | `string` | Sì | | `versionId` | ID versione del file sorgente. | `string` | Sì | | `transformFormat` | Accettato da `FileUpload` e validato localmente, ma non utilizzato da questo endpoint di caricamento. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Sì | | `incomingBranchId` | Accettato da `FileUpload` ma non inviato da questo metodo. | `string` | Sì | | `checkedOutBranchId` | Accettato da `FileUpload` ma non inviato da questo metodo. | `string` | Sì | Ogni traduzione (un `FileUpload`) utilizza questi campi: | Campo | Descrizione | Tipo | Facoltativo | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------- | | `content` | Testo tradotto non elaborato, oppure contenuto binario codificato in base64 per `LOTTIE`. | `string` | No | | `fileName` | Richiesto da `FileUpload`; la traduzione memorizzata usa il nome del file sorgente. | `string` | No | | `fileFormat` | Formato del file. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | No | | `locale` | Impostazione regionale di destinazione della traduzione. | `string` | No | | `dataFormat` | Formato dei dati tradotti (`ICU`, `I18NEXT`, `JSX` o `STRING`). | [`DataFormat`](/docs/platform/core/reference/types/data-format) | Sì | | `fileId` | Accettato e inviato dal client, ma ignorato dall'endpoint; la traduzione eredita l'ID del file sorgente. | `string` | Sì | | `versionId` | Accettato e inviato dal client, ma ignorato dall'endpoint; la traduzione eredita l'ID versione del sorgente. | `string` | Sì | | `branchId` | Accettato e inviato dal client, ma ignorato dall'endpoint; la traduzione eredita il branch del sorgente. | `string` | Sì | | `transformFormat` | Accettato da `FileUpload` ma non inviato da questo metodo. | [`FileFormat`](/docs/platform/core/reference/types/file-format) | Sì | | `formatMetadata` | Accettato da `FileUpload` ma non inviato da questo metodo. | `GTJsonFormatMetadata \| FormatMetadata` | Sì | | `incomingBranchId` | Accettato da `FileUpload` ma non inviato da questo metodo. | `string` | Sì | | `checkedOutBranchId` | Accettato da `FileUpload` ma non inviato da questo metodo. | `string` | Sì | ### `options` **Tipo** `UploadFilesOptions` · **Obbligatorio** Configurazione per l'upload: | Campo | Descrizione | Tipo | Facoltativo | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------- | | `sourceLocale` | Impostazione regionale sorgente per la richiesta. Aggiorna anche l'impostazione regionale predefinita del progetto quando è diversa. | `string` | No | | `modelProvider` | Accettato dal tipo di opzioni condiviso ma non inviato da questo metodo di upload. Imposta invece il provider su [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files). | `string` | Sì | | `timeout` | Timeout della richiesta in millisecondi. | `number` | Sì | *Nota: `branchId` non è un'opzione di upload. È un campo a livello di singolo file in ciascun oggetto file, non fa parte di `UploadFilesOptions`.* ## Restituisce [#returns] **Tipo** `Promise` 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', }); const files = [ { // Questo esatto sorgente deve essere già stato caricato. source: { content: fs.readFileSync('./locales/en/common.json', 'utf8'), fileName: 'common.json', fileFormat: 'JSON' as const, locale: 'en', }, 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: { content: sourceFiles[0].source.content, fileName: uploadedFiles[0].fileName, fileFormat: uploadedFiles[0].fileFormat, locale: sourceFiles[0].source.locale, 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 fs from 'node:fs'; import { GT } from 'generaltranslation'; import type { FileUpload } from 'generaltranslation/types'; const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id', }); async function uploadAllTranslations( sourceFiles: FileUpload[], targetLocales: string[] ) { const files = sourceFiles.map((source) => ({ source, translations: targetLocales .map((locale) => { const translationPath = `./locales/${locale}/${source.fileName}`; try { return { content: fs.readFileSync(translationPath, 'utf8'), fileName: source.fileName, fileFormat: source.fileFormat, locale, }; } catch { // Il file di traduzione non esiste per questa impostazione regionale return null; } }) .filter((file): file is FileUpload => file !== null), })); const result = await gt.uploadTranslations(files, { sourceLocale: 'en', timeout: 60000, }); return result; } ``` ## Note [#notes] * L'oggetto `source` in ogni voce deve includere il contenuto, il nome del file, il formato del file e l'impostazione regionale. * La versione sorgente identificata da quell'oggetto deve già esistere nel progetto. * Ogni traduzione nell'array `translations` deve includere il contenuto e un'impostazione regionale di destinazione. * Questo metodo è utile per migrare traduzioni esistenti o caricare traduzioni sottoposte a revisione umana. * I riferimenti ai file includono `branchId` per il versionamento con supporto per i branch. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.