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 e Rendere traducibili i blocchi Gutenberg personalizzati.

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:

wp bs wpml config > wp-content/themes/my-theme/wpml-config.xml

Oppure lasciate che sia il comando a scrivere il file:

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:

{
  "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:

<wpml-config>
	<gutenberg-blocks>
		<!-- blockstudio:start -->
		<!-- Generated by wp bs wpml config. Run it again after changing block fields; edits between the markers are replaced. -->
		<gutenberg-block type="my-theme/cards" translate="1" label="Cards">
			<key name="blockstudio">
				<key name="attributes">
					<key name="heading" label="Heading" />
					<key name="gallery">
						<key name="*" type="post-ids" sub-type="attachment" />
					</key>
					<key name="cards">
						<key name="*">
							<key name="title" label="Cards: Title" />
							<key name="image" type="post-ids" sub-type="attachment" />
							<key name="link">
								<key name="title" label="Cards: Button: Link text" />
								<key name="url" type="link" label="Cards: Button: URL" />
							</key>
						</key>
					</key>
				</key>
			</key>
		</gutenberg-block>
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

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. 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 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.

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 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:

{
  "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:

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.

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:

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 <!-- blockstudio:start --> e <!-- blockstudio:end -->, lasciando inalterate le altre sezioni e le voci degli altri blocchi:

<wpml-config>
	<custom-types>
		<custom-type translate="1">book</custom-type>
	</custom-types>
	<gutenberg-blocks>
		<gutenberg-block type="my-plugin/map" translate="1">
			<key name="caption" />
		</gutenberg-block>
		<!-- blockstudio:start -->
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

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. WPML individua le immagini nei tag <img> 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, 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:

add_filter(
	'wpml_ids_of_media_used_in_post',
	function ( $ids ) {
		return array_values( array_diff( $ids, array( 42 ) ) );
	},
	20
);