WPML

WPML vertaalt de attributen van een aangepast blok alleen voor zover een taalconfiguratiebestand ze declareert. Blockstudio slaat elke veldwaarde op in het blokcommentaar onder blockstudio.attributes, dus elk blok heeft een vermelding nodig die WPML naar de tekstvelden en bijbehorende bijlage-ID’s verwijst. De opdracht wp bs wpml config schrijft deze vermeldingen voor elk geregistreerd blok weg.

Waarom blokken configuratie nodig hebben

WPML leest de configuratie uit een bestand met de naam wpml-config.xml in de hoofdmap van het actieve thema en van elke actieve plugin. Voor een must-use-plugin bestaande uit één bestand heeft de map dezelfde naam als het bestand, zonder .php. Zie Taalconfiguratiebestanden en Maak aangepaste Gutenberg-blokken vertaalbaar.

Een blok zonder vermelding wordt overgelaten aan de automatische stringdetectie van WPML, die elk stringattribuut van het blok aanbiedt voor vertaling. Voor een Blockstudio-blok gaat het daarbij onder meer om selectiewaarden, bestandsverwijzingen, URL’s en CSS-klassen. Vertalers zien deze technische waarden naast de echte tekst, en een vertaalde selectiewaarde of klasse kan het blok onbruikbaar maken.

De configuratie genereren

Druk de configuratie af en sla deze op in de hoofdmap van het thema of de plugin waarmee de blokken worden geleverd:

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

Of laat de opdracht het bestand schrijven:

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

Een blok met een tekstveld, een afbeelding, een link en een herhaler:

{
  "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" }
        ]
      }
    ]
  }
}

wordt:

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

De waarde style is niet gedeclareerd, dus WPML kopieert deze ongewijzigd naar de vertaling. Ook de ID’s gallery en image worden gekopieerd, en WPML vervangt ze bij het weergeven van het blok elk door de bijlage voor de paginataal, zodat een vertaalde afbeelding een eigen alternatieve tekst kan hebben. Zie ‘ID’s automatisch omzetten in blokken’ in Maak aangepaste Gutenberg-blokken vertaalbaar. Als een bijlage geen vertaling heeft, behoudt WPML de oorspronkelijke ID.

Wat wordt gedeclareerd

De opdracht leest de geregistreerde blokken nadat custom/-velden en blokvelden zijn uitgebreid en overschrijvingen en attribuutfilters zijn toegepast. Velden die extensies toevoegen aan een Blockstudio-blok worden opgenomen. Velden die extensies toevoegen aan coreblokken of blokken van andere plugins niet, omdat die blokken hun configuratie uit WPML of uit hun eigen plugin halen.

Een blok zonder gedeclareerd tekstveld krijgt translate="0". WPML kopieert vervolgens alle waarden ervan en biedt niets aan voor vertaling. De velden files worden nog steeds binnen de vermelding gedeclareerd, omdat WPML bijlage-ID’s omzet, ongeacht wat translate aangeeft. Binnenblokken worden zoals gebruikelijk vertaald.

Niet gedeclareerd:

• Velden met hidden, omdat editors hun waarden niet schrijven.
• Velden met "translate": false, zie hieronder.
• Velden van aangepaste veldtypen die niet zijn geregistreerd met translate ingesteld op true. De opdracht geeft voor elk ervan een waarschuwing, omdat alleen het veldtype weet of de waarde tekst bevat. Een expliciete "translate": false voor een veld onderdrukt deze waarschuwing ook voor dat veld. Zie hieronder.
• Attributen die een blok declareert in zijn eigen attributes in plaats van als Blockstudio-velden.
• Opslagsleutels waarvan de velden verschillende typen hebben, zie hieronder.

Elk tekstveld wordt gedeclareerd, ook als het een technische waarde bevat, zoals een CSS-klasse, tenzij "translate": false is ingesteld.

Een veld weglaten

Een tekstveld kan een waarde bevatten die in elke taal hetzelfde moet zijn: een accountnaam, een e-mailadres, een anker of een CSS-klasse. WPML biedt deze waarde net als andere tekst aan voor vertaling, en een vertaalde waarde kan het blok onbruikbaar maken. Stel translate in op false om het veld uit de configuratie weg te laten, zodat WPML de waarde ongewijzigd naar de vertaling kopieert:

{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}

Op een group, tabs of repeater is "translate": false van toepassing op elk veld erin, inclusief geneste containers. Een onderliggend veld kan "translate": true niet gebruiken om een container waarvoor deze optie is uitgeschakeld alsnog op te nemen. Bij een files-veld laat false ook de bijlage-ID’s weg, zodat de vertaling de oorspronkelijke bijlagen behoudt.

Als u translate weglaat of instelt op true, blijft het bestaande gedrag behouden: het veldtype bepaalt wat er gebeurt. Verborgen velden en waardetypen zoals select worden daardoor niet vertaalbaar. De optie geldt voor blok- en extensievelden, verbergt of schakelt hun editorbedieningselementen niet uit en verandert hun opgeslagen waarden niet. Voer wp bs wpml config opnieuw uit nadat u de instelling hebt gewijzigd en werk uw wpml-config.xml bij met de gegenereerde configuratie.

Het label van elke sleutel is het veldlabel, voorafgegaan door de labels van de bovenliggende herhalers en groepen met een ID. WPML toont dit als veldnaam in de vertaaleditor. De twee sleutels van een link-veld voegen Link text en URL toe aan het label. Deze achtervoegsels worden vertaald naar de taal van de site, dus voer de opdracht uit met de taalinstelling waarin uw vertalers werken.

Aangepaste veldtypen

Een veldtype dat een gewone tekststring opslaat, geeft dat aan wanneer het wordt geregistreerd. Stel translate in op true in de definitie; daarvoor moet attribute zijn ingesteld op string:

bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);

De opdracht declareert vervolgens elk veld van dat type als vertaalbare tekst. Een veld kan nog steeds "translate": false instellen om zichzelf uit te sluiten. Zonder deze optie worden de velden van het type uitgesloten en gerapporteerd, zoals voorheen.

De labels wijzigen

Veldlabels zijn bedoeld voor de blokeditor en kunnen hints bevatten zoals “Afbeelding (optioneel)” die niets betekenen in de vertaaleditor. Het filter blockstudio/wpml/config/label ontvangt elk label voordat het wordt weggeschreven, samen met de context van de sleutel:

• block: de bloknaam.
• path: het opslagpad van het veld onder blockstudio.attributes, met niveau * voor de rijen van elke herhaler, bijvoorbeeld cards/*/link.
• field: de velddefinitie.
• parents: de labels van de bovenliggende herhalers en groepen met een ID.
• part: text voor een tekstveld, title of url voor de twee sleutels van een linkveld.

add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

Geef een lege tekenreeks terug om het label van een sleutel weg te laten, zodat WPML in plaats daarvan het label van het blok toont. Een retourwaarde die geen tekenreeks is, behoudt het oorspronkelijke label. Voer de opdracht opnieuw uit nadat u het filter hebt gewijzigd.

Velden met dezelfde opslagsleutel

Twee velden kunnen dezelfde opslagsleutel krijgen, bijvoorbeeld een blokveld en een uitbreidingsveld met dezelfde id, of het veld text in een groep met de ID cta en een veld met de ID cta_text. De opdracht declareert zo’n sleutel alleen als duidelijk is wat er wordt opgeslagen:

• Binnen de velden van een blok, buiten rijen van herhalers, registreert Blockstudio één attribuut per opslagsleutel, waardoor een later veld een eerder veld vervangt, ongeacht het type. Voor de uitbreidingen van een blok geldt hetzelfde: een later veld, of het veld van een later geregistreerde uitbreiding, vervangt een eerder veld.
• Een blokveld en een uitbreidingsveld met dezelfde sleutel blijven beide van kracht. De bloktemplate ontvangt de waarde zoals die door het blokveld is gedefinieerd, terwijl de uitbreiding wordt toegepast met het eigen veld. De sleutel wordt één keer gedeclareerd wanneer beide velden dezelfde declaratie nodig hebben: beide zijn tekstvelden (text, textarea, richtext of wysiwyg), beide zijn links, beide zijn velden van files (met multiple op een van beide krijgt de sleutel het niveau *), of geen van beide wordt gedeclareerd, zoals bij een select en een number. Twee herhalers worden veld voor veld in hun rijen vergeleken. Het label komt van het blokveld.
• Twee velden met dezelfde id in de rijen van één herhaler blijven ook beide van kracht en worden op dezelfde manier vergeleken.

Als de typen verschillen, bijvoorbeeld een veld van text in het blok en een veld van select in een uitbreiding, is de opgeslagen waarde tekst of een selectieoptie, afhankelijk van het besturingselement dat de waarde heeft weggeschreven. De opdracht declareert de sleutel niet en geeft een waarschuwing:

Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)

Hernoem een van de velden of geef beide hetzelfde type om de sleutel te laten declareren.

Houd de configuratie actueel

Voer de opdracht opnieuw uit nadat u velden hebt toegevoegd, verwijderd of hernoemd, en lever het bijgewerkte bestand mee met het thema of de plugin. Genereer configuraties die vóór 7.7.5 zijn gemaakt opnieuw om declaraties voor bijlage-ID’s op te nemen. Inhoud die al bestond, toont nieuwe velden voor vertaling zodra het origineel is bijgewerkt, zoals beschreven in de bovenstaande handleiding WPML.

Met --file maakt de opdracht een ontbrekend bestand aan. In een bestaand bestand vervangt de opdracht alleen de tekst tussen <!-- blockstudio:start --> en <!-- blockstudio:end -->, zodat andere secties en vermeldingen voor andere blokken behouden blijven:

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

Als u een bestaand bestand zonder markeringen wilt gebruiken, voegt u de twee markeringsregels één keer toe binnen het element gutenberg-blocks, of voegt u een element gutenberg-blocks met de markeringen toe als het bestand dat nog niet bevat. Zonder de markeringen, of als het resultaat geen geldige configuratie zou zijn, laat de opdracht het bestand ongewijzigd en stopt met een foutmelding.

Vermeldingen voor blokken Blockstudio die handmatig zijn toegevoegd, zoals vermeldingen translate="0" die technische waarden verbergen, zijn niet meer nodig zodra de gegenereerde sectie het blok omvat. De opdracht waarschuwt voor elk blok dat meer dan één keer is gedeclareerd, zodat deze vermeldingen kunnen worden verwijderd.

Afbeeldingsteksten in vertaalopdrachten

WPML voegt de teksten van de afbeeldingen die een pagina gebruikt toe aan de vertaalopdracht voor die pagina: titel, alternatieve tekst, bijschrift en beschrijving. Wanneer de opdracht is voltooid, schrijft WPML de vertaalde teksten weg naar de bijlage in de doeltaal en maakt die bijlage aan als deze nog niet bestaat. Zie Afbeeldingen vertalen. WPML vindt afbeeldingen in <img>-tags in de inhoud, in galerijen, in de uitgelichte afbeelding en in de blokken die het herkent. Een blok Blockstudio slaat bijlage-ID’s op in de blokopmerking, dus WPML vindt er geen.

Wanneer WPML actief is, voegt Blockstudio de bijlagen die zijn velden opslaan in de blokken van een pagina toe aan de gevonden afbeeldingen WPML:

• Velden files, ook verborgen velden, en velden attributes met media; dezelfde velden die de blokeditor als media laadt.
• Velden in groepen, tabbladen, rijen van herhalers en binnenblokken.
• Velden van uitbreidingen, ook op kernblokken en blokken van andere plugins, omdat hun waarden zijn opgeslagen in de attributen van het uitgebreide blok.

Waarden die geen bijlage-ID zijn, worden uitgesloten. Configuratie is niet nodig en wpml-config.xml is niet betrokken. Zonder WPML wordt niets gescand voor vertaalopdrachten en wordt de mediaintegratieklasse niet geladen.

Dit staat los van conversie van bijlage-ID’s: de gegenereerde XML vertelt WPML welke vertaalde bijlage moet worden weergegeven, terwijl deze integratie aangeeft welke afbeeldingsteksten in een vertaalopdracht moeten worden opgenomen. Tekenreeksverwijzingen en ID’s van berichten die geen bijlagen zijn, worden niet toegevoegd aan mediaopdrachten. Opgeslagen geneste veldwaarden krijgen voorrang op waarden op het hoogste niveau van blokken Blockstudio, net als bij het weergeven.

De teksten maken alleen deel uit van de opdracht als een van de opties voor afbeeldingstekst onder WPML > Settings > Media Translation is ingeschakeld: “Automatically detect best options for translating image texts” of “Translate Media Library texts when translating content”, net als bij afbeeldingen in kernblokken.

Blockstudio rapporteert de afbeeldingen via het filter wpml_ids_of_media_used_in_post, dat WPML toepast op de media van een bericht in PostWithMediaFiles. Als u een afbeelding van de taken wilt uitsluiten, verwijdert u het ID ervan in een callback op hetzelfde filter met een prioriteit hoger dan 10:

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