# General Translation Integrations: API programmatica URL: https://generaltranslation.com/it/docs/integrations/payload/reference/api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Richiama gt-payload dal codice server ed esamina i tipi di risultato e i componenti di amministrazione che esporta. Riferimento API per gli export di gt-payload. Il pacchetto radice esporta le funzioni di traduzione lato server e i relativi tipi. I sottopercorsi `gt-payload/client` e `gt-payload/rsc` espongono i componenti che [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) registra nel pannello di amministrazione di Payload. ## Esportazioni [#exports] | Esportazione | Punto di ingresso | Descrizione | | -------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- | | [`translateDocument`](#translate-document) | `gt-payload` | Traduce un documento di una collection o un global. | | [`translateSite`](#translate-site) | `gt-payload` | Traduce tutti i documenti e i global supportati. | | [`saveTranslations`](#save-translations) | `gt-payload` | Salva i valori dell'impostazione regionale attuale per una destinazione. | | [`saveSiteTranslations`](#save-site-translations) | `gt-payload` | Salva i valori dell'impostazione regionale attuale per l'intero sito. | | [`gtPlugin`](#plugin) | `gt-payload` | Aggiunge il workflow di amministrazione a una config di Payload. | | [`GtDocumentControls`](#admin-components) | `gt-payload/client` | Controllo di traduzione document-level. | | [`GtNavLink`](#admin-components) | `gt-payload/client` | Link alla vista Traduzioni site-wide. | | [`GtRunsProvider`](#admin-components) | `gt-payload/client` | Riprende le esecuzioni di traduzione in sospeso. | | [`GtTranslationsClient`](#admin-components) | `gt-payload/client` | Contenuto lato client della vista Traduzioni. | | [`GtTranslationsView`](#admin-components) | `gt-payload/rsc` | Vista server registrata in `/translations`. | | [`GtPluginOptions`](#gtpluginoptions) | `gt-payload` | Opzioni accettate da `gtPlugin`. | | [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload` | Ingresso per le operazioni su un singolo documento. | | [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload` | Ingresso per le operazioni site-wide. | | [`TranslateTarget`](#translatetarget) | `gt-payload` | Identità di un documento di una collection o di un global. | | [`TranslateResult`](#translateresult-and-localeresult) | `gt-payload` | Risultato della traduzione per una destinazione. | | [`LocaleResult`](#translateresult-and-localeresult) | `gt-payload` | Risultato per un'impostazione regionale di destinazione. | | [`SkippedReason`](#skippedstring-and-skippedreason) | `gt-payload` | Motivo per cui una string non è stata scritta. | | [`SkippedString`](#skippedstring-and-skippedreason) | `gt-payload` | Chiave ignorata e relativo motivo. | | [`SiteResult`](#siteresult-and-documentresult) | `gt-payload` | Risultato della traduzione site-wide. | | [`DocumentResult`](#siteresult-and-documentresult) | `gt-payload` | Destinazione associata al relativo risultato. | | [`SaveTranslationsResult`](#savetranslationsresult) | `gt-payload` | Risultato del salvataggio delle modifiche locali. | | [`GtClient`](#gtclient) | `gt-payload` | Metodi di General Translation richiesti dal plugin. | ## `translateDocument` [#translate-document] **Ingresso** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Returns** `Promise` Carica un singolo documento di una collection o un global, attende fino a un'ora il completamento dei relativi job e scrive le traduzioni completate in Payload. ```ts import { GT } from 'generaltranslation'; import { translateDocument } from 'gt-payload'; const result = await translateDocument({ payload, gt: new GT({ projectId: process.env.GT_PROJECT_ID, apiKey: process.env.GT_API_KEY, sourceLocale: payload.config.localization ? payload.config.localization.defaultLocale : undefined, }), target: { collection: 'pages', id: pageId }, locales: ['es', 'fr'], }); ``` Per gli errori previsti relativi a documenti, autorizzazioni, job e traduzioni, il risultato segnala gli errori anziché sollevare un'eccezione. Le chiamate a Payload o al client possono comunque generare un rifiuto se un'operazione fallisce in modo imprevisto. ## `translateSite` [#translate-site] **ingresso** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Returns** `Promise` Elenca tutti i documenti delle collection e i global con campi localizzati traducibili, quindi li traduce in un unico batch. I documenti privi di impostazioni regionali tradotte e senza errori vengono omessi da `documents`. ```ts import { translateSite } from 'gt-payload'; const result = await translateSite({ payload, gt, locales: ['es', 'fr'], user, }); ``` ## `saveTranslations` [#save-translations] **ingresso** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **Returns** `Promise` Invia a General Translation i valori correnti delle impostazioni regionali di Payload per una destinazione, senza accodare nuovi lavori di traduzione. Se General Translation non conosce ancora il documento sorgente, questa funzione lo carica per prima cosa. ```ts import { saveTranslations } from 'gt-payload'; const result = await saveTranslations({ payload, gt, target: { global: 'site-settings' }, locales: ['es', 'fr'], user, }); ``` ## `saveSiteTranslations` [#save-site-translations] **ingresso** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **Returns** `Promise<{ documents: DocumentResult[] }>` Esegue il workflow salvataggio delle modifiche locali per ciascuna destinazione gestita da [`translateSite`](#translate-site). ```ts import { saveSiteTranslations } from 'gt-payload'; const result = await saveSiteTranslations({ payload, gt, locales: ['es', 'fr'], user, }); ``` ## `gtPlugin` [#plugin] **Tipo** `(options?: GtPluginOptions) => Plugin` Restituisce un plugin Payload. Consulta [Configurazione del plugin Payload](/docs/integrations/payload/reference/plugin-configuration) per l'elenco completo delle opzioni e dei relativi effetti collaterali. ## Tipi di ingresso [#input-types] ### `GtPluginOptions` ```ts type GtPluginOptions = { projectId?: string; apiKey?: string; customMapping?: CustomMapping; client?: GtClient; }; ``` ### `TranslateDocumentInput` e `TranslateSiteInput` ```ts type TranslateDocumentInput = { payload: Payload; gt: GtClient; target: TranslateTarget; locales: string[]; saveLocalEdits?: boolean; user?: TypedUser | null; }; type TranslateSiteInput = Omit; ``` | Proprietà | Descrizione | Tipo | Facoltativo | Predefinito | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ----------- | ---------------------------------------------------- | | `payload` | Istanza di Payload inizializzata. | `Payload` | No | — | | `gt` | Client usato per caricamenti, job, scaricamenti e nuovi tentativi più brevi. | [`GtClient`](#gtclient) | No | — | | `target` | Documento di una collection o global. Solo per le operazioni sui documenti. | [`TranslateTarget`](#translatetarget) | No | — | | `locales` | Codici delle impostazioni locali di Payload da elaborare. L'impostazione regionale sorgente e gli eventuali duplicati vengono esclusi. | `string[]` | No | — | | `saveLocalEdits` | Salva le modifiche note alle impostazioni regionali prima di tradurre e preserva quelle che non è possibile inviare. | `boolean` | Sì | `false` | | `user` | Utente di Payload le cui regole di accesso vengono applicate alle operazioni di lettura e scrittura. | `TypedUser \| null` | Sì | Comportamento lato server della Local API di Payload | ### `TranslateTarget` ```ts type TranslateTarget = | { collection: string; id: string | number } | { global: string }; ``` Gli ID delle collection sono univoci solo all'interno di una collection, quindi l'identità del file in General Translation è data dalla combinazione di entrambi i valori. Un global utilizza invece il proprio slug. ## Tipi di risultato [#result-types] ### `TranslateResult` e `LocaleResult` ```ts type TranslateResult = { error?: string; usageLimitReached?: true; locales: Record; }; type LocaleResult = | { status: 'applied'; applied: string[]; skipped: SkippedString[]; } | { status: 'failed'; error: string; }; ``` `error` descrive un errore a livello di destinazione. `usageLimitReached` è presente solo quando General Translation rifiuta l'elaborazione con stato `402`. `applied` contiene le chiavi stabili dei campi scritte in Payload. `skipped` indica quali stringhe traducibili non sono state scritte e per quale motivo. ### `SkippedString` e `SkippedReason` ```ts type SkippedString = { key: string; reason: SkippedReason; }; type SkippedReason = | 'removed' | 'broken_markup' | 'missing' | 'unsaved_edit'; ``` | Motivo | Significato | | --------------- | -------------------------------------------------------------------------------------------------- | | `removed` | La riga, il blocco o il campo di origine non esiste più. | | `broken_markup` | Non è stato possibile ricostruire in modo sicuro il testo ricco o i link restituiti. | | `missing` | Non è stato restituito alcun valore tradotto per la chiave di origine. | | `unsaved_edit` | Non è stato possibile inviare una modifica di Payload, quindi `saveLocalEdits` l'ha mantenuta. | ### `SiteResult` e `DocumentResult` ```ts type DocumentResult = { target: TranslateTarget; result: T; }; type SiteResult = { error?: string; documents: DocumentResult[]; }; ``` `DocumentResult` mantiene i successi parziali e gli errori associati al rispettivo documento di collection o global. ### `SaveTranslationsResult` ```ts type SaveTranslationsResult = { error?: string; locales: Record< string, | { status: 'saved'; unsaved?: number } | { status: 'no_translations'; unsaved?: number } | { status: 'failed'; error: string } >; }; ``` `unsaved` indica il numero di stringhe che il plugin non è riuscito a inviare perché i relativi link non corrispondono a quelli del codice sorgente. ### `GtClient` `GtClient` è il sottoinsieme della classe `GT` di `generaltranslation` utilizzato dal plugin: ```ts type GtClient = Pick< GT, | 'uploadSourceFiles' | 'enqueueFiles' | 'awaitJobs' | 'downloadFileBatch' | 'uploadTranslations' | 'checkJobStatus' | 'translateMany' | 'customMapping' >; ``` In produzione usa un'istanza di `GT`. Il tipo più specifico consente di usare anche i test double. ## Componenti di amministrazione [#admin-components] Il plugin registra queste esportazioni tramite il percorso dell'import map: | Componente | Punto di ingresso | Ruolo | | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------ | | `GtDocumentControls` | `gt-payload/client` | Aggiunge il pulsante **Translate** e il pannello laterale a un documento o a un global. | | `GtNavLink` | `gt-payload/client` | Aggiunge il link di navigazione **Traduzioni**. | | `GtRunsProvider` | `gt-payload/client` | Individua e fa avanzare le esecuzioni in sospeso mentre il pannello di amministrazione è aperto. | | `GtTranslationsClient` | `gt-payload/client` | Renderizza i controlli site-wide e la tabella di copertura. | | `GtTranslationsView` | `gt-payload/rsc` | Avvolge la vista client nel template di amministrazione di Payload. | Anziché registrare singolarmente questi componenti, aggiungi [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration). Sono esportati solo per consentire all'import map generata da Payload di risolvere la configurazione del plugin. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.