# 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](https://wpml.org/documentation/support/language-configuration-files/) a [Zpřístupnění vlastních bloků Gutenberg k překladu](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

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:

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

Nebo nechte příkaz soubor vytvořit:

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

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

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

se změní na:

```xml title="wpml-config.xml"
<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](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/). 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í](https://blockstudio.dev/cs/docs/extensions/). 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.

| Pole | Deklarace |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Přeložitelný text. |
| `link` | `title` jako text a `url` s `type="link"`, aby WPML nahradil odkaz překladem, pokud je k dispozici. |
| `files` | Uložené ID přílohy s `type="post-ids"` a `sub-type="attachment"`. U `multiple` se pro seznam použije úroveň pojmenovaná `*`, která odpovídá také jedinému ID uloženému v poli při výběru jednoho souboru. |
| `repeater` | Úroveň pojmenovaná `*`, která odpovídá každému řádku a obsahuje deklarace polí daného řádku. Vnořené opakovače fungují stejně. |
| `group` s `id` | Pole skupiny s ID skupiny jako předponou klíče (`cta_text` pro pole `text` ve skupině `cta`). |
| `group` bez `id`, `tabs` | Pole bez vlastní úrovně. |
| Vlastní typ pole registrovaný s `translate` nastaveným na `true` | Přeložitelný text, stejně jako u pole `text`. |
| Všechny ostatní vestavěné typy | Nedeklarují se. WPML hodnotu zkopíruje beze změny. |

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í](https://blockstudio.dev/cs/docs/blocks/attributes/custom-field-types/), 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:

```json title="block.json"
{
  "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`:

```php title="functions.php"
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.

```php title="functions.php"
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í:

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

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:

```xml title="wpml-config.xml"
<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](https://wpml.org/documentation/translating-your-contents/media/).
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í](https://blockstudio.dev/cs/docs/extensions/), 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:

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