Come tradurre i campi personalizzati di ACF in WordPress: gruppi di campi, repeater, 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 singolo campo in un secondo momento, quindi l’ordine delle operazioni non ha importanza. Configura i gruppi di campi, poi torna ad ACFML.

Scegli un’opzione di traduzione per ogni gruppo di campi

I gruppi di campi di ACF non si comportano tutti allo stesso modo durante la traduzione. ACFML offre tre opzioni di traduzione per ogni gruppo di campi. Per sceglierne una:

1. Vai su ACF → Gruppi di campi e modifica il gruppo di campi.
2. Nella sezione Multilingual Setup, alla voce Select a translation option for this field group, fai clic su Choose per l’opzione che desideri.
3. Salva il gruppo di campi.

ACFML contrassegna l’opzione che suggerisce per il tuo sito come recommended for this site. Per scegliere un’altra opzione in seguito, fai clic su Change option. Le versioni precedenti di ACFML chiamano le prime due opzioni Same fields across languages e Different fields across languages.

Stesso contenuto in ogni lingua, tradotto

L’impostazione tipica per la maggior parte dei siti ACF. I visitatori in ogni lingua vedono le stesse pagine, nella propria lingua. Il testo viene tradotto, mentre il layout e le impostazioni rimangono invariati. 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 e la struttura dei campi rimane la stessa. Inserisci il team nella lingua predefinita, quindi invii l’articolo per la traduzione da WPML → Traduzioni → Dashboard. I valori tradotti ritornano negli stessi campi. Questa opzione funziona con la traduzione automatica e con Traduci tutto.

Ogni lingua ha il suo contenuto

Usa questa opzione quando ogni lingua mostra contenuti diversi nello stesso gruppo di campi. L’esempio classico è un’azienda che organizza eventi locali. La pagina Eventi in inglese mostra gli eventi per il pubblico inglese, mentre la pagina in francese mostra gli eventi per il pubblico francese. I campi iniziano come una copia dell’originale. Successivamente, ogni lingua mantiene i propri valori. Modifichi ogni lingua nell’editor di WordPress: apri l’articolo, fai clic sull’icona a forma di più per la lingua di destinazione nel riquadro Lingua, compili i valori per quella lingua e pubblichi. In seguito WPML non sincronizza le versioni linguistiche e la traduzione automatica non viene applicata.

Esperto

Usa questa opzione quando hai bisogno di un mix: alcuni campi vengono tradotti, altri rimangono uguali e altri ancora vengono copiati una volta e poi modificati in ogni lingua. Scegli Esperto e imposta manualmente la preferenza di traduzione di ogni campo. Nell’esempio degli Eventi, il titolo e la descrizione usano Traduci, mentre il prezzo, la data e l’indirizzo usano Copia. ACFML non consiglia questa opzione per i nuovi gruppi di campi. Un gruppo di campi definito in PHP o JSON locale può non avere alcuna opzione di traduzione. In tal caso, utilizza Esperto solo se il gruppo di campi esiste prima dell’aggiornamento del tuo sito a WPML 5.2.

Preferenze di traduzione per ogni tipo di campo ACF

Ogni campo che memorizza un valore ha una delle quattro preferenze di traduzione:

• Traduci. I visitatori vedono il valore nella propria lingua. WPML lo compila con la traduzione. Lo modifichi nell’editor di traduzione.
• Copia. I visitatori in ogni lingua vedono esattamente ciò che mostra l’originale. Il campo è bloccato nelle altre lingue.
• Copia una volta. Il valore inizia come una copia dell’originale. Successivamente, lo modifichi manualmente in ogni lingua. Se svuoti il campo in una traduzione, rimane vuoto. WPML non vi copia nuovamente il valore originale.
• Non tradurre. Le traduzioni iniziano senza questo valore. Puoi compilarlo manualmente in ogni lingua.

Quando scegli Stesso contenuto in ogni lingua, tradotto o Ogni lingua ha il suo contenuto, ACFML assegna a ogni campo la preferenza consigliata per il suo tipo di campo. Le tabelle seguenti mostrano queste preferenze consigliate. Per impostare una preferenza diversa per un singolo campo, usa Esperto. Per modificare la preferenza consigliata di un tipo di campo sull’intero sito, usa il filtro acfml_field_group_mode_field_translation_preference (vedi Developer Hooks for Edge Cases di seguito).

I campi Tab, Accordion, Message e Separator non memorizzano un valore, quindi non hanno alcuna preferenza di traduzione. Un tipo di campo che non è presente nelle tabelle, ad esempio un tipo di campo di un altro plugin, ottiene Copia con entrambe le opzioni di traduzione.

Campi Repeater, Flexible Content, Group e Clone

Questi campi contengono altri campi. La preferenza consigliata per il campo contenitore è Copia o Copia una volta. ACFML non offre Traduci per il campo contenitore stesso. Ogni sottocampo ha la propria preferenza di traduzione.

Con Stesso contenuto in ogni lingua, tradotto, le righe dei campi Repeater e Flexible Content mantengono lo stesso ordine della lingua predefinita. Con Esperto, o quando un articolo usa gruppi di campi con opzioni diverse, l’editor dell’articolo mostra un riquadro ACFML Synchronise translations. Questo appare sull’articolo originale quando l’articolo ha delle traduzioni e un campo Repeater o Flexible Content. Seleziona Keep repeater and flexible sub-fields in the same order as the default language per mantenere le righe allineate in tutte le lingue.

Campi di base

Campi di contenuto

Campi di scelta

Campi jQuery

Campi di layout

Campi relazionali

Per un campo Link, la traduzione copre il testo del link e l’URL. Quando l’URL punta a una pagina del tuo sito e non lo modifichi, WPML mostra la pagina nella lingua del visitatore.

Campi URL e Link

A partire da ACFML 5.0, i campi URL e Link utilizzano la preferenza Traduci per impostazione predefinita.

Relazioni bidirezionali

A partire da ACF 6.2, i campi Relazione, Oggetto articolo, Tassonomia e Utente possono essere bidirezionali. Quando selezioni una destinazione nel campo, ACF aggiunge il tuo articolo al campo accoppiato della destinazione. Ad esempio, il libro Dune imposta il suo campo Autore su Frank Herbert. ACF aggiunge quindi Dune al campo Libri di Frank Herbert.

ACFML mantiene la coppia in ogni lingua:

• Quando WPML copia il campo in una traduzione, ACFML fa puntare il campo alla destinazione nella stessa lingua. Successivamente, ACFML aggiunge la traduzione al campo accoppiato di quella destinazione. Il Dune spagnolo mostra il Frank Herbert spagnolo, e il Frank Herbert spagnolo elenca il Dune spagnolo.
• Quando il campo utilizza Copia e cambi la destinazione nell’articolo originale, WPML aggiorna la traduzione. ACFML aggiunge la traduzione alla nuova destinazione in quella lingua e la rimuove dalla vecchia destinazione.
• ACFML modifica solo le destinazioni nella lingua della traduzione. Gli articoli nella lingua originale mantengono la propria coppia.
• Quando la destinazione non ha ancora una traduzione, la traduzione punta alla destinazione originale e ACFML non modifica la destinazione originale. Quando in seguito traduci la destinazione, ACFML fa puntare il campo alla nuova traduzione e aggiunge l’articolo al suo campo accoppiato. Il campo elenca la destinazione una sola volta.
• Gli utenti non hanno traduzioni, quindi ACFML non aggiunge traduzioni al campo accoppiato di un utente. Quel campo mantiene l’articolo originale. In un’altra lingua, ACFML mostra la traduzione di quell’articolo, a meno che il campo non utilizzi Copia.

Questo funziona per le preferenze Copia e Copia una volta, che sono le preferenze consigliate per questi tipi di campo. Funziona anche quando duplichi un articolo con WPML.

Traduci i blocchi ACF

Per impostazione predefinita, i blocchi ACF salvano i valori dei propri campi all’interno del blocco, nel contenuto dell’articolo, non come campi personalizzati. ACFML invia questi valori per la traduzione insieme al resto dell’articolo, nello stesso lavoro di traduzione.

• Il blocco utilizza l’opzione di traduzione e le preferenze di campo del Gruppo di campi la cui regola di posizione è questo blocco.
• ACFML invia solo i campi che utilizzano Traduci. I campi che utilizzano Copia, Copia una volta o Non tradurre mantengono il valore dal blocco originale.
• Anche i campi Repeater e Flexible Content all’interno di un blocco vengono tradotti, anche quando sono annidati. Ogni sottocampo utilizza la propria preferenza di traduzione.
• Un blocco con "usePostMeta": true nella sezione acf del suo block.json salva i suoi valori come campi personalizzati dell’articolo, non nel blocco. Questi valori vengono tradotti come qualsiasi altro campo personalizzato dell’articolo, con l’opzione di traduzione e le preferenze di campo del Gruppo di campi.
• Quando cambi una preferenza di traduzione in un Gruppo di campi che utilizzi sui blocchi, WPML ti chiede se vuoi aggiornare le traduzioni esistenti. Se confermi, WPML contrassegna le traduzioni di questi articoli come da aggiornare. Inviali nuovamente per la traduzione per applicare la modifica. Una modifica a Non tradurre non li contrassegna.

Campi dichiarati in block.json

A partire da ACF 6.8.1, un blocco può dichiarare i suoi campi nel proprio file block.json, in acf.fields. ACF crea un Gruppo di campi per questi campi e non puoi modificare questo Gruppo di campi nell’area di amministrazione. ACFML gli assegna l’opzione Stesso contenuto in ogni lingua, tradotto e la preferenza consigliata per ogni tipo di campo, come un Gruppo di campi registrato in PHP.

Per utilizzare un’altra opzione per l’intero gruppo, aggiungi acfml_field_group_mode alla sezione acf di block.json, oppure a acf_register_block_type(). I valori accettati sono translation (Stesso contenuto in ogni lingua, tradotto), localization (Ogni lingua ha il proprio contenuto) e advanced (Esperto). ACFML ignora qualsiasi altro valore.

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

Per impostare la preferenza di un campo, aggiungi wpml_cf_preferences a quel campo. ACFML mantiene questa preferenza con ogni opzione. Con Esperto, solo i campi che dichiarano wpml_cf_preferences ottengono una preferenza.

Quando block.json non specifica un’opzione, ACFML memorizza l’opzione che assegna al gruppo la prima volta che lo rileva e la mantiene in seguito. Sui siti che utilizzavano questi blocchi con una versione precedente di ACFML, l’opzione memorizzata è Esperto.

Impostare le preferenze per i campi registrati in PHP o JSON

I gruppi di campi ACF registrati in PHP (con acf_add_local_field_group()) o tramite la funzionalità Local JSON di ACF non prendono le preferenze di traduzione dalle schermate dell’area di amministrazione, perché quest’ultima non li gestisce. Imposta le preferenze nello stesso posto in cui registri i campi.

Per impostare l’opzione di traduzione del gruppo di campi, aggiungi la chiave acfml_field_group_mode alla definizione, con translation, localization o advanced (Esperto). Quando la definizione non imposta alcuna opzione di traduzione, ACFML assegna al gruppo di campi l’opzione Stesso contenuto in ogni lingua, tradotto la prima volta che lo rileva. ACFML memorizza questa opzione e la mantiene in seguito. I gruppi di campi esistenti prima dell’aggiornamento del tuo sito a WPML 5.2 mantengono Esperto.

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 tra le lingue), 2 per Traduci (il valore viene tradotto) 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 Traduci i campi ACF Local JSON e registrati in PHP.
3. In Sincronizza le preferenze di traduzione per i campi locali, seleziona Sincronizza ora una volta e fai clic su Applica.

WPML legge le preferenze dalle definizioni dei tuoi campi e le memorizza. Sincronizza ora una volta viene eseguito una sola volta. Se modifichi spesso le definizioni, seleziona invece Sincronizza a ogni richiesta (potrebbe influire sulle prestazioni). Questa opzione esegue la sincronizzazione a ogni richiesta dell’area di amministrazione.

Se utilizzi la funzionalità Local JSON 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 gruppi di campi che ACF crea con il comando WP-CLI wp acf json import, o tramite la sua API Abilities per gli strumenti IA, vengono memorizzati nel database. ACFML assegna loro l’opzione Stesso contenuto in ogni lingua, tradotto e la preferenza consigliata per ogni tipo di campo. Quando il JSON importato ha già una chiave acfml_field_group_mode, ACFML utilizza invece quell’opzione.

Gruppi di campi nei file Local JSON

ACF carica i gruppi di campi della cartella acf-json molto presto in ogni richiesta. A partire da WPML 5.2, ACFML legge questi gruppi di campi nello stesso momento. Quindi, quando sincronizzi le preferenze di traduzione, la sincronizzazione copre anche i gruppi di campi JSON. WPML utilizza poi le preferenze nei file JSON.

Nel file JSON, aggiungi wpml_cf_preferences a ogni campo, con gli stessi valori del PHP. Questa chiave imposta la preferenza di ogni campo, indipendentemente dall’opzione di traduzione del gruppo di campi. L’esempio utilizza Esperto:

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

Per inviare a WPML le preferenze e le etichette dei gruppi di campi JSON:

1. Vai su ACF → Strumenti.
2. Scorri fino a Traduci i campi ACF Local JSON e registrati in PHP.
3. In Sincronizza le preferenze di traduzione per i campi locali, seleziona Sincronizza ora una volta o Sincronizza a ogni richiesta (potrebbe influire sulle prestazioni).
4. In Registra le etichette per la traduzione, seleziona Registra le etichette ora.
5. Fai clic su Applica.

Per verificare il risultato, vai su WPML → Impostazioni e trova i campi in Traduzione dei campi personalizzati. Ogni campo mostra la preferenza dal file JSON. ACFML registra anche le etichette dei gruppi di campi, dei tipi di post, delle tassonomie e delle pagine delle opzioni che esistono solo nel codice: nella cartella acf-json o registrati in PHP. Traducili come le etichette di qualsiasi altro gruppo di campi (vedi Traduci le etichette dei campi ACF di seguito).

Traduci 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 es., Numero di telefono, Indirizzo). Si traducono 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 di traduzione.
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.

Smetti di tradurre le etichette dei campi

Per impostazione predefinita, il lavoro di traduzione di un articolo non include le etichette dei campi. Le traduci solo quando invii l’elemento Field Group Labels dalla Bacheca. Se non lo invii, ACF mostra le etichette originali. Per mostrare le etichette originali anche quando esistono le traduzioni, usa il filtro acfml_should_translate_acf_entity e restituisci false per i campi o i gruppi di campi che vuoi saltare. Il riferimento per gli hook e le costanti di ACFML contiene un esempio.

Traduci le scelte dei campi ACF

I campi di scelta (Select, Checkbox, Radio Button, Button Group) hanno le proprie etichette per le opzioni (ad es., Small / Medium / Large). Anche queste si trovano insieme alle etichette dei campi anziché all’interno della traduzione dell’articolo. Inviale nello stesso modo:

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

Traduci le pagine delle opzioni di ACF

Le pagine delle opzioni di ACF (schermate di impostazioni globali come Contact details, Header settings, Footer links) si traducono come un tipo di oggetto a sé stante, separatamente dagli articoli:

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

I valori della pagina delle opzioni di ciascuna lingua vengono visualizzati automaticamente quando ACF legge l’opzione nel contesto di quella lingua.

L’opzione di traduzione del gruppo di campi sulla pagina delle opzioni decide cosa succede a ciascun campo:

• I campi che usano Traduci finiscono nell’elemento ACF Options che invii dalla Dashboard di traduzione. Quando la traduzione è completata, ACFML scrive i valori nella pagina delle opzioni di quella lingua. I campi Repeater e Flexible Content ottengono le stesse righe dell’originale.
• I campi che usano Copia ottengono il valore dell’originale in ogni lingua. Quando salvi l’originale, ACFML aggiorna le altre lingue.
• I campi che usano Copia una volta iniziano come una copia dell’originale. Successivamente, li modifichi sulla pagina delle opzioni di ciascuna lingua.

Usa Each language has its own content quando le opzioni differiscono in base alla lingua. Ad esempio, una pagina delle opzioni elenca tre agenti di vendita in inglese e due in spagnolo. Per scegliere l’opzione, modifica il gruppo di campi, come per qualsiasi altro gruppo di campi.

Per modificare una traduzione completata, vai su WPML → Traduzioni → Lavori di traduzione e fai clic su Modifica sul lavoro ACF Options. Puoi anche modificare i valori tradotti in WPML → Traduzione stringhe. Quando salvi una traduzione lì, ACFML la scrive nella pagina delle opzioni di quella lingua.

Quando cambi la lingua predefinita del sito, i valori esistenti della pagina delle opzioni rimangono nella lingua in cui li hai scritti. ACF legge gli stessi valori di prima della modifica.

Nel codice, get_field( 'my_field', 'option' ) restituisce il valore della lingua corrente. Dopo do_action( 'wpml_switch_language', 'fr' ), restituisce il valore in francese. Questo funziona anche per le pagine delle opzioni con un post_id personalizzato.

Problemi comuni

• Le etichette dei campi sembrano non tradotte. Si trovano in Traduzione stringhe, non nella traduzione dell’articolo. Invia l’elemento Field Group Labels del gruppo di campi dalla Bacheca (vedi Traduci le etichette dei campi ACF sopra).
• I valori di scelta sembrano non tradotti. Stesso principio. Invia il gruppo di campi dalla sezione ACF Field Group della Bacheca in modo che i valori delle opzioni vengano inclusi.
• Le righe del Repeater non sono sincronizzate. Probabilmente il gruppo di campi usa Expert. Modifica l’articolo originale, seleziona Keep repeater and flexible sub-fields in the same order as the default language nel riquadro ACFML Synchronise translations e aggiorna l’articolo. Oppure passa il gruppo di campi a Same content in every language, translated.
• 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 differire per ogni 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.

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 sito, nascondere le annotazioni ai traduttori o escludere le stringhe del gruppo di campi dai lavori di traduzione degli articoli), ACFML dispone di due filtri e quattro costanti. Il riferimento completo con esempi di codice si trova in Riferimento per gli hook e le costanti di ACFML.