WPML

WPML překládá atributy vlastního bloku pouze v rozsahu, který deklaruje jazykový konfigurační soubor. Blockstudio ukládá každou hodnotu pole do komentáře bloku pod blockstudio.attributes, takže každý blok potřebuje položku, která nasměruje WPML na jeho textová pole a ID příloh. Příkaz wp bs wpml config tyto položky vytvoří pro každý registrovaný blok.

Proč bloky potřebují konfiguraci

WPML čte konfiguraci ze souboru s názvem wpml-config.xml v kořenové složce aktivního motivu a každého aktivního pluginu. U pluginu určeného k povinnému načtení, který tvoří jediný soubor, se složka jmenuje stejně jako soubor bez .php. Viz Soubory s konfigurací jazyka a Zpřístupnění vlastních bloků Gutenberg k překladu.

Blok bez záznamu se ponechá automatickému rozpoznávání řetězců v WPML, které nabídne k překladu všechny řetězcové atributy bloku. U bloku Blockstudio, který obsahuje hodnoty výběru, odkazy na soubory, URL a třídy CSS. Překladatelé tyto technické hodnoty vidí vedle skutečného textu a přeložená hodnota výběru nebo třída může blok poškodit.

Vygenerování konfigurace

Vypište konfiguraci a uložte ji do kořenové složky motivu nebo pluginu, který bloky obsahuje:

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

Nebo nechte příkaz soubor vytvořit:

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

Blok s textovým polem, obrázkem, odkazem a opakovačem:

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

se změní na:

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

Hodnota style není deklarována, takže WPML ji zkopíruje do překladu beze změny. Zkopírují se také ID gallery a image a při vykreslení bloku WPML každé z nich nahradí přílohou v jazyce stránky, takže přeložený obrázek může mít vlastní alternativní text. Viz „Automatický převod ID v blocích“ v dokumentu Zpřístupnění vlastních bloků Gutenberg k překladu. Pokud příloha nemá překlad, WPML ponechá původní ID.

Co se deklaruje

Příkaz načte registrované bloky poté, co jsou rozbalena pole custom/ i pole bloků a jsou použita přepsání a filtry atributů. Zahrnuta jsou pole, která do bloku Blockstudio přidávají rozšíření. Pole, která rozšíření přidávají do základních bloků nebo bloků jiných pluginů, zahrnuta nejsou, protože konfiguraci těchto bloků zajišťuje WPML nebo jejich vlastní plugin.

Blok bez deklarovaného textového pole získá translate="0". WPML pak zkopíruje všechny jeho hodnoty a nenabídne žádnou k překladu. Jeho pole files jsou stále deklarována v záznamu, protože WPML převádí ID příloh bez ohledu na to, co určuje translate. Vnitřní bloky se překládají jako obvykle.

Nedeklarují se:

• Pole s hidden, protože jejich hodnoty nezapisují editoři.
• Pole s "translate": false, viz níže.
• Pole vlastních typů polí, která nejsou registrována s translate nastaveným na true. Příkaz pro každé z nich vypíše upozornění, protože pouze typ pole ví, zda jeho hodnota obsahuje text. Výslovné "translate": false u pole toto upozornění také potlačí. Viz níže.
• Atributy, které blok deklaruje ve svém nativním attributes, nikoli jako pole Blockstudio.
• Klíče úložiště, jejichž pole mají různé typy, viz níže.

Deklaruje se každé textové pole, včetně polí obsahujících technickou hodnotu, například třídu CSS, pokud není nastaveno "translate": false.

Vynechání pole

Textové pole může obsahovat hodnotu, která musí být ve všech jazycích stejná: uživatelské jméno účtu, e-mailovou adresu, kotvu nebo třídu CSS. WPML ji nabídne k překladu stejně jako jakýkoli jiný text a přeložená hodnota může blok poškodit. Nastavte translate na false, aby pole nebylo zahrnuto do konfigurace a WPML zkopíroval jeho hodnotu do překladu beze změny:

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

U pole group, tabs nebo repeater se "translate": false použije na všechna vnořená pole i kontejnery. Podřízené pole nemůže zrušit vynechání kontejneru pomocí "translate": true. U pole files false vynechá také ID příloh, takže překlad zachová původní přílohy.

Vynechání translate nebo nastavení na true zachovává dosavadní chování: rozhoduje typ pole. Skrytá pole ani typy hodnot jako select tím nelze zpřístupnit k překladu. Tato volba platí pro pole bloků i rozšíření, neskrývá ani nezakazuje jejich ovládací prvky v editoru a nemění uložené hodnoty. Po změně nastavení spusťte znovu wp bs wpml config a aktualizujte svůj wpml-config.xml vygenerovanou konfigurací.

label každého klíče tvoří popisek pole, před kterým jsou popisky nadřazených opakovačů a skupin s ID. WPML jej v editoru překladů zobrazuje jako název pole. Ke dvěma klíčům pole link se k popisku přidávají Link text a URL. Tyto přípony se překládají do jazyka webu, proto spusťte příkaz v jazyce, ve kterém pracují vaši překladatelé.

Vlastní typy polí

Typ pole, který ukládá prostý textový řetězec, to při registraci uvede. V definici nastavte translate na true; tato volba vyžaduje, aby attribute mělo hodnotu string:

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

Příkaz pak označí všechna pole daného typu jako přeložitelný text. Pole se stále může samo vynechat nastavením "translate": false. Bez této volby se pole daného typu jako dříve vynechají a nahlásí.

Změna štítků

Štítky polí se zapisují pro editor bloků a mohou obsahovat nápovědy, jako je „Obrázek (volitelné)“, které v editoru překladů nemají žádný význam. Filtr blockstudio/wpml/config/label přijímá každý štítek před jeho zapsáním spolu s kontextem klíče:

• block: název bloku.
• path: cesta k úložišti pole pod blockstudio.attributes, s úrovní * pro řádky každého opakovače, například cards/*/link.
• field: definice pole.
• parents: štítky nadřazených opakovačů a skupin s ID.
• part: text pro textové pole, title nebo url pro dva klíče pole odkazu.

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

Vraťte prázdný řetězec, chcete-li štítek klíče vynechat; WPML pak místo něj zobrazí štítek bloku. Návratová hodnota, která není řetězcem, zachová původní štítek. Po změně filtru spusťte příkaz znovu.

Pole se stejným klíčem úložiště

Dvě pole mohou mít nakonec stejný klíč úložiště, například pole bloku a pole rozšíření se stejným id nebo pole text ve skupině s ID cta a pole s ID cta_text. Příkaz deklaruje takový klíč pouze tehdy, když je jasné, co se pod ním ukládá:

• V rámci polí bloku, mimo řádky opakovače, Blockstudio zaregistruje jeden atribut pro každý klíč úložiště, takže pozdější pole nahradí dřívější bez ohledu na jeho typ. Stejně se chovají pole rozšíření bloku: pozdější pole nebo pole později zaregistrovaného rozšíření nahradí dřívější.
• Pole bloku i pole rozšíření se stejným klíčem zůstávají aktivní. Šablona bloku obdrží hodnotu definovanou polem bloku, zatímco rozšíření se použije se svým vlastním polem. Klíč se deklaruje jednou, když obě pole vyžadují stejnou deklaraci: obě jsou textová pole (text, textarea, richtext nebo wysiwyg), obě jsou odkazy, obě jsou pole files (s multiple u kteréhokoli z nich má klíč úroveň *) nebo není deklarováno ani jedno, například select a number. Dva opakovače se porovnávají pole po poli v jednotlivých řádcích. Štítek se převezme z pole bloku.
• Dvě pole se stejným id v řádcích jednoho opakovače zůstávají také aktivní a porovnávají se stejným způsobem.

Když se typy liší, například u pole text v bloku a pole select v rozšíření, je uloženou hodnotou text nebo možnost výběru podle toho, který ovládací prvek ji zapsal. Příkaz klíč nedeklaruje a vypíše upozornění:

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

Přejmenujte jedno z polí nebo oběma nastavte stejný typ, aby se klíč deklaroval.

Udržování konfigurace v aktuálním stavu

Po přidání, odebrání nebo přejmenování polí spusťte příkaz znovu a přidejte aktualizovaný soubor k šabloně nebo pluginu. Konfigurace vytvořené před 7.7.5 vygenerujte znovu, aby zahrnovaly deklarace ID příloh. Po aktualizaci původního obsahu se v něm objeví nová pole k překladu, jak je popsáno výše v příručce WPML.

Pomocí --file příkaz vytvoří chybějící soubor. V existujícím souboru nahradí pouze text mezi <!-- blockstudio:start --> a <!-- blockstudio:end -->, takže ostatní oddíly a položky pro jiné bloky zůstanou beze změny:

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

Chcete-li použít existující soubor, který zatím neobsahuje žádné značky, přidejte oba řádky se značkami jednou do jeho prvku gutenberg-blocks nebo přidejte prvek gutenberg-blocks se značkami, pokud soubor žádný takový prvek nemá. Pokud značky chybí nebo by výsledkem nebyla platná konfigurace, příkaz soubor ponechá beze změny a skončí s chybou.

Položky pro bloky Blockstudio, které byly zapsány ručně, například položky translate="0" skrývající technické hodnoty, už nejsou potřeba, jakmile vygenerovaná část daný blok pokrývá. Příkaz upozorní na každý blok deklarovaný více než jednou, takže tyto položky lze odstranit.

Texty obrázků v úlohách překladu

WPML zařadí texty obrázků použitých na stránce do její úlohy překladu: název, alternativní text, popisek a popis. Po dokončení úlohy WPML zapíše přeložené texty do přílohy v cílovém jazyce a vytvoří tuto přílohu, pokud ještě neexistuje. Viz Jak přeložit média. WPML vyhledává obrázky ve značkách <img> v obsahu, v galeriích, v náhledovém obrázku a ve známých blocích. Blok Blockstudio ukládá ID příloh do komentáře bloku, takže v něm WPML žádné nenajde.

Když je aktivní WPML, Blockstudio přidá mezi nalezené obrázky WPML také přílohy, jejichž ID ukládají pole v blocích dané stránky:

• Pole files, včetně skrytých, a pole attributes s media; jde o stejná pole, která editor bloků načítá jako média.
• Pole ve skupinách, panelech, řádcích opakovače a vnitřních blocích.
• Pole rozšíření, a to i v základních blocích a blocích jiných pluginů, protože jejich hodnoty se ukládají do atributů rozšířeného bloku.

Hodnoty, které nejsou ID přílohy, se vynechají. Není třeba nic konfigurovat a wpml-config.xml se nepoužívá. Bez WPML se nic neprohledává kvůli úlohám překladu a třída integrace médií se nenačte.

To je oddělené od převodu ID příloh: vygenerované XML říká WPML, kterou přeloženou přílohu vykreslit, zatímco tato integrace určuje, které texty příloh zahrnout do úlohy překladu. Řetězcové odkazy a ID příspěvků, které nejsou přílohami, se do úloh překladu médií nepřidávají. Uložené hodnoty vnořených polí mají přednost před hodnotami nejvyšší úrovně u bloků Blockstudio, stejně jako při vykreslování.

Texty jsou součástí úlohy pouze tehdy, je-li povolena některá z možností textů obrázků v nabídce WPML > Nastavení > Překlad médií: „Automaticky vyhledávat nejlepší možnosti pro překlad textů obrázků“ nebo „Překládat texty v knihovně médií při překladu obsahu“, stejně jako u obrázků v základních blocích.

Blockstudio vrací obrázky přes filtr wpml_ids_of_media_used_in_post, který WPML se vztahuje na média příspěvku v PostWithMediaFiles. Chcete-li obrázek vyřadit z úloh, odeberte jeho ID v callbacku na stejném filtru s prioritou vyšší než 10:

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