# WPML

WPML översätter attributen i ett anpassat block endast i den utsträckning som deklareras i en språkkonfigurationsfil. Blockstudio lagrar varje fältvärde i blockkommentaren under `blockstudio.attributes`, så varje block behöver en post som anger WPML för dess textfält och bifogade ID:n. Kommandot `wp bs wpml config` skriver dessa poster för varje registrerat block.

## Varför block behöver en konfiguration

WPML läser konfigurationen från en fil med namnet `wpml-config.xml` i rotmappen för det aktiva temat och varje aktivt tillägg. För ett must-use-tillägg som består av en enda fil heter mappen samma sak som filen, utan `.php`. Se [Språkfiler för konfiguration](https://wpml.org/documentation/support/language-configuration-files/) och [Gör anpassade Gutenberg-block översättningsbara](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

Ett block utan en post överlåts till WPMLs automatiska strängidentifiering, som erbjuder varje strängattribut i blocket för översättning. För ett Blockstudio-block omfattar det urvalsvärden, filreferenser, URL:er och klasser i CSS. Översättare ser dessa tekniska värden bredvid den faktiska texten, och ett översatt urvalsvärde eller en översatt klass kan göra att blocket slutar fungera.

## Generera konfigurationen

Skriv ut konfigurationen och spara den i rotmappen för temat eller tillägget som innehåller blocken:

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

Eller låt kommandot skriva filen:

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

Ett block med ett textfält, en bild, en länk och en upprepningsbar grupp:

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

blir:

```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ärdet `style` deklareras inte, så WPML kopierar det oförändrat till översättningen. Även ID:na `gallery` och `image` kopieras, och WPML ersätter vart och ett med bilagan för sidans språk när blocket renderas, så att en översatt bild kan ha sin egen alt-text. Se ”Konvertera ID:n automatiskt i block” i [Gör anpassade Gutenberg-block översättningsbara](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).
När en bilaga saknar översättning behåller WPML det ursprungliga ID:t.

## Vad som deklareras

Kommandot läser de registrerade blocken efter att fält i `custom/` och blockfält har utökats och åsidosättningar och attributfilter har tillämpats. Fält som [tillägg](https://blockstudio.dev/sv/docs/extensions/) lägger till i ett Blockstudio-block inkluderas. Fält som tillägg lägger till i kärnblock eller i andra tilläggs block inkluderas inte, eftersom dessa block får sin konfiguration från WPML eller från sitt eget tillägg.

| Fält | Deklaration |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Översättningsbar text. |
| `link` | `title` som text och `url` med `type="link"`, så att WPML ersätter en länk med dess översättning när en sådan finns. |
| `files` | Det lagrade bilage-ID:t med `type="post-ids"` och `sub-type="attachment"`. Med `multiple` används en nivå med namnet `*` för listan, vilket också matchar det enskilda ID:t som fältet lagrar när en fil väljs. |
| `repeater` | En nivå med namnet `*` som matchar varje rad, med deklarationerna för radens fält. Nästlade upprepningsbara grupper fungerar på samma sätt. |
| `group` med en `id` | Gruppens fält, med gruppens ID som nyckelprefix (`cta_text` för fältet `text` i gruppen `cta`). |
| `group` utan en `id`, `tabs` | Fälten utan en egen nivå. |
| Anpassad fälttyp registrerad med `translate` inställd på `true` | Översättningsbar text, som ett `text`-fält. |
| Alla andra inbyggda typer | Deklareras inte. WPML kopierar värdet oförändrat. |

Ett block utan deklarerat textfält får `translate="0"`. WPML kopierar då alla dess värden och erbjuder inget i blocket för översättning. Dess `files`-fält deklareras fortfarande i posten, eftersom WPML konverterar bilage-ID:n oavsett vad `translate` anger. Inre block översätts som vanligt.

Deklareras inte:

- Fält med `hidden`, eftersom deras värden inte skrivs av redigerare.
- Fält med `"translate": false`, se nedan.
- Fält för [anpassade fälttyper](https://blockstudio.dev/sv/docs/blocks/attributes/custom-field-types/)
  som inte har registrerats med `translate` inställt på `true`. Kommandot skriver ut en
  varning för varje sådant fält, eftersom endast fälttypen vet om dess värde innehåller
  text. En uttrycklig `"translate": false` på ett fält undertrycker också denna
  varning för det fältet. Se nedan.
- Attribut som ett block deklarerar i sitt inbyggda `attributes` i stället för som
  fält i Blockstudio.
- Lagringsnycklar vars fält har olika typer, se nedan.

Varje textfält deklareras, även fält som innehåller ett tekniskt värde, till exempel en CSS-klass, om det inte har `"translate": false`.

### Utesluta ett fält

Ett textfält kan innehålla ett värde som måste vara detsamma på alla språk: ett kontonamn, en e-postadress, ett ankare eller en CSS-klass. WPML erbjuder det för översättning som vilken annan text som helst, och ett översatt värde kan göra att blocket slutar fungera. Ställ in `translate` på `false` för att utesluta fältet från konfigurationen, så att WPML kopierar dess värde oförändrat till översättningen:

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

För en `group`, `tabs` eller `repeater` gäller `"translate": false` för alla fält inuti, inklusive nästlade behållare. Ett underordnat element kan inte åsidosätta en utelämnad behållare med `"translate": true`. För ett `files`-fält utelämnar `false` även bilage-ID:na, så översättningen behåller de ursprungliga bilagorna.

Om `translate` utelämnas eller ställs in på `true` bevaras det befintliga beteendet: fälttypen avgör. Det gör inte dolda fält eller värdetyper som `select` översättningsbara. Alternativet gäller block- och tilläggsfält, döljer eller inaktiverar inte deras redigeringskontroller och ändrar inte deras lagrade värden. Kör `wp bs wpml config` igen när du har ändrat inställningen och uppdatera din `wpml-config.xml` med den genererade konfigurationen.

`label` för varje nyckel är fältetiketten, föregången av etiketterna för omslutande upprepningsbara grupper och grupper med ett ID. WPML visar den som fältnamn i översättningsredigeraren. De två nycklarna för ett `link`-fält lägger till `Link text` och `URL` i etiketten. Dessa suffix översätts till webbplatsens språk, så kör kommandot med den språkversion som dina översättare arbetar med.

### Anpassade fälttyper

En fälttyp som lagrar en vanlig textsträng anger det när den registreras. Ställ in `translate` på `true` i definitionen, vilket kräver att `attribute` är `string`:

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

Kommandot deklarerar sedan alla fält av den typen som översättningsbar text. Ett fält kan fortfarande ange `"translate": false` för att undantas. Utan alternativet undantas fälten av typen och rapporteras som tidigare.

### Ändra etiketterna

Fältetiketter är avsedda för blockredigeraren och kan innehålla ledtrådar som
”Bild (valfritt)” som inte betyder något i översättningsredigeraren. Filtret
`blockstudio/wpml/config/label` tar emot varje etikett innan den skrivs,
tillsammans med nyckelns kontext:

- `block`: blocknamnet.
- `path`: fältets lagringssökväg under `blockstudio.attributes`, med
  en nivå `*` för varje upprepares rader, till exempel `cards/*/link`.
- `field`: fältdefinitionen.
- `parents`: etiketterna för de omslutande uppreparna och grupperna med ett ID.
- `part`: `text` för ett textfält, `title` eller `url` för de två nycklarna i ett länkfält.

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

Returnera en tom sträng för att utelämna en nyckels etikett, så visar WPML blockets etikett i stället. Ett returvärde som inte är en sträng behåller den ursprungliga etiketten. Kör kommandot igen när filtret har ändrats.

### Fält med samma lagringsnyckel

Två fält kan få samma lagringsnyckel, till exempel ett blockfält och ett tilläggsfält med samma `id`, eller fältet `text` i en grupp med ID:t `cta` och ett fält med ID:t `cta_text`. Kommandot deklarerar en sådan nyckel endast när det är tydligt vad som lagras där:

- Bland blockets fält, utanför uppreparrader, registrerar Blockstudio ett attribut per lagringsnyckel, så ett senare fält ersätter ett tidigare, oavsett typ. Blockets tilläggsfält fungerar likadant: ett senare fält, eller ett fält från ett tillägg som registrerats senare, ersätter ett tidigare.
- Ett blockfält och ett tilläggsfält med samma nyckel är båda aktiva. Blockmallen får värdet så som blockfältet definierar det, medan tillägget tillämpas med sitt eget fält. Nyckeln deklareras en gång när båda fälten behöver samma deklaration: båda är textfält (`text`, `textarea`, `richtext` eller `wysiwyg`), båda är länkar, båda är fält av typen `files` (med `multiple` på något av dem får nyckeln nivån `*`), eller inget av dem deklareras, till exempel ett `select` och ett `number`. Två upprepare jämförs fält för fält i sina rader. Etiketten hämtas från blockets fält.
- Även två fält med samma `id` i raderna i en upprepning är båda aktiva och jämförs på samma sätt.

När typerna skiljer sig åt, till exempel ett `text`-fält i blocket och ett `select` i ett tillägg, är det lagrade värdet text eller ett valt alternativ, beroende på vilken kontroll som skrev det. Kommandot deklarerar inte nyckeln och skriver ut en varning:

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

Byt namn på ett av fälten eller ge båda samma typ så att nyckeln deklareras.

## Håll konfigurationen uppdaterad

Kör kommandot igen när du lägger till, tar bort eller byter namn på fält, och leverera den uppdaterade filen med temat eller tillägget. Generera om konfigurationer som skapats före 7.7.5 så att de innehåller deklarationer för bilage-ID:n. Innehåll som fanns sedan tidigare visar nya fält för översättning när originalet har uppdaterats, enligt beskrivningen i guiden WPML ovan.

Med `--file` skapar kommandot en fil om den saknas. I en befintlig fil ersätter det endast texten mellan `<!-- blockstudio:start -->` och
`<!-- blockstudio:end -->`, så att andra avsnitt och poster för andra block förblir som de är:

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

Om du vill använda en befintlig fil som ännu saknar markörer lägger du till de två markörraderna en gång inuti dess element `gutenberg-blocks`, eller lägger till ett element `gutenberg-blocks` med markörerna om filen saknar ett sådant. Utan markörerna, eller om resultatet inte skulle vara en giltig konfiguration, lämnar kommandot filen oförändrad och avslutas med ett fel.

Poster för block med Blockstudio som lagts till manuellt, till exempel poster med `translate="0"` som döljer tekniska värden, behövs inte längre när det genererade avsnittet omfattar blocket. Kommandot varnar för varje block som deklareras mer än en gång, så att dessa poster kan tas bort.

## Bildtexter i översättningsjobb

WPML lägger till texterna för bilderna som en sida använder i sidans översättningsjobb: titel, alternativtext, bildtext och beskrivning. När jobbet är klart skriver WPML de översatta texterna till bilagan på målspråket och skapar bilagan om den inte redan finns. Se [Så översätter du media](https://wpml.org/documentation/translating-your-contents/media/).
WPML hittar bilderna i innehållets `<img>`-taggar, i gallerier, i den utvalda bilden och i de block som det känner till. Ett Blockstudio-block lagrar bilage-ID:n i blockkommentaren, så WPML hittar inga av dem.

När WPML är aktivt lägger Blockstudio till de bilagor som dess fält lagrar i sidans block till de bilder som WPML har hittat:

- `files`-fält, även dolda, och `attributes`-fält med `media`, samma fält som blockredigeraren läser in som media.
- Fält i grupper, flikar, uppreparrader och inre block.
- Fält i [tillägg](https://blockstudio.dev/sv/docs/extensions/), även i kärnblock och block från andra tillägg, eftersom deras värden lagras i det utökade blockets attribut.

Värden som inte är ID:n för bilagor utelämnas. Ingen konfiguration behövs, och `wpml-config.xml` berörs inte. Utan WPML genomsöks ingenting efter översättningsjobb och mediaintegreringsklassen läses inte in.

Detta är separat från konvertering av bilage-ID:n: det genererade XML talar om för WPML vilken översatt bilaga som ska renderas, medan den här integreringen talar om vilka bilagetexter som ska ingå i ett översättningsjobb. Strängreferenser och ID:n för inlägg som inte är bilagor läggs inte till i mediajobb. Sparade värden i nästlade fält har företräde framför värden på toppnivå i Blockstudio-block, precis som vid rendering.

Texterna ingår i jobbet endast när ett av bildtextalternativen under WPML > Settings > Media Translation är aktiverat: ”Automatically detect best options for translating image texts” eller ”Translate Media Library texts when translating content”, precis som för bilder i kärnblock.

Blockstudio rapporterar bilderna via filtret
`wpml_ids_of_media_used_in_post`, som WPML tillämpar på ett inläggs media i
`PostWithMediaFiles`. Om du vill utesluta en bild från jobben tar du bort dess ID i en
callback på samma filter med en prioritet över 10:

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