# WPML

WPML kääntää mukautetun lohkon attribuutit vain siltä osin kuin kieliasetustiedosto ne määrittää. Blockstudio tallentaa jokaisen kentän arvon lohkon kommenttiin kohtaan `blockstudio.attributes`, joten jokaiselle lohkolle tarvitaan merkintä, joka osoittaa WPML sen tekstikenttiin ja liitteiden tunnisteisiin. Komento `wp bs wpml config` kirjoittaa nämä merkinnät kaikille rekisteröidyille lohkoille.

## Miksi lohkot tarvitsevat määrityksen

WPML lukee määrityksen tiedostosta nimeltä `wpml-config.xml` aktiivisen teeman ja kunkin aktiivisen lisäosan juurikansiosta. Yksittäisestä tiedostosta koostuvan pakollisen lisäosan kansio on nimetty tiedoston mukaan ilman päätettä `.php`. Katso [Kielimääritystiedostot](https://wpml.org/documentation/support/language-configuration-files/) ja [Tee mukautetuista Gutenberg-lohkoista käännettäviä](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

Ilman merkintää oleva lohko jätetään WPML automaattisen merkkijonojen tunnistuksen varaan, joka tarjoaa käännettäväksi lohkon jokaisen merkkijonomääritteen. Blockstudio-lohkon tapauksessa näitä ovat myös valintojen arvot, tiedostoviittaukset, URL-osoitteet ja CSS-luokat. Kääntäjät näkevät nämä tekniset arvot varsinaisen tekstin vieressä, ja käännetty valinta-arvo tai luokka voi rikkoa lohkon.

## Määrityksen luominen

Tulosta määritys ja tallenna se teeman tai lisäosan juurikansioon, joka sisältää lohkot:

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

Tai anna komennon kirjoittaa tiedosto:

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

Lohko, jossa on tekstikenttä, kuva, linkki ja toistokenttä:

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

muuttuu seuraavaksi:

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

Arvoa `style` ei ole määritetty, joten WPML kopioi sen käännökseen muuttumattomana. Myös tunnukset `gallery` ja `image` kopioidaan, ja WPML korvaa ne sivun kielen liitteellä lohkoa näytettäessä, joten käännetyllä kuvalla voi olla oma vaihtoehtoinen tekstinsä. Katso kohta ”Tunnusten automaattinen muuntaminen lohkoissa” oppaasta [Tee mukautetuista Gutenberg-lohkoista käännettäviä](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/). Jos liitteellä ei ole käännöstä, WPML säilyttää alkuperäisen tunnuksen.

## Mitä määritetään

Komento lukee rekisteröidyt lohkot sen jälkeen, kun `custom/`-kentät ja lohkokentät on laajennettu ja ohitukset sekä määrite-suodattimet on otettu käyttöön. Kentät, jotka [laajennukset](https://blockstudio.dev/fi/docs/extensions/) lisäävät lohkoon Blockstudio, otetaan mukaan. Laajennusten ydilohkoihin tai muiden lisäosien lohkoihin lisäämiä kenttiä ei oteta mukaan, koska näiden lohkojen määritys tulee lähteestä WPML tai niiden omasta lisäosasta.

| Kenttä | Määritys |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Käännettävää tekstiä. |
| `link` | `title` tekstinä ja `url` yhdessä `type="link"` kanssa, jolloin WPML korvaa linkin käännöksellään, jos sellainen on saatavilla. |
| `files` | Tallennettu liitteen tunnus sekä `type="post-ids"` ja `sub-type="attachment"`. Kun käytössä on `multiple`, luettelolle määritetään taso nimeltä `*`; tämä vastaa myös yksittäistä tunnusta, jonka kenttä tallentaa, kun valittuna on yksi tiedosto. |
| `repeater` | Taso nimeltä `*`, joka vastaa jokaista riviä ja sisältää rivikenttien määritykset. Sisäkkäiset toistokentät toimivat samalla tavalla. |
| `group`, jossa on `id` | Ryhmän kentät, joiden avainetuliitteenä on ryhmän tunnus (`cta_text` kentälle `text` ryhmässä `cta`). |
| `group` ilman `id`-arvoa, `tabs` | Kentät ilman omaa tasoa. |
| Mukautettu kenttätyyppi, joka on rekisteröity asetuksella `translate`, jonka arvoksi on asetettu `true` | Käännettävää tekstiä, kuten `text`-kentässä. |
| Kaikki muut sisäänrakennetut tyypit | Ei määritetä. WPML kopioi arvon muuttumattomana. |

Lohko, jossa ei ole määritettyä tekstikenttää, saa arvon `translate="0"`. Tämän jälkeen WPML kopioi kaikki sen arvot eikä tarjoa siitä mitään käännettäväksi. Sen `files`-kentät määritetään silti merkinnässä, koska WPML muuntaa liitteiden tunnukset riippumatta siitä, mitä `translate` ilmoittaa. Sisälohkot käännetään tavalliseen tapaan.

Ei määritetä:

- Kentät, joissa on `hidden`, koska niiden arvoja eivät kirjoita muokkaajat.
- Kentät, joissa on `"translate": false`; katso alta.
- Kentät, joiden [mukautettuja kenttätyyppejä](https://blockstudio.dev/fi/docs/blocks/attributes/custom-field-types/) ei ole rekisteröity asetuksella `translate`, jonka arvoksi on asetettu `true`. Komento tulostaa jokaisesta varoituksen, koska vain kenttätyyppi tietää, sisältääkö sen arvo tekstiä. Kentälle erikseen asetettu `"translate": false` vaimentaa myös kyseistä kenttää koskevan varoituksen. Katso alta.
- Määritteet, jotka lohko määrittää natiivissa `attributes`-rakenteessaan sen sijaan, että ne olisivat Blockstudio-kenttiä.
- Tallennusavaimet, joiden kentillä on eri tyypit; katso alta.

Jokainen tekstikenttä määritetään, myös sellainen, joka sisältää teknisen arvon, kuten CSS-luokan, ellei siinä ole asetusta `"translate": false`.

### Jätä kenttä pois

Tekstikentässä voi olla arvo, jonka on oltava sama kaikilla kielillä: tilin käyttäjänimi, sähköpostiosoite, ankkuri tai CSS-luokka. WPML tarjoaa sen käännettäväksi muiden tekstien tapaan, ja käännetty arvo voi rikkoa lohkon. Aseta `translate` arvoon `false`, jotta kenttä jätetään pois määrityksestä ja WPML kopioi sen arvon käännökseen muuttumattomana:

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

`group`-, `tabs`- tai `repeater`-kentässä `"translate": false` koskee jokaista sisällä olevaa kenttää, myös sisäkkäisiä säilöjä. Lapsi ei voi kumota pois jätetyn säilön asetusta `"translate": true`-määrityksellä. `files`-kentässä `false` jättää pois myös liitteiden tunnukset, jolloin käännöksessä säilyvät alkuperäiset liitteet.

Jos `translate` jätetään pois tai asetetaan arvoon `true`, toiminta säilyy ennallaan: kenttätyyppi ratkaisee. Tämä ei tee piilotetuista kentistä tai arvoista, kuten `select`, käännettäviä. Asetus koskee lohkojen ja laajennusten kenttiä, ei piilota eikä poista käytöstä niiden muokkaimen säätimiä eikä muuta niiden tallennettuja arvoja. Suorita `wp bs wpml config` uudelleen asetuksen muuttamisen jälkeen ja päivitä `wpml-config.xml` luodulla määrityksellä.

Kunkin avaimen `label` on kentän nimi, jota edeltävät niiden tunnuksellisten ympäröivien toistokenttien ja ryhmien nimet. WPML näyttää sen käännösmuokkaimessa kentän nimenä. `link`-kentän kahteen avaimeen lisätään tunnisteet `Link text` ja `URL` kentän nimen perään. Nämä jälkiliitteet käännetään sivuston kielelle, joten suorita komento kääntäjiesi käyttämällä kielialueella.

### Mukautetut kenttätyypit

Tavallisen tekstimerkkijonon tallentava kenttätyyppi ilmoittaa siitä rekisteröinnin yhteydessä. Aseta määritelmässä `translate` arvoksi `true`; tämä edellyttää, että `attribute` on `string`:

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

Komento julistaa sitten kaikki kyseisen tyypin kentät käännettäväksi tekstiksi. Kenttä voi silti asettaa arvoksi `"translate": false`, jolloin se jätetään pois. Ilman tätä valintaa tyypin kentät jätetään pois ja niistä ilmoitetaan kuten aiemmin.

### Muuta tunnisteita

Kenttien tunnisteet on kirjoitettu lohkoeditoria varten, ja ne voivat sisältää vihjeitä, kuten ”Kuva (valinnainen)”, joilla ei ole merkitystä käännöseditorissa. Suodatin `blockstudio/wpml/config/label` vastaanottaa kunkin tunnisteen ennen sen kirjoittamista avaimen kontekstin kanssa:

- `block`: lohkon nimi.
- `path`: kentän tallennuspolku kohdan `blockstudio.attributes` alapuolella, taso `*` kunkin toistimen riveille, esimerkiksi `cards/*/link`.
- `field`: kentän määrittely.
- `parents`: ympäröivien toistimien ja ryhmien tunnisteet, joilla on ID.
- `part`: `text` tekstikentälle, `title` tai `url` linkkikentän kahdelle avaimelle.

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

Palauta tyhjä merkkijono, jos haluat jättää avaimen tunnisteen pois; tällöin WPML näyttää sen sijaan lohkon tunnisteen. Jos palautusarvo ei ole merkkijono, alkuperäinen tunniste säilyy. Suorita komento uudelleen suodattimen muuttamisen jälkeen.

### Kentät, joilla on sama tallennusavain

Kahdella kentällä voi olla sama tallennusavain, esimerkiksi lohkon kentällä ja laajennuskentällä, joilla on sama `id`, tai ryhmässä, jonka ID on `cta`, olevalla kentällä `text` ja kentällä, jonka ID on `cta_text`. Komento julistaa tällaisen avaimen vain, kun siihen tallennettavan arvon tyyppi on selvä:

- Lohkon kenttien sisällä, toistimen rivien ulkopuolella, Blockstudio rekisteröi yhden attribuutin tallennusavainta kohden, joten myöhempi kenttä korvaa aiemman tyypistä riippumatta. Lohkon laajennusten kentät toimivat samalla tavalla: myöhempi kenttä tai myöhemmin rekisteröidyn laajennuksen kenttä korvaa aiemman.
- Lohkon kenttä ja laajennuskenttä, joilla on sama avain, pysyvät molemmat käytössä. Lohkomalli saa arvon lohkon kentän määrittelemässä muodossa, kun taas laajennus käsittelee sen oman kenttänsä avulla. Avain julistetaan kerran, kun molemmat kentät tarvitsevat saman julistuksen: molemmat ovat tekstikenttiä (`text`, `textarea`, `richtext` tai `wysiwyg`), molemmat ovat linkkejä, molemmat ovat `files`-kenttiä (jos kummalla tahansa on `multiple`, avain saa tason `*`), tai kumpaakaan ei julisteta, kuten tapauksessa `select` ja `number`. Kahta toistinta verrataan kenttä kentältä niiden riveillä. Tunniste otetaan lohkon kentästä.
- Myös kahden kentän, joilla on sama `id` yhden toistimen riveillä, vaikutus säilyy molemmilla, ja niitä verrataan samalla tavalla.

Kun tyypit eroavat, esimerkiksi jos lohkossa on `text`-kenttä ja laajennuksessa `select`, tallennettu arvo on tekstiä tai valintavaihtoehto sen mukaan, mikä ohjaus kirjoitti sen. Komento ei julista avainta ja tulostaa varoituksen:

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

Nimeä toinen kentistä uudelleen tai aseta molemmille sama tyyppi, jotta avain julistetaan.

## Pidä asetukset ajan tasalla

Suorita komento uudelleen, kun lisäät, poistat tai nimeät kenttiä uudelleen, ja toimita päivitetty tiedosto teeman tai lisäosan mukana. Luo uudelleen ennen 7.7.5 luodut asetukset, jotta niihin sisältyvät liitetiedostojen ID-määritykset. Ennen tätä olemassa olleessa sisällössä uudet kentät tulevat käännettäviksi, kun sen alkuperäinen versio päivitetään, kuten yllä olevassa WPML oppaassa kuvataan.

Kun käytössä on `--file`, komento luo puuttuvan tiedoston. Olemassa olevassa tiedostossa se korvaa vain tekstin merkkien `<!-- blockstudio:start -->` ja `<!-- blockstudio:end -->` väliltä, joten muut osiot ja muiden lohkojen merkinnät säilyvät ennallaan:

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

Jos haluat käyttää olemassa olevaa tiedostoa, jossa ei vielä ole merkkejä, lisää kaksi merkkiriviä kerran sen `gutenberg-blocks`-elementin sisään tai lisää `gutenberg-blocks`-elementti, jossa merkit ovat mukana, jos tiedostossa ei ole elementtiä. Jos merkkejä ei ole tai tuloksena ei olisi kelvollinen asetustiedosto, komento jättää tiedoston ennalleen ja päättyy virheeseen.

Käsin kirjoitettuja Blockstudio-lohkojen merkintöjä, kuten teknisiä arvoja piilottavia `translate="0"`-merkintöjä, ei enää tarvita, kun luotu osio kattaa lohkon. Komento varoittaa jokaisesta lohkosta, joka on julistettu useammin kuin kerran, joten nämä merkinnät voidaan poistaa.

## Kuvien tekstit käännöstöissä

WPML lisää sivulla käytettyjen kuvien tekstit sivun käännöstyöhön: otsikon, vaihtoehtoisen tekstin, kuvatekstin ja kuvauksen. Kun työ on valmis, WPML kirjoittaa käännetyt tekstit kohdekielen liitetiedostoon ja luo kyseisen liitetiedoston, jos sitä ei vielä ole. Katso [Ohje median kääntämiseen](https://wpml.org/documentation/translating-your-contents/media/).
WPML etsii kuvat sisällön `<img>`-tageista, gallerioista, artikkelikuvasta ja tuntemistaan lohkoista. Blockstudio-lohko tallentaa liitetiedostojen ID:t lohkon kommenttiin, joten WPML ei löydä niitä.

Kun WPML on käytössä, Blockstudio lisää sivun lohkoissa kenttiensä tallentamat liitetiedostot löydettyjen kuvien WPML joukkoon:

- `files`-kentät, myös piilotetut, sekä `attributes`-kentät, joissa on `media`; nämä ovat samoja kenttiä, jotka lohkoeditori lataa mediana.
- Ryhmien, välilehtien, toistimen rivien ja sisäkkäisten lohkojen kentät.
- [laajennusten](https://blockstudio.dev/fi/docs/extensions/) kentät, myös ydinlohkoissa ja muiden lisäosien lohkoissa, koska niiden arvot tallennetaan laajennetun lohkon attribuutteihin.

Arvot, jotka eivät ole liitetiedoston ID:itä, jätetään pois. Mitään ei tarvitse määrittää, eikä `wpml-config.xml` ole mukana. Ilman WPML-asetusta käännöstöitä varten ei skannata mitään eikä median integrointiluokkaa ladata.

Tämä on erillään liitetiedostojen ID-muunnoksesta: luotu XML kertoo WPML:lle, mikä käännetty liitetiedosto renderöidään, kun taas tämä integrointi kertoo sille, mitkä liitetiedostojen tekstit lisätään käännöstyöhön. Merkkijonoviittauksia ja muiden kuin liitetiedostojen artikkelien ID:itä ei lisätä mediatöihin. Tallennetut sisäkkäisten kenttien arvot ovat ensisijaisia ylimmän tason arvoihin nähden Blockstudio-lohkoissa, kuten myös renderöinnissä.

Tekstit sisällytetään työhön vain, kun jokin kuvan tekstiasetuksista kohdassa WPML > Settings > Media Translation on käytössä: ”Automatically detect best options for translating image texts” tai ”Translate Media Library texts when translating content”, kuten ydinlohkojen kuvien kohdalla.

Blockstudio raportoi kuvat suodattimen kautta
`wpml_ids_of_media_used_in_post`, joka WPML koskee julkaisun mediaa
`PostWithMediaFiles`. Jos haluat jättää kuvan pois töistä, poista sen tunnus saman suodattimen
callback-funktiossa prioriteetilla, joka on suurempi kuin 10:

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