# WPML
WPML traduce gli attributi di un blocco personalizzato solo nella misura in cui sono dichiarati in un file di configurazione linguistica. Blockstudio memorizza ogni valore di campo nel commento del blocco sotto `blockstudio.attributes`, quindi ogni blocco necessita di una voce che indichi a WPML i suoi campi di testo e gli ID degli allegati. Il comando `wp bs wpml config` scrive queste voci per ogni blocco registrato.
## Perché i blocchi hanno bisogno di una configurazione
WPML legge la configurazione da un file chiamato `wpml-config.xml` nella cartella principale del tema attivo e di ogni plugin attivo. Per un plugin must-use costituito da un singolo file, la cartella ha il nome del file senza `.php`. Consultate [File di configurazione della lingua](https://wpml.org/documentation/support/language-configuration-files/) e [Rendere traducibili i blocchi Gutenberg personalizzati](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).
Un blocco senza una voce viene lasciato al rilevamento automatico delle stringhe di WPML, che rende disponibili per la traduzione tutti gli attributi stringa del blocco. Nel caso di un blocco Blockstudio che include valori di selezione, riferimenti a file, URL e classi CSS, i traduttori vedono questi valori tecnici accanto al testo effettivo; tradurre un valore di selezione o una classe può compromettere il blocco.
## Generare la configurazione
Stampate la configurazione e salvatela nella cartella principale del tema o del plugin che include i blocchi:
```bash
wp bs wpml config > wp-content/themes/my-theme/wpml-config.xml
```
Oppure lasciate che sia il comando a scrivere il file:
```bash
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml
```
Un blocco con un campo di testo, un'immagine, un link e un ripetitore:
```json title="block.json"
{
"name": "my-theme/cards",
"title": "Cards",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true },
{
"id": "style",
"type": "select",
"label": "Style",
"options": [
{ "value": "light", "label": "Light" },
{ "value": "dark", "label": "Dark" }
]
},
{
"id": "cards",
"type": "repeater",
"label": "Cards",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Image" },
{ "id": "link", "type": "link", "label": "Button" }
]
}
]
}
}
```
diventa:
```xml title="wpml-config.xml"
```
Il valore `style` non è dichiarato, quindi WPML lo copia senza modificarlo nella traduzione. Anche gli ID `gallery` e `image` vengono copiati, e WPML sostituisce ciascuno con l'allegato nella lingua della pagina quando il blocco viene visualizzato, così un'immagine tradotta può avere il proprio testo alternativo. Consultate «Conversione automatica degli ID nei blocchi» in [Rendere traducibili i blocchi Gutenberg personalizzati](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).
Se un allegato non ha una traduzione, WPML mantiene l'ID originale.
## Cosa viene dichiarato
Il comando legge i blocchi registrati dopo l'espansione dei campi `custom/` e dei campi dei blocchi, e l'applicazione di override e filtri degli attributi. Sono inclusi i campi che le [estensioni](https://blockstudio.dev/it/docs/extensions/) aggiungono a un blocco Blockstudio. I campi aggiunti dalle estensioni ai blocchi core o ai blocchi di altri plugin non sono inclusi, perché questi blocchi ottengono la configurazione da WPML o dal proprio plugin.
| Campo | Dichiarazione |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Testo traducibile. |
| `link` | `title` come testo e `url` con `type="link"`, così WPML sostituisce un link con la relativa traduzione, se disponibile. |
| `files` | L'ID dell'allegato archiviato con `type="post-ids"` e `sub-type="attachment"`. Con `multiple`, un livello denominato `*` per l'elenco, che corrisponde anche all'ID singolo memorizzato dal campo quando viene selezionato un solo file. |
| `repeater` | Un livello denominato `*` che corrisponde a ogni riga, con le dichiarazioni dei campi della riga. I ripetitori annidati funzionano allo stesso modo. |
| `group` con un `id` | I campi del gruppo, con l'ID del gruppo come prefisso della chiave (`cta_text` per il campo `text` nel gruppo `cta`). |
| `group` senza un `id`, `tabs` | I campi, senza un livello dedicato. |
| Tipo di campo personalizzato registrato con `translate` impostato su `true` | Testo traducibile, come un campo `text`. |
| Ogni altro tipo integrato | Non dichiarato. WPML copia il valore senza modificarlo. |
Un blocco senza un campo di testo dichiarato riceve `translate="0"`. WPML copia quindi tutti i suoi valori e non ne rende disponibile nessuno per la traduzione. I suoi campi `files` vengono comunque dichiarati nella voce, perché WPML converte gli ID degli allegati indipendentemente da ciò che indica `translate`. I blocchi interni vengono tradotti come di consueto.
Non dichiarati:
- I campi con `hidden`, perché i loro valori non vengono scritti dagli editor.
- I campi con `"translate": false`, vedi sotto.
- I campi dei [tipi di campo personalizzati](https://blockstudio.dev/it/docs/blocks/attributes/custom-field-types/) che non sono registrati con `translate` impostato su `true`. Il comando stampa un avviso per ciascuno, perché solo il tipo di campo sa se il suo valore contiene testo. Un `"translate": false` esplicito su un campo sopprime anche questo avviso per quel campo. Vedi sotto.
- Gli attributi che un blocco dichiara nel proprio `attributes` nativo anziché come campi Blockstudio.
- Le chiavi di archiviazione i cui campi hanno tipi diversi, vedi sotto.
Ogni campo di testo viene dichiarato, anche se contiene un valore tecnico come una classe CSS, a meno che non imposti `"translate": false`.
### Escludere un campo
Un campo di testo può contenere un valore che deve essere uguale in tutte le lingue: un nome utente, un indirizzo email, un'ancora, una classe CSS. WPML lo rende disponibile per la traduzione come qualsiasi altro testo, e una traduzione può compromettere il blocco. Impostate `translate` su `false` per escludere il campo dalla configurazione, così WPML ne copia il valore nella traduzione senza modificarlo:
```json title="block.json"
{
"id": "account",
"type": "text",
"label": "Account handle",
"translate": false
}
```
Su un `group`, un `tabs` o un `repeater`, `"translate": false` si applica a tutti i campi interni, compresi i contenitori annidati. Un elemento figlio non può sovrascrivere un contenitore escluso impostando `"translate": true`. Su un campo `files`, `false` esclude anche gli ID degli allegati, così la traduzione mantiene gli allegati originali.
Omettere `translate` o impostarlo su `true` mantiene il comportamento esistente: decide il tipo di campo. Non rende traducibili i campi nascosti né tipi di valore come `select`. L'opzione si applica ai campi dei blocchi e delle estensioni, non nasconde né disattiva i relativi controlli nell'editor e non modifica i valori memorizzati. Eseguite di nuovo `wp bs wpml config` dopo aver cambiato l'impostazione e aggiornate il vostro `wpml-config.xml` con la configurazione generata.
Il `label` di ogni chiave è l'etichetta del campo, preceduta dalle etichette dei ripetitori e dei gruppi contenitori provvisti di ID. WPML lo mostra come nome del campo nell'editor delle traduzioni. Le due chiavi di un campo `link` aggiungono `Link text` e `URL` all'etichetta. Questi suffissi vengono tradotti nella lingua del sito, quindi eseguite il comando con la lingua usata dai traduttori.
### Tipi di campo personalizzati
Un tipo di campo che memorizza una semplice stringa di testo lo dichiara al momento della registrazione. Impostate `translate` su `true` nella definizione; per farlo, `attribute` deve essere `string`:
```php title="functions.php"
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
```
Il comando dichiara quindi traducibile ogni campo di quel tipo. Un campo può comunque impostare `"translate": false` per escludersi. Senza questa opzione, i campi del tipo vengono esclusi e segnalati, come prima.
### Modificare le etichette
Le etichette dei campi sono pensate per l'editor dei blocchi e possono contenere suggerimenti come "Immagine (facoltativa)" che non hanno alcun significato nell'editor di traduzione. Il filtro `blockstudio/wpml/config/label` riceve ogni etichetta prima che venga scritta, insieme al contesto della chiave:
- `block`: il nome del blocco.
- `path`: il percorso di archiviazione del campo sotto `blockstudio.attributes`, con un livello `*` per le righe di ogni ripetitore, per esempio `cards/*/link`.
- `field`: la definizione del campo.
- `parents`: le etichette dei ripetitori e dei gruppi contenitori con un ID.
- `part`: `text` per un campo di testo, `title` o `url` per le due chiavi di un campo link.
```php title="functions.php"
add_filter('blockstudio/wpml/config/label', function ($label, $context) {
return str_replace(' (optional)', '', $label);
}, 10, 2);
```
Restituite una stringa vuota per escludere l'etichetta di una chiave, così WPML mostra invece l'etichetta del blocco. Un valore restituito che non sia una stringa mantiene l'etichetta originale. Eseguite di nuovo il comando dopo aver modificato il filtro.
### Campi con la stessa chiave di archiviazione
Due campi possono finire per avere la stessa chiave di archiviazione, per esempio un campo del blocco e un campo di estensione con lo stesso `id`, oppure il campo `text` in un gruppo con ID `cta` e un campo con ID `cta_text`. Il comando dichiara una chiave di questo tipo solo quando è chiaro cosa vi viene archiviato:
- Tra i campi di un blocco, fuori dalle righe dei ripetitori, Blockstudio registra un attributo per ogni chiave di archiviazione; di conseguenza, un campo successivo sostituisce quello precedente, indipendentemente dal tipo. Lo stesso vale per i campi delle estensioni di un blocco: un campo successivo, o il campo di un'estensione registrata più tardi, sostituisce quello precedente.
- Un campo del blocco e un campo di estensione con la stessa chiave restano entrambi attivi. Il modello del blocco riceve il valore secondo la definizione del campo del blocco, mentre l'estensione viene applicata con il proprio campo. La chiave viene dichiarata una sola volta quando entrambi i campi richiedono la stessa dichiarazione: sono entrambi campi di testo (`text`, `textarea`, `richtext` o `wysiwyg`), sono entrambi link, sono entrambi campi `files` (con `multiple` su uno dei due, la chiave riceve il livello `*`) oppure nessuno dei due viene dichiarato, come nel caso di un `select` e un `number`. Due ripetitori vengono confrontati campo per campo nelle rispettive righe. L'etichetta proviene dal campo del blocco.
- Anche due campi con lo stesso `id` nelle righe di un ripetitore restano entrambi attivi e vengono confrontati allo stesso modo.
Se i tipi differiscono, per esempio un campo `text` nel blocco e un campo `select` in un'estensione, il valore archiviato è testo oppure un'opzione di selezione, a seconda del controllo che l'ha scritto. Il comando non dichiara la chiave e mostra un avviso:
```bash
Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)
```
Rinominate uno dei campi oppure assegnate a entrambi lo stesso tipo affinché la chiave venga dichiarata.
## Mantenere aggiornata la configurazione
Eseguite di nuovo il comando dopo aver aggiunto, rimosso o rinominato dei campi e distribuite il file aggiornato insieme al tema o al plugin. Rigenerate le configurazioni create prima di 7.7.5 per includere le dichiarazioni degli ID degli allegati. Nei contenuti esistenti, i nuovi campi diventano disponibili per la traduzione quando viene aggiornato l'originale, come descritto nella guida WPML qui sopra.
Con `--file`, il comando crea un file se non esiste. In un file esistente, sostituisce solo il testo tra `` e ``, lasciando inalterate le altre sezioni e le voci degli altri blocchi:
```xml title="wpml-config.xml"
book
```
Per usare un file esistente che non contiene ancora marcatori, aggiungete una volta le due righe dei marcatori all'interno del suo elemento `gutenberg-blocks` oppure aggiungete un elemento `gutenberg-blocks` con i marcatori, se il file non ne contiene. Senza i marcatori, o se il risultato non fosse una configurazione valida, il comando lascia il file invariato e termina con un errore.
Le voci per i blocchi Blockstudio inserite manualmente, come le voci `translate="0"` che nascondono valori tecnici, non servono più quando la sezione generata copre il blocco. Il comando avvisa per ogni blocco dichiarato più di una volta, così è possibile rimuovere queste voci.
## Testi delle immagini nei lavori di traduzione
WPML inserisce i testi delle immagini usate da una pagina nel lavoro di traduzione della pagina: titolo, testo alternativo, didascalia e descrizione. Una volta completato il lavoro, WPML scrive i testi tradotti nell'allegato della lingua di destinazione e crea quell'allegato se non esiste ancora. Consultate [Come tradurre i media](https://wpml.org/documentation/translating-your-contents/media/).
WPML individua le immagini nei tag `![]()
` del contenuto, nelle gallerie, nell'immagine in evidenza e nei blocchi che riconosce. Un blocco Blockstudio archivia gli ID degli allegati nel commento del blocco, quindi WPML non ne individua nessuno.
Quando WPML è attivo, Blockstudio aggiunge alle immagini individuate WPML gli allegati archiviati dai suoi campi nei blocchi di una pagina:
- Campi `files`, compresi quelli nascosti, e campi `attributes` con `media`: gli stessi campi che l'editor dei blocchi carica come media.
- Campi in gruppi, schede, righe di ripetitori e blocchi interni.
- Campi delle [estensioni](https://blockstudio.dev/it/docs/extensions/), anche nei blocchi principali e in quelli di altri plugin, perché i loro valori sono archiviati negli attributi del blocco esteso.
I valori che non corrispondono all'ID di un allegato vengono esclusi. Non occorre configurare nulla e `wpml-config.xml` non è coinvolto. Senza WPML, non viene eseguita alcuna scansione per i lavori di traduzione e la classe di integrazione dei media non viene caricata.
Questo processo è distinto dalla conversione degli ID degli allegati: il file XML generato indica a WPML quale allegato tradotto mostrare, mentre questa integrazione indica quali testi degli allegati includere in un lavoro di traduzione. I riferimenti a stringhe e gli ID di contenuti diversi dagli allegati non vengono aggiunti ai lavori di traduzione dei media. Nei blocchi Blockstudio, i valori dei campi annidati salvati hanno la precedenza su quelli di primo livello, come durante il rendering.
I testi fanno parte del lavoro solo se è attiva una delle opzioni per i testi delle immagini in WPML > Settings > Media Translation: "Automatically detect best options for translating image texts" oppure "Translate Media Library texts when translating content", come per le immagini nei blocchi principali.
Blockstudio segnala le immagini tramite il filtro
`wpml_ids_of_media_used_in_post`, che WPML applica ai contenuti multimediali di un post in
`PostWithMediaFiles`. Per escludere un'immagine dai processi, rimuovete il suo ID in una
callback sullo stesso filtro con priorità superiore a 10:
```php
add_filter(
'wpml_ids_of_media_used_in_post',
function ( $ids ) {
return array_values( array_diff( $ids, array( 42 ) ) );
},
20
);
```