# 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-11-12
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&#39;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&#39;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.

## Video

The video is narrated in English, with English captions.

[How do I translate content in Payload CMS?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/v2/kb-translate-payload-content.mp4) (44 s)

Add localization to your Payload config and set localized true on each field; Payload then stores one value per locale but doesn't fill them. General Translation's gt-payload plugin adds a Translate button that writes each target locale, as a draft when drafts are enabled and directly otherwise. It never publishes. Add gtPlugin() to the config, set GT_PROJECT_ID and GT_API_KEY, and choose Translate.

## 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&#39;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&#39;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&#39;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&#39;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&#39;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&#39;impostazione regionale in CSV o JSON per chi traduce su file                                                                                          | Si importa il file tradotto nell&#39;impostazione regionale di destinazione                                                                                              | Preservare testo ricco, blocchi e ID delle righe durante l&#39;esportazione e la reimportazione, e riesportare dopo ogni modifica                             |
| Uno script basato su un&#39;API di IA (OpenAI API, Claude API)                                                                                         | Traduce molti documenti in un&#39;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&#39;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&#39;unica esecuzione per l&#39;intero sito, scrive ogni impostazione regionale, come bozza se le bozze sono abilitate | Avviare un&#39;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&#39;agenzia o un TMS gestisce già la traduzione e lavora su file. Usa uno script con un&#39;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.5) 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&#39;app di test con Payload 3.92.1, il plugin ha aggiunto all&#39;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&#39;[Avvio rapido di Payload](/docs/integrations/payload/quickstart).

## Cosa fa un&#39;esecuzione di traduzione

Il plugin usa l&#39;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&#39;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&#39;impostazione regionale non annulla gli altri.

## Revisionare, pubblicare e conservare le modifiche

Revisiona ogni impostazione regionale nell&#39;editor di Payload e pubblicala con le normali autorizzazioni di Payload: i controlli del plugin rispettano le regole di accesso dell&#39;utente che ha effettuato l&#39;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&#39;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&#39;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&#39;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): General Translation consente ai revisori di confrontare e modificare le traduzioni nella dashboard, usando etichette e commenti per tenere traccia della revisione. Puoi scaricare le modifiche salvate con la CLI oppure riportarle in una pull request alla successiva esecuzione della traduzione di Locadex. Gli sviluppatori possono anche inviare alla piattaforma le modifiche revisionate ai file con gt save-local.
- [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.
