# WPML

WPML tõlgib kohandatud ploki atribuute ainult ulatuses, mille keele konfiguratsioonifail määrab. Blockstudio salvestab kõik väljaväärtused ploki kommentaari alla `blockstudio.attributes`, seega vajab iga plokk kirjet, mis suunab WPML selle tekstiväljade ja manuste ID-de juurde. Käsk `wp bs wpml config` kirjutab need kirjed kõigi registreeritud plokkide jaoks.

## Miks plokid vajavad konfiguratsiooni

WPML loeb konfiguratsiooni failist nimega `wpml-config.xml` aktiivse teema ja iga aktiivse plugina juurkaustas. Ühefaililise kohustusliku plugina puhul on kausta nimi faili nimi ilma `.php`-ta. Vt [Keele konfiguratsioonifailid](https://wpml.org/documentation/support/language-configuration-files/) ja [Kuidas muuta kohandatud Gutenberg plokid tõlgitavaks](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

Ilma kirjeta ploki puhul tuvastab stringid automaatselt WPML, mis pakub tõlkimiseks kõiki ploki stringi atribuute. Blockstudio ploki puhul hõlmab see ka valikuväärtusi, failiviiteid, URL-e ja CSS klasse. Tõlkijad näevad neid tehnilisi väärtusi koos tegeliku tekstiga ning tõlgitud valikuväärtus või klass võib ploki katki teha.

## Loo konfiguratsioon

Väljasta konfiguratsioon ja salvesta see teema või plugina juurkausta, mis plokid kaasa toob:

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

Või lase käsul fail kirjutada:

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

Tekstivälja, pildi, lingi ja kordusväljaga plokk:

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

muutub selliseks:

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

Väärtust `style` pole deklareeritud, seega kopeerib WPML selle tõlkesse muutmata kujul. Ka ID-d `gallery` ja `image` kopeeritakse ning WPML asendab kummagi ploki renderdamisel lehe keele manusega, nii et tõlgitud pildil saab olla oma alternatiivtekst. Vt „ID-de automaatne teisendamine plokkides“ juhendis [Kuidas muuta kohandatud Gutenberg plokid tõlgitavaks](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/). Kui manusel puudub tõlge, säilitab WPML algse ID.

## Mida deklareeritakse

Käsk loeb registreeritud plokke pärast `custom/` väljade ja plokiväljade laiendamist ning ülekirjutuste ja atribuudifiltrite rakendamist. Kaasas on väljad, mida [laiendused](https://blockstudio.dev/et/docs/extensions/) lisavad Blockstudio plokile. Väljad, mida laiendused lisavad tuumplokkidele või muude pluginate plokkidele, ei kuulu siia, sest need plokid saavad oma konfiguratsiooni kohast WPML või oma pluginast.

| Väli | Deklaratsioon |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Tõlgitav tekst. |
| `link` | `title` tekstina ja `url` koos `type="link"`-ga, nii et WPML asendab lingi selle tõlkega, kui see on saadaval. |
| `files` | Salvestatud manuse ID koos väärtustega `type="post-ids"` ja `sub-type="attachment"`. Koos väärtusega `multiple` kasutatakse loendi jaoks taset nimega `*`; see sobib ka üksiku ID-ga, mille väli salvestab siis, kui valitud on üks fail. |
| `repeater` | Tase nimega `*`, mis sobib iga reaga ja sisaldab reaväljade deklaratsioone. Pesastatud kordusväljad toimivad samamoodi. |
| `group` koos `id`-ga | Grupi väljad, grupi ID võtme prefiksina (`cta_text` väljale `text` grupis `cta`). |
| `group` ilma väärtuseta `id`, `tabs` | Väljad ilma oma tasemeta. |
| Kohandatud väljatyüp, mis on registreeritud nii, et `translate` väärtuseks on `true` | Tõlgitav tekst nagu `text` väli. |
| Kõik muud sisseehitatud tüübid | Deklareerimata. WPML kopeerib väärtuse muutmata. |

Plokile, millel pole deklareeritud tekstivälja, määratakse `translate="0"`. Seejärel kopeerib WPML kõik selle väärtused ega paku ühtegi neist tõlkimiseks. Selle `files` väljad deklareeritakse siiski kirjes, sest WPML teisendab manuste ID-sid sõltumata sellest, mida ütleb `translate`. Sisemisi plokke tõlgitakse tavapäraselt.

Deklareerimata:

- Väljad väärtusega `hidden`, sest redaktorid ei kirjuta nende väärtusi.
- Väljad väärtusega `"translate": false`, vt allpool.
- [kohandatud väljatyüpide](https://blockstudio.dev/et/docs/blocks/attributes/custom-field-types/) väljad, mis pole registreeritud nii, et `translate` väärtuseks oleks `true`. Käsk kuvab iga sellise välja kohta hoiatuse, sest ainult väljatyüp teab, kas selle väärtus sisaldab teksti. Väljale selgesõnaliselt määratud `"translate": false` jätab selle hoiatuse samuti kuvamata. Vt allpool.
- Atribuudid, mille plokk deklareerib algses `attributes`-is, mitte Blockstudio väljadena.
- Salvestusvõtmed, mille väljadel on erinevad tüübid, vt allpool.

Deklareeritakse iga tekstiväli, sealhulgas tehnilist väärtust, näiteks CSS klassi sisaldav väli, kui sellele pole määratud `"translate": false`.

### Jäta väli välja

Tekstiväli võib sisaldada väärtust, mis peab kõigis keeltes olema sama: konto kasutajanimi, e-posti aadress, ankur või CSS klass. WPML pakub selle tõlkimiseks nagu mis tahes muud teksti ning tõlgitud väärtus võib ploki katki teha. Jäta väli konfiguratsioonist välja, määrates `translate` väärtuseks `false`, nii et WPML kopeerib selle väärtuse tõlkesse muutmata kujul:

```json title="block.json"
{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}
```

Väljal `group`, `tabs` või `repeater` rakendub `"translate": false` igale sees olevale väljale, sealhulgas pesastatud konteineritele. Alamväli ei saa `"translate": true` abil välistatud konteinerit üle kirjutada. Väljal `files` jätab `false` välja ka manuste ID-d, nii et tõlkes säilivad algsed manused.

Väärtuse `translate` väljajätmine või selle määramine väärtuseks `true` säilitab senise käitumise: otsuse teeb väljatyüp. See ei muuda peidetud välju ega väärtusetüüpe, näiteks `select`, tõlgitavaks. See valik kehtib ploki- ja laiendusväljadele, ei peida ega lülita välja nende redaktori juhtelemente ega muuda salvestatud väärtusi. Käivita `wp bs wpml config` uuesti pärast sätte muutmist ja uuenda oma `wpml-config.xml` loodud konfiguratsiooniga.

Iga võtme `label` on väljasilti, mille ees on ID-ga ümbritsevate kordusväljade ja gruppide sildid. WPML kuvab selle tõlketoimetajas väljanimena. `link` välja kaks võtit lisavad sildile `Link text` ja `URL`. Need järelliited tõlgitakse saidi keelde, seega käivita käsk keeles, mida sinu tõlkijad kasutavad.

### Kohandatud väljatyüübid

Väljatyüp, mis salvestab lihtteksti stringina, annab sellest registreerimisel teada. Määra definitsioonis `translate` väärtuseks `true`; selleks peab `attribute` olema `string`:

```php title="functions.php"
bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);
```

Seejärel märgib käsk kõik seda tüüpi väljad tõlgitavaks tekstiks. Väli saab siiski määrata `"translate": false`, et see välja jätta. Ilma selle suvandita jäetakse seda tüüpi väljad välja ja neist antakse teada nagu varemgi.

### Siltide muutmine

Väljade sildid on mõeldud plokiredaktorile ja võivad sisaldada vihjeid, näiteks „Pilt (valikuline)”, millel pole tõlkeredaktoris tähendust. Filter `blockstudio/wpml/config/label` saab iga sildi enne selle salvestamist koos võtme kontekstiga:

- `block`: ploki nimi.
- `path`: välja salvestustee asukohas `blockstudio.attributes`, tasemega `*` iga kordaja rea jaoks, näiteks `cards/*/link`.
- `field`: välja määratlus.
- `parents`: ümbritsevate kordajate ja ID-ga rühmade sildid.
- `part`: `text` tekstivälja puhul, `title` või `url` lingivälja kahe võtme puhul.

```php title="functions.php"
add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);
```

Tagastage tühi string, et võtme silt välja jätta; siis kuvab WPML selle asemel ploki sildi. Stringist erinev tagastusväärtus jätab algse sildi alles. Käivitage käsk pärast filtri muutmist uuesti.

### Sama salvestusvõtmega väljad

Kahel väljal võib olla sama salvestusvõti, näiteks plokiväljal ja laiendusväljal, millel on sama `id`, või väljal `text` rühmas ID-ga `cta` ja väljal ID-ga `cta_text`. Käsk märgib sellise võtme ainult siis, kui on selge, mida sinna salvestatakse:

- Ploki väljade seas väljaspool kordaja ridu registreerib Blockstudio iga salvestusvõtme kohta ühe atribuudi, nii et hilisem väli asendab varasema, olenemata välja tüübist. Ploki laienduste väljad toimivad samamoodi: hilisem väli või hiljem registreeritud laienduse väli asendab varasema.
- Sama võtmega plokiväli ja laiendusväli jäävad mõlemad kehtima. Plokimall saab väärtuse plokivälja määratletud kujul, samal ajal kui laiendust rakendatakse selle enda väljaga. Võti märgitakse üks kord, kui mõlemad väljad vajavad sama määratlust: mõlemad on tekstiväljad (`text`, `textarea`, `richtext` või `wysiwyg`), mõlemad on lingid, mõlemad on `files` väljad (kui kummalgi on `multiple`, saab võti taseme `*`) või kumbagi pole deklareeritud, näiteks `select` ja `number`. Kahe kordaja välju võrreldakse nende ridades välja välja haaval. Silt pärineb plokiväljalt.
- Kahe välja puhul, millel on sama `id` ühe kordaja ridades, jäävad mõlemad samuti kehtima ja neid võrreldakse samal viisil.

Kui tüübid erinevad, näiteks ploki väli `text` ja laienduse väli `select`, on salvestatud väärtus tekst või valik, olenevalt selle kirjutanud juhtelemendist. Käsk ei deklareeri võtit ja kuvab hoiatuse:

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

Nimetage üks väli ümber või määrake mõlemale sama tüüp, et võti deklareeritaks.

## Hoidke konfiguratsioon ajakohasena

Käivitage käsk uuesti pärast väljade lisamist, eemaldamist või ümbernimetamist ning lisage uuendatud fail teema või pluginaga kaasa. Looge enne versiooni 7.7.5 koostatud konfiguratsioonid uuesti, et lisada manuse ID-de deklaratsioonid. Nagu eespool olevas WPML juhendis kirjeldatud, ilmuvad enne seda loodud sisus uued väljad tõlkimiseks pärast algteksti uuendamist.

Kui kasutate `--file`, loob käsk puuduva faili. Olemasolevas failis asendab see ainult teksti märgendite `<!-- blockstudio:start -->` ja `<!-- blockstudio:end -->` vahel, nii et muud jaotised ning teiste plokkide kirjed jäävad samaks:

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

Et kasutada olemasolevat faili, milles pole veel märgendeid, lisage need kaks märgendirida üks kord selle `gutenberg-blocks` elemendi sisse või lisage märgenditega `gutenberg-blocks` element, kui failis seda pole. Ilma märgenditeta või juhul, kui tulemus poleks kehtiv konfiguratsioon, jätab käsk faili muutmata ja lõpetab veaga.

Käsitsi kirjutatud kirjete järele plokkide Blockstudio jaoks, näiteks kirjete `translate="0"`, mis peidavad tehnilisi väärtusi, pole enam vajadust, kui loodud jaotis ploki katab. Käsk annab hoiatuse iga ploki kohta, mis on deklareeritud mitu korda, et need kirjed saaks eemaldada.

## Piltide tekstid tõlketöödes

WPML lisab lehe kasutatavate piltide tekstid lehe tõlketöösse: pealkirja, alternatiivteksti, pealdise ja kirjelduse. Kui töö on lõpetatud, kirjutab WPML tõlgitud tekstid sihtkeele manusele ja loob selle manuse, kui seda veel pole. Vt [Meedia tõlkimine](https://wpml.org/documentation/translating-your-contents/media/).
WPML leiab pildid sisu `<img>` siltidest, galeriidest, esiletõstetud pildist ja plokkidest, mida see tunneb. Plokk Blockstudio salvestab manuste ID-d ploki kommentaari, seega ei leia WPML neid.

Kui WPML on aktiivne, lisab Blockstudio lehe plokkides olevate väljade talletatud manused leitud piltide WPML hulka:

- `files` väljad, sealhulgas peidetud väljad, ja väljad `attributes` koos `media`-ga; samad väljad laadib plokiredaktor meediana.
- Väljad rühmades, vahekaartidel, kordaja ridades ja sisemistes plokkides.
- [laienduste](https://blockstudio.dev/et/docs/extensions/) väljad, ka põhikomponentide plokkides ja teiste pluginate plokkides, sest nende väärtused salvestatakse laiendatud ploki atribuutidesse.

Väärtused, mis pole manuse ID-d, jäetakse välja. Midagi pole vaja seadistada ja `wpml-config.xml` pole kaasatud. Ilma WPML-ta ei otsita tõlketööde jaoks midagi ning meedialõimimise klassi ei laadita.

See on manuse ID teisendamisest eraldi: loodud XML ütleb WPML-le, millist tõlgitud manust kuvada, samal ajal kui see lõiming määrab, millised manusetekstid tõlketöösse lisada. Stringiviiteid ja mitte-manusest postituste ID-sid meediatöödesse ei lisata. Salvestatud pesastatud väljade väärtused on Blockstudio plokkides ülimuslikud ülemise taseme väärtuste suhtes, nagu ka renderdamisel.

Tekstid lisatakse töösse ainult siis, kui üks piltide tekstide valikutest jaotises WPML > Settings > Media Translation on lubatud: „Automatically detect best options for translating image texts” või „Translate Media Library texts when translating content”, nagu põhikomponentide plokkides olevate piltide puhul.

Blockstudio annab filtrile teada piltidest
`wpml_ids_of_media_used_in_post`, mis WPML rakendub postituse meediale
`PostWithMediaFiles`. Pildi tööde hulgast välja jätmiseks eemaldage selle ID sama filtri tagasihelistuses, mille prioriteet on üle 10:

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