# General Translation Knowledge Base: Come si traducono i contenuti in Payload CMS? URL: https://generaltranslation.com/it/kb/translate-payload-content.mdx Docs index: https://generaltranslation.com/llms.txt Description: Aggiungi localization alla config di Payload e imposta localized true su ogni campo; Payload memorizzerà un valore per ogni impostazione regionale, ma senza compilarlo. Il plugin gt-payload di General Translation aggiunge un pulsante Translate che scrive ogni impostazione regionale di destinazione, come bozza se le bozze sono abilitate e direttamente in caso contrario. Non pubblica mai. Category: Strumenti per il flusso di lavoro Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Payload CMS memorizza le traduzioni a livello di campo. Quando la config contiene un blocco `localization`, ogni campo contrassegnato con `localized: true` contiene un valore per ciascuna impostazione regionale all'interno dello stesso documento, e il frontend richiede una lingua tramite il parametro `locale`. Payload però non genera questi valori, e compilarli è un lavoro delicato: il testo ricco di Lexical (l'editor predefinito di Payload) contiene link, formattazioni e blocchi incorporati; array e blocchi annidano campi localizzati; slug, relazioni e caricamenti devono restare invariati; e le correzioni apportate da un redattore a una traduzione non devono andare perse al successivo aggiornamento. ## Come Payload memorizza le traduzioni In Payload 3 la localizzazione fa parte della config principale di Payload ([documentazione di Payload sulla localizzazione](https://payloadcms.com/docs/configuration/localization)). Le impostazioni regionali vanno elencate una sola volta: ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; export default buildConfig({ // ... la tua configurazione esistente localization: { locales: ['en', 'es', 'fr'], // oppure oggetti con code, label, rtl e fallbackLocale defaultLocale: 'en', fallback: true, // impostazione predefinita: un valore mancante usa come fallback l'impostazione locale predefinita }, }); ``` Poi contrassegna ogni campo da tradurre. `localized: true` funziona su qualsiasi campo con nome, inclusi array e blocchi, e i campi annidati all'interno di un contenitore localizzato diventano insiemi distinti per ogni impostazione regionale. Payload avverte che modificare `localized` su un campo che contiene già dati ne comporta la perdita, quindi decidi prima di caricare i contenuti. Ogni API accetta un'impostazione regionale. REST usa `?locale=es` e `?fallback-locale=none`, GraphQL accetta gli argomenti `locale` e `fallbackLocale` e la Local API accetta le stesse opzioni: ```ts // Valori in spagnolo, con fallback all'inglese per i campi privi di valore in spagnolo const page = await payload.findByID({ collection: 'pages', id, locale: 'es' }); // Solo valori in spagnolo; i campi non tradotti vengono restituiti vuoti const strict = await payload.findByID({ collection: 'pages', id, locale: 'es', fallbackLocale: false }); // Tutte le impostazioni regionali in una volta: all.title è { en: 'Pricing', es: 'Precios' } const all = await payload.findByID({ collection: 'pages', id, locale: 'all' }); ``` In un'app di test con Payload 3.92, una pagina con titoli solo in inglese e spagnolo restituiva per impostazione predefinita il titolo inglese per `fr` e un titolo vuoto con `fallbackLocale: false`. È un comportamento predefinito da tenere presente: un'impostazione regionale non tradotta restituisce silenziosamente la lingua di origine anziché generare un errore. ## Modi per tradurre i contenuti di Payload I plugin ufficiali di Payload includono SEO, Redirects, Search e Import/Export, ma nessuno traduce i contenuti ([plugin di Payload](https://payloadcms.com/docs/plugins/overview)). Ecco le opzioni disponibili: | Approccio | Punti di forza | Come le traduzioni arrivano in Payload | Cosa resta a tuo carico | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I redattori inseriscono a mano ogni impostazione regionale | Il traduttore vede ogni campo nel pannello di amministrazione | Si cambia l'impostazione regionale del pannello di amministrazione e si digita ogni valore | Tutte le traduzioni, oltre a individuare i campi cambiati dopo ogni modifica alla sorgente | | Il [plugin Import/Export](https://payloadcms.com/docs/plugins/import-export) di Payload con traduttori o un sistema di gestione delle traduzioni (TMS) | Esporta un'impostazione regionale in CSV o JSON per chi traduce su file | Si importa il file tradotto nell'impostazione regionale di destinazione | Preservare testo ricco, blocchi e ID delle righe durante l'esportazione e la reimportazione, e riesportare dopo ogni modifica | | Uno script basato su un'API di IA (OpenAI API, Claude API) | Traduce molti documenti in un'unica esecuzione, con il tono e la terminologia definiti nel prompt | Lo script scrive con `payload.update({ locale })` | Attraversare i campi annidati e il JSON di Lexical, fornire il contesto per ogni stringa, garantire la coerenza terminologica, la revisione e le riesecuzioni | | [Lingo.dev](https://lingo.dev/guides/payload) (`@lingo.dev/payloadcms`) | Traduce automaticamente testo localizzato e testo ricco quando si salva la sorgente | Il servizio ospitato scrive ogni impostazione regionale, già pubblicata o come bozza | Il Piano Enterprise di Lingo.dev, un utente di servizio Payload con una chiave API e l'editor Lexical | | General Translation (`gt-payload`) | Traduce i campi localizzati `text`, `textarea` e `richText` di Lexical, blocchi annidati inclusi, applicando il Glossario e i prompt personalizzati del tuo progetto | Un pulsante **Translate** per ogni documento, o un'unica esecuzione per l'intero sito, scrive ogni impostazione regionale, come bozza se le bozze sono abilitate | Avviare un'esecuzione dopo le modifiche alla sorgente, revisionare ogni impostazione regionale e pubblicare le bozze | Traduci a mano se hai pochi documenti e un traduttore per lingua. Usa Import/Export se un'agenzia o un TMS gestisce già la traduzione e lavora su file. Usa uno script con un'API di IA per un batch una tantum che verrà poi revisionato. Usa General Translation quando i documenti contengono testo ricco e blocchi, cambiano spesso e devono adottare la stessa terminologia della tua app e della tua documentazione. (Consulta [General Translation vs. Lingo.dev](/kb/general-translation-vs-lingo-dev) per un confronto tra i due servizi.) ## Tradurre i contenuti di Payload con gt-payload Il plugin `gt-payload` di General Translation (con licenza MIT, versione 0.1.2) richiede Payload 3.90.0 o versioni successive con `localization` configurato, Next.js 15.2.9 o versioni successive, React 19.0.1 o versioni successive e almeno un campo localizzato. 1. Installalo con `npm install gt-payload`. 2. Aggiungi il plugin alla tua config. Il plugin legge le impostazioni regionali e i campi localizzati direttamente da Payload, quindi nella maggior parte dei casi non richiede opzioni: ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; import { gtPlugin } from 'gt-payload'; export default buildConfig({ // ... la tua config esistente localization: { locales: ['en', 'es', 'fr'], defaultLocale: 'en', }, plugins: [gtPlugin()], }); ``` 3. Sul server che esegue Payload, imposta `GT_PROJECT_ID` e, come `GT_API_KEY`, una [chiave API di progetto](/docs/platform/dashboard/reference/api-keys#create-project-keys) con autorizzazioni **All**. Non esporre mai la chiave nel codice client. 4. Esegui `npx payload generate:importmap` per consentire al pannello di amministrazione di caricare i componenti del plugin. Su PostgreSQL o SQLite, crea e applica una migrazione (`npx payload migrate:create`, poi `npx payload migrate`) per le due collection aggiunte dal plugin. 5. Apri un documento salvato, scegli **Translate**, seleziona le impostazioni locali di destinazione e scegli **Translate into …**. Per tradurre tutto, apri invece **Traduzioni** dalla navigazione del pannello di amministrazione. In un'app di test con Payload 3.92.1, il plugin ha aggiunto all'import map e ai tipi generati i propri controlli del documento, la vista **Traduzioni** e le collection `gt-translation-runs` e `gt-translation-locks`, e `next build` è stato completato correttamente. I suoi endpoint rifiutano le richieste prive di un utente Payload autenticato. Per tutti i passaggi, consulta l'[Avvio rapido di Payload](/docs/integrations/payload/quickstart). ## Cosa fa un'esecuzione di traduzione Il plugin usa l'impostazione locale predefinita come sorgente e invia il testo localizzato di ogni documento al tuo progetto General Translation, dove compare con la sua identità Payload (`collection/id`, oppure lo slug di un global). Traduce i campi `text` localizzati (incluse le liste `hasMany`), i campi `textarea` e il `richText` di Lexical, anche all'interno di gruppi, schede, array, blocchi e blocchi di testo ricco. Il testo ricco conserva formattazione, link, caricamenti e blocchi; una stringa il cui markup non può essere associato alla sorgente viene ignorata e segnalata, anziché essere salvata danneggiata. Restano invariati i campi slug, i campi di sola lettura, nascosti e virtuali, i valori `text` che sembrano URL, percorsi o indirizzi email, le relazioni, i caricamenti, le date, i numeri e gli ID. Per escludere un campo, ad esempio uno SKU, imposta `custom: { gt: { translate: false } }`. Quando una traduzione supera il `maxLength` di un campo, il plugin ne richiede una più breve e, solo se continua a non rientrare nel limite, la tronca al confine di una parola aggiungendo i puntini di sospensione. (Vedi [contenuti supportati](/docs/integrations/payload/reference/supported-content).) I risultati vengono salvati nello stesso documento, sotto ciascuna impostazione regionale di destinazione. Per le collection e i global con [bozze](https://payloadcms.com/docs/versions/drafts) viene creata una bozza; gli altri vengono salvati direttamente. Il plugin non pubblica mai. Le esecuzioni sono memorizzate in Payload, quindi proseguono anche dopo la chiusura della scheda: vengono riprese al successivo accesso al pannello di amministrazione, oppure completate dalla [coda dei job](https://payloadcms.com/docs/jobs-queue/overview) di Payload se è configurato `jobs.autoRun`. Un errore in un documento o in un'impostazione regionale non annulla gli altri. ## Revisionare, pubblicare e conservare le modifiche Revisiona ogni impostazione regionale nell'editor di Payload e pubblicala con le normali autorizzazioni di Payload: i controlli del plugin rispettano le regole di accesso dell'utente che ha effettuato l'accesso. Se un redattore corregge una traduzione in Payload, attiva **Save local edits before translating** nel pannello **Traduzioni** (è disattivata per impostazione predefinita) oppure scegli **Save local edits**, così General Translation manterrà quella formulazione nelle esecuzioni successive. Con il salvataggio, i valori di Payload diventano la fonte di riferimento e sostituiscono quanto memorizzato da General Translation per quel documento. (Vedi [gestione delle traduzioni](/docs/integrations/payload/guides/managing-translations).) La qualità della traduzione dipende dal contesto. Assegna un [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) al progetto: il relativo Glossario e i prompt personalizzati guideranno ogni esecuzione di Payload, così il nome di un prodotto o di un livello di piano verrà tradotto allo stesso modo sia nelle pagine del CMS sia nella tua app. Per avviare le traduzioni dal tuo codice, ad esempio da un hook o da un job pianificato, chiama [`translateDocument`](/docs/integrations/payload/reference/api#translate-document) o `translateSite` da `gt-payload`. L'utilizzo viene fatturato in base ai [prezzi di General Translation](https://generaltranslation.com/pricing). Per gli altri aspetti di un sito multilingue, come gli URL per lingua e `hreflang`, consulta [Come rendo multilingue un sito web?](/kb/make-website-multilingue). La stessa operazione in altri CMS è descritta per [Sanity](/kb/translate-sanity-content) e [Storyblok](/kb/translate-storyblok-content). ## Punti chiave * Payload 3 memorizza le traduzioni a livello di singolo campo: aggiungi `localization` alla config, imposta `localized: true` e leggi i contenuti con `locale` e `fallback-locale`. * Con il valore predefinito `fallback: true`, un'impostazione regionale non ancora tradotta restituisce il testo di origine: verifica quindi la copertura prima di collegare una lingua. * Payload non offre un plugin di traduzione ufficiale; il suo plugin Import/Export consente però di esportare un'impostazione regionale in formato CSV o JSON da inviare ai traduttori. * `gt-payload` di General Translation aggiunge `gtPlugin()`, un pulsante **Translate** e una pagina **Traduzioni** a livello di sito; traduce i campi localizzati di tipo text, textarea e testo ricco Lexical e, dove le bozze sono abilitate, salva ogni impostazione regionale come bozza, senza mai pubblicare. * Attiva **Save local edits before translating** affinché le modifiche apportate in Payload non vadano perse nelle esecuzioni successive. ## Related questions - [Come si traducono i contenuti in Sanity?](https://generaltranslation.com/it/kb/translate-sanity-content.mdx): Salva ogni lingua come documento separato oppure come valore per impostazione regionale in ciascun campo, quindi traduci la sorgente in ogni impostazione regionale di destinazione. Il plugin gt-sanity di General Translation aggiunge un'azione Translate a Sanity Studio e, per impostazione predefinita, importa ogni traduzione come bozza da revisionare e pubblicare. - [Come si traducono i contenuti in Storyblok?](https://generaltranslation.com/it/kb/translate-storyblok-content.mdx): In Storyblok, aggiungi le lingue di destinazione allo spazio e assegna a ogni campo traducibile un valore per ciascuna lingua. L'integrazione Storyblok di General Translation compila questi valori dalla dashboard con Sincronizza e applica, sotto forma di bozze da revisionare e pubblicare in Storyblok. - [Come si rende multilingue un sito web?](https://generaltranslation.com/it/kb/make-website-multilingual.mdx): Scegli dove gestire le traduzioni (in un proxy, in un plugin del CMS, in un site builder o nel tuo codice), poi assegna a ogni lingua un URL dedicato, come raccomanda Google. Traduci le pagine per intero, compresi titoli e meta description, collega le versioni con hreflang e offri un selettore della lingua anziché reindirizzare automaticamente i visitatori. - [Come si revisionano e modificano le traduzioni?](https://generaltranslation.com/it/kb/review-translations.mdx): Confronta ogni traduzione con il testo sorgente e con le altre impostazioni regionali, e correggi ciò che non suona bene. Con General Translation modifichi le traduzioni nella pagina Traduzioni della dashboard e tieni traccia della revisione con etichette e commenti; alla successiva esecuzione della traduzione, Locadex, il suo Agente IA, riporta le modifiche in una pull request. - [General Translation vs. Lingo.dev: quale scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-lingo-dev.mdx): Lingo.dev si basa su motori di traduzione configurabili, con strumenti CLI, React e GitHub per utilizzarli. General Translation è una piattaforma di localizzazione: librerie, contesto del codice, terminologia condivisa, revisione nella Dashboard inclusa in tutti i piani e Locadex, che internazionalizza anche il tuo codice. Scegli Lingo.dev se ti serve il controllo del modello per ogni coppia di lingue. ## Previous and next questions - Previous question: [Come si traduce un'app Flask o FastAPI?](https://generaltranslation.com/it/kb/translate-python-app.mdx) - Next question: [Come si traducono i file .resx in un'app .NET?](https://generaltranslation.com/it/kb/translate-resx-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.