Come tradurre i campi personalizzati ACF in WordPress: gruppi di campi, ripetitori, pagine delle opzioni

Prima di iniziare

Installa e attiva questi plugin:

• Advanced Custom Fields o ACF Pro.
• WPML e WPML Traduzione stringhe.
• ACFML (il componente aggiuntivo trattato in questa pagina).

I tuoi gruppi di campi dovrebbero essere già configurati in ACF. Puoi modificare le preferenze di traduzione per ogni campo in un secondo momento, quindi l’ordine delle operazioni non ha importanza. Configura i gruppi di campi, poi torna ad ACFML.

Scegli una modalità di traduzione per ogni gruppo di campi

I gruppi di campi ACF non si comportano tutti allo stesso modo durante la traduzione. ACFML offre tre modalità per ogni gruppo di campi, impostabili in ACF → Gruppi di campi nella sezione Configurazione multilingue:

Stessi campi in tutte le lingue

L’impostazione tipica per la maggior parte dei siti ACF. Traduci i valori dei campi in ogni lingua mantenendo invariata la struttura. La pagina Il nostro team è l’esempio classico. Il tuo team è lo stesso in ogni lingua, quindi il nome e la biografia di ogni membro del team vengono tradotti per ogni lingua, mentre la struttura dei campi rimane intatta. Inserisci il team nella lingua di origine, poi invia l’articolo per la traduzione tramite WPML → Traduzioni → Dashboard; i valori tradotti ritornano associati agli stessi campi.

Campi diversi nelle varie lingue

Usala quando ogni lingua mostra contenuti fondamentalmente diversi nello stesso gruppo di campi. Il caso classico è quello di un’azienda che gestisce eventi localizzati. La pagina Eventi in inglese mostra gli eventi per il pubblico inglese, la pagina in francese mostra gli eventi per il pubblico francese. Imposta il gruppo di campi su Campi diversi nelle varie lingue, poi apri l’articolo che vuoi localizzare → nel riquadro Lingue sulla destra, fai clic sull’icona con il segno più per la lingua di destinazione → si aprirà una bozza vuota con campi personalizzati vuoti → compila i valori specifici per la lingua e pubblica.

Modalità esperto

Usala quando hai bisogno di una combinazione: alcuni campi vengono tradotti per ogni lingua, altri rimangono uguali, altri vengono copiati una volta e poi differiscono. Scegli Modalità esperto nella configurazione del gruppo di campi e imposta la preferenza per ogni campo. L’esempio degli Eventi con comportamento misto: titolo e descrizione impostati su Traduci; prezzo, data e indirizzo impostati su Copia.

Preferenze di traduzione per ogni tipo di campo ACF

Ogni campo in un gruppo di campi ha una delle quattro preferenze di traduzione:

• Traduci. Il valore del campo viene tradotto per ogni lingua.
• Copia. Il valore del campo rimane sincronizzato in tutte le lingue; lo modifichi una volta e si propaga.
• Copia una volta. Il valore del campo fa da base per la traduzione, dopodiché ogni versione linguistica può essere modificata in modo indipendente.
• Non tradurre. Il campo viene ignorato nel processo di traduzione.

Quando scegli Stessi campi in tutte le lingue o Campi diversi nelle varie lingue, a ogni campo viene assegnata una preferenza predefinita sensata in base al tipo di campo. Le tabelle seguenti mostrano queste impostazioni predefinite. Usa Modalità esperto per sovrascriverle campo per campo, oppure usa il filtro acfml_field_group_mode_field_translation_preference per sovrascrivere l’impostazione predefinita per un tipo di campo a livello di intero sito (vedi Hook per sviluppatori per casi limite di seguito).

Ripetitore e contenuto flessibile: Copia o Copia una volta

Per i campi Ripetitore e Contenuto flessibile, puoi scegliere tra due comportamenti a livello di riga prima che entrino in gioco le preferenze dei sottocampi:

• Copia. Stesso layout e stesso numero di righe in ogni lingua. I traduttori vedono le stesse righe; i sottocampi vengono tradotti in base alle proprie preferenze.
• Copia una volta. Ogni lingua può avere un layout diverso e un numero di righe diverso dopo l’impostazione iniziale.

Scegli Copia quando la struttura è la stessa in tutte le lingue (nella maggior parte dei casi). Scegli Copia una volta quando le versioni linguistiche divergono strutturalmente (ad esempio, un elenco di eventi diverso per ogni lingua).

Campi di base

Campi di contenuto

Campi di scelta

Campi jQuery

Campi di layout

Campi relazionali

Impostare le preferenze per i campi registrati in PHP o JSON

I gruppi di campi ACF registrati in PHP (tramite acf_add_local_field_group()) o attraverso la funzionalità JSON locale di ACF non acquisiscono le preferenze di traduzione dall’interfaccia utente di amministrazione, perché non è l’area di amministrazione a gestirle. Imposta le preferenze nello stesso punto in cui registri i campi.

Per ogni campo nella definizione del gruppo di campi, aggiungi una chiave wpml_cf_preferences. Il valore è un numero intero che corrisponde alle quattro preferenze di traduzione: 0 per Non tradurre (WPML ignora il campo), 1 per Copia (il valore rimane sincronizzato in tutte le lingue), 2 per Traduci (il valore passa attraverso la traduzione) e 3 per Copia una volta (il valore viene copiato nelle nuove traduzioni, dopodiché ogni lingua può essere modificata in modo indipendente).

Un esempio minimo:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

Dopo aver definito i campi nel codice, sincronizza le preferenze in WPML in modo che l’area di amministrazione le riconosca:

1. Vai su ACF → Strumenti.
2. Scorri fino a Translate ACF Local JSON and PHP-Registered Fields.
3. In Sync Translation Preferences for Local Fields, scegli Sync once now e fai clic su Applica.

WPML legge le preferenze dalle tue definizioni PHP e le memorizza. La sincronizzazione viene eseguita una volta quando la attivi, non a ogni caricamento della pagina.

Se usi la funzionalità JSON locale di ACF per condividere i gruppi di campi tra i siti, ACFML scrive automaticamente le preferenze di traduzione nei file JSON. Esporta un file JSON da un sito, importalo su un altro e il sito di destinazione rileverà le preferenze non appena ACFML sarà attivo su entrambi i siti.

Tradurre le etichette dei campi ACF

Le etichette dei campi ACF sono i nomi che identificano ogni campo personalizzato nell’editor di WordPress e sul front-end (ad esempio, Numero di telefono, Indirizzo). Vengono tradotte separatamente dai valori dei campi e si trovano in WPML Traduzione stringhe, non nel lavoro di traduzione dell’articolo.

Per inviare le etichette dei campi per la traduzione:

1. Apri WPML → Traduzioni → Dashboard.
2. Espandi la sezione Gruppo di campi ACF.
3. Seleziona l’elemento Etichette del gruppo di campi per il gruppo di campi che vuoi tradurre.
4. Scegli un metodo di traduzione (PTC, il tuo traduttore o Traduco io) e invia.

Le etichette tradotte appaiono automaticamente sul front-end una volta completata la traduzione.

Tradurre le scelte dei campi ACF

I campi di scelta (Seleziona, Casella di controllo, Pulsante di opzione, Gruppo di pulsanti) hanno le proprie etichette di opzione (ad esempio, Piccolo / Medio / Grande). Anche queste si trovano insieme alle etichette dei campi piuttosto che all’interno della traduzione dell’articolo. Inviale nello stesso modo:

1. Apri WPML → Traduzioni → Dashboard.
2. Espandi la sezione Gruppo di campi ACF.
3. Seleziona il gruppo di campi di cui vuoi tradurre i valori di scelta.
4. Scegli un metodo di traduzione e invia.

Tradurre le pagine delle opzioni ACF

Le pagine delle opzioni ACF (schermate di impostazioni globali come Dettagli di contatto, Impostazioni dell’intestazione, Link del footer) si traducono come un tipo di oggetto a sé stante, separatamente dagli articoli:

1. Apri WPML → Traduzioni → Dashboard.
2. Espandi la sezione Opzioni ACF.
3. Seleziona la pagina delle opzioni che vuoi tradurre.
4. Scegli un metodo di traduzione e invia.

I valori della pagina delle opzioni di ogni lingua appaiono automaticamente quando ACF legge l’opzione nel contesto di quella lingua.

Errori comuni

• Le etichette dei campi sembrano non tradotte. Si trovano in Traduzione stringhe, non nella traduzione dell’articolo. Invia l’elemento Etichette del gruppo di campi del gruppo di campi dalla Dashboard (vedi Tradurre le etichette dei campi ACF sopra).
• I valori di scelta sembrano non tradotti. Stessa situazione. Invia il gruppo di campi dalla sezione Gruppo di campi ACF della Dashboard, in modo che i valori delle opzioni vengano inclusi.
• Le righe del ripetitore non sono più sincronizzate. Il campo è probabilmente impostato su Copia una volta, mentre Copia manterrebbe le righe allineate. Apri il gruppo di campi → cambia il comportamento del campo Ripetitore in Copia.
• La logica condizionale si comporta in modo imprevisto. Quando il campo di controllo è impostato su Copia o Non tradurre, il comportamento condizionale segue il valore della lingua di origine in tutte le traduzioni. Imposta il campo di controllo su Traduci se il suo valore deve variare in base alla lingua.
• I campi locali (registrati in PHP) ignorano le preferenze di traduzione impostate nell’area di amministrazione. Imposta la chiave wpml_cf_preferences nella definizione stessa del gruppo di campi e sincronizza da ACF → Strumenti. La procedura si trova in Impostare le preferenze per i campi registrati in PHP o JSON sopra. ACFML 2.2.0 (febbraio 2026) ha aggiunto il supporto completo per i campi locali; le versioni precedenti presentavano limitazioni in questo ambito.

Hook per sviluppatori per casi limite

Per il controllo programmatico (escludere campi specifici dalla traduzione, sovrascrivere la preferenza predefinita per un tipo di campo a livello di intero sito, nascondere le annotazioni ai traduttori o escludere le stringhe del gruppo di campi dai lavori di traduzione degli articoli), ACFML espone due filtri e quattro costanti. Il riferimento completo con esempi di codice si trova in Riferimento per hook e costanti di ACFML.