# WPML

WPML tłumaczy atrybuty niestandardowego bloku tylko w zakresie określonym w pliku konfiguracji językowej. Blockstudio przechowuje każdą wartość pola w komentarzu bloku pod `blockstudio.attributes`, dlatego każdy blok wymaga wpisu, który wskazuje WPML jego pola tekstowe i identyfikatory załączników. Polecenie `wp bs wpml config` zapisuje te wpisy dla każdego zarejestrowanego bloku.

## Dlaczego bloki potrzebują konfiguracji

WPML odczytuje konfigurację z pliku o nazwie `wpml-config.xml` znajdującego się w katalogu głównym aktywnego motywu i każdej aktywnej wtyczki. W przypadku wtyczki typu must-use będącej pojedynczym plikiem katalog nosi nazwę tego pliku bez `.php`. Zobacz [Pliki konfiguracji językowej](https://wpml.org/documentation/support/language-configuration-files/) oraz [Jak sprawić, by własne bloki Gutenberg były tłumaczalne](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

Blok bez wpisu pozostawia się automatycznemu wykrywaniu ciągów przez WPML, które udostępnia do tłumaczenia każdy atrybut tekstowy bloku. W przypadku bloku Blockstudio obejmuje to wartości select, odwołania do plików, adresy URL i klasy CSS. Tłumacze widzą te wartości techniczne obok właściwego tekstu, a przetłumaczona wartość select lub klasa może zepsuć blok.

## Wygeneruj konfigurację

Wyświetl konfigurację i zapisz ją w katalogu głównym motywu lub wtyczki, która dostarcza bloki:

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

Możesz też pozwolić poleceniu zapisać plik:

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

Blok z polem tekstowym, obrazem, odnośnikiem i repeaterem:

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

staje się:

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

Wartość `style` nie jest zadeklarowana, więc WPML kopiuje ją bez zmian do tłumaczenia. Identyfikatory `gallery` i `image` również są kopiowane, a WPML podczas renderowania bloku zastępuje każdy z nich załącznikiem w języku strony, dzięki czemu przetłumaczony obraz może mieć własny tekst alternatywny. Zobacz „Automatyczna konwersja identyfikatorów w blokach” w [Jak sprawić, by własne bloki Gutenberg były tłumaczalne](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/). Jeśli załącznik nie ma tłumaczenia, WPML zachowuje oryginalny identyfikator.

## Co jest deklarowane

Polecenie odczytuje zarejestrowane bloki po rozwinięciu pól `custom/` i pól bloków oraz zastosowaniu nadpisań i filtrów atrybutów. Uwzględniane są pola dodane przez [rozszerzenia](https://blockstudio.dev/pl/docs/extensions/) do bloku Blockstudio. Pola dodane przez rozszerzenia do bloków podstawowych lub bloków innych wtyczek nie są uwzględniane, ponieważ te bloki pobierają konfigurację z WPML albo z własnej wtyczki.

| Pole | Deklaracja |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg` | Tekst do tłumaczenia. |
| `link` | `title` jako tekst oraz `url` z `type="link"`, dzięki czemu WPML zastępuje odnośnik jego tłumaczeniem, jeśli jest dostępne. |
| `files` | Zapisany identyfikator załącznika z `type="post-ids"` i `sub-type="attachment"`. W przypadku `multiple` poziom o nazwie `*` dla listy, który pasuje również do pojedynczego identyfikatora zapisywanego przez pole po wybraniu jednego pliku. |
| `repeater` | Poziom o nazwie `*`, który pasuje do każdego wiersza, wraz z deklaracjami pól wiersza. Zagnieżdżone repeatery działają tak samo. |
| `group` z `id` | Pola grupy, z identyfikatorem grupy jako prefiksem klucza (`cta_text` dla pola `text` w grupie `cta`). |
| `group` bez `id`, `tabs` | Pola bez własnego poziomu. |
| Własny typ pola zarejestrowany z `translate` ustawionym na `true` | Tekst do tłumaczenia, tak jak w przypadku pola `text`. |
| Każdy inny wbudowany typ | Niezadeklarowany. WPML kopiuje wartość bez zmian. |

Blok bez zadeklarowanego pola tekstowego otrzymuje `translate="0"`. Następnie WPML kopiuje wszystkie jego wartości i nie udostępnia ich do tłumaczenia. Jego pola `files` nadal są zadeklarowane we wpisie, ponieważ WPML konwertuje identyfikatory załączników niezależnie od ustawień `translate`. Bloki wewnętrzne są tłumaczone jak zwykle.

Niezadeklarowane:

- Pola z `hidden`, ponieważ ich wartości nie są zapisywane przez edytorów.
- Pola z `"translate": false`, zobacz poniżej.
- Pola [własnych typów pól](https://blockstudio.dev/pl/docs/blocks/attributes/custom-field-types/), które nie są zarejestrowane z `translate` ustawionym na `true`. Polecenie wyświetla ostrzeżenie dla każdego z nich, ponieważ tylko typ pola wie, czy jego wartość zawiera tekst. Jawne `"translate": false` w polu wyłącza również to ostrzeżenie dla danego pola. Zobacz poniżej.
- Atrybuty, które blok deklaruje w swoim natywnym `attributes` zamiast jako pola Blockstudio.
- Klucze pamięci, których pola mają różne typy, zobacz poniżej.

Deklarowane jest każde pole tekstowe, także to przechowujące wartość techniczną, na przykład klasę CSS, chyba że ma ustawione `"translate": false`.

### Pominięcie pola

Pole tekstowe może przechowywać wartość, która musi być taka sama w każdym języku: nazwę konta, adres e-mail, kotwicę lub klasę CSS. WPML udostępnia ją do tłumaczenia jak każdy inny tekst, a przetłumaczona wartość może zepsuć blok. Ustaw `translate` na `false`, aby pominąć pole w konfiguracji, dzięki czemu WPML skopiuje jego wartość do tłumaczenia bez zmian:

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

W przypadku `group`, `tabs` lub `repeater` ustawienie `"translate": false` dotyczy każdego pola wewnątrz, w tym zagnieżdżonych kontenerów. Element podrzędny nie może nadpisać kontenera wyłączonego z tłumaczenia za pomocą `"translate": true`. W przypadku pola `files` ustawienie `false` pomija również identyfikatory załączników, więc tłumaczenie zachowuje oryginalne załączniki.

Pominięcie `translate` lub ustawienie go na `true` zachowuje dotychczasowe działanie: decyzję podejmuje typ pola. Nie sprawia to, że ukryte pola ani typy wartości takie jak `select` stają się tłumaczalne. Opcja dotyczy pól bloków i rozszerzeń, nie ukrywa ani nie wyłącza kontrolek edytora i nie zmienia zapisanych wartości. Po zmianie ustawienia ponownie uruchom `wp bs wpml config` i zaktualizuj swój `wpml-config.xml`, używając wygenerowanej konfiguracji.

`label` każdego klucza to etykieta pola poprzedzona etykietami otaczających repeaterów i grup mających identyfikator. WPML wyświetla ją jako nazwę pola w edytorze tłumaczeń. Dwa klucze pola `link` dodają do etykiety `Link text` i `URL`. Te przyrostki są tłumaczone na język witryny, dlatego uruchom polecenie z ustawieniami regionalnymi używanymi przez tłumaczy.

### Własne typy pól

Typ pola przechowujący zwykły ciąg tekstu sygnalizuje to podczas rejestracji. Ustaw `translate` na `true` w definicji. Wymaga to, aby `attribute` miało wartość `string`:

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

Polecenie deklaruje następnie każde pole tego typu jako tekst do tłumaczenia. Pole może nadal ustawić `"translate": false`, aby je pominąć. Bez tej opcji pola tego typu są pomijane i zgłaszane jak dotychczas.

### Zmiana etykiet

Etykiety pól są przeznaczone dla edytora bloków i mogą zawierać wskazówki, takie jak „Obraz (opcjonalnie)”, które nie mają znaczenia w edytorze tłumaczeń. Filtr `blockstudio/wpml/config/label` otrzymuje każdą etykietę przed jej zapisaniem, wraz z kontekstem klucza:

- `block`: nazwa bloku.
- `path`: ścieżka przechowywania pola poniżej `blockstudio.attributes`, z poziomem `*` dla wierszy każdego pola powtarzalnego, na przykład `cards/*/link`.
- `field`: definicja pola.
- `parents`: etykiety nadrzędnych pól powtarzalnych i grup z identyfikatorem.
- `part`: `text` dla pola tekstowego, `title` lub `url` dla dwóch kluczy pola łącza.

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

Zwróć pusty ciąg, aby pominąć etykietę klucza; wtedy WPML wyświetli etykietę bloku. Wartość zwrotna, która nie jest ciągiem, zachowuje oryginalną etykietę. Po zmianie filtra uruchom polecenie ponownie.

### Pola z tym samym kluczem przechowywania

Dwa pola mogą mieć ten sam klucz przechowywania, na przykład pole bloku i pole rozszerzenia z tym samym `id` albo pole `text` w grupie o identyfikatorze `cta` i pole o identyfikatorze `cta_text`. Polecenie deklaruje taki klucz tylko wtedy, gdy wiadomo, co jest w nim przechowywane:

- Wśród pól bloku, poza wierszami pól powtarzalnych, Blockstudio rejestruje jeden atrybut dla każdego klucza przechowywania, więc późniejsze pole zastępuje wcześniejsze, niezależnie od typu. Pola rozszerzeń bloku działają tak samo: późniejsze pole lub pole rozszerzenia zarejestrowanego później zastępuje wcześniejsze.
- Pole bloku i pole rozszerzenia z tym samym kluczem pozostają aktywne. Szablon bloku otrzymuje wartość zgodnie z definicją pola bloku, a rozszerzenie stosuje własne pole. Klucz jest deklarowany raz, gdy oba pola wymagają tej samej deklaracji: oba są polami tekstowymi (`text`, `textarea`, `richtext` lub `wysiwyg`), oba są łączami, oba są polami `files` (z `multiple` w jednym z nich klucz otrzymuje poziom `*`) albo żadne nie jest deklarowane, jak w przypadku `select` i `number`. Dwa pola powtarzalne są porównywane pole po polu w swoich wierszach. Etykieta pochodzi z pola bloku.
- Dwa pola z tym samym `id` w wierszach jednego pola powtarzalnego również pozostają aktywne i są porównywane w ten sam sposób.

Gdy typy się różnią, na przykład pole `text` w bloku i `select` w rozszerzeniu, przechowywana wartość jest tekstem lub opcją wyboru, zależnie od kontrolki, która ją zapisała. Polecenie nie deklaruje klucza i wyświetla ostrzeżenie:

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

Zmień nazwę jednego z pól albo nadaj obu ten sam typ, aby klucz został zadeklarowany.

## Aktualizowanie konfiguracji

Uruchom polecenie ponownie po dodaniu, usunięciu lub zmianie nazwy pól, a następnie dołącz zaktualizowany plik do motywu lub wtyczki. Wygeneruj ponownie konfiguracje utworzone przed 7.7.5, aby uwzględnić deklaracje identyfikatorów załączników. W istniejącej wcześniej treści nowe pola pojawią się do tłumaczenia po zaktualizowaniu jej oryginału, zgodnie z opisem w powyższym przewodniku WPML.

Po użyciu `--file` polecenie tworzy brakujący plik. W istniejącym pliku zastępuje tylko tekst między `<!-- blockstudio:start -->` i `<!-- blockstudio:end -->`, więc pozostałe sekcje i wpisy dotyczące innych bloków pozostają bez zmian:

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

Aby użyć istniejącego pliku, który nie zawiera jeszcze znaczników, dodaj raz dwie linie znaczników wewnątrz jego elementu `gutenberg-blocks` albo dodaj element `gutenberg-blocks` zawierający znaczniki, jeśli plik go nie ma. Bez znaczników lub gdy wynik nie byłby prawidłową konfiguracją, polecenie pozostawia plik bez zmian i kończy działanie z błędem.

Wpisy dotyczące bloków Blockstudio, dodane ręcznie, takie jak wpisy `translate="0"` ukrywające wartości techniczne, nie są już potrzebne, gdy wygenerowana sekcja obejmuje blok. Polecenie ostrzega o każdym bloku zadeklarowanym więcej niż raz, dzięki czemu te wpisy można usunąć.

## Teksty obrazów w zadaniach tłumaczeniowych

WPML dodaje teksty obrazów używanych na stronie do jej zadania tłumaczeniowego: tytuł, tekst alternatywny, podpis i opis. Po ukończeniu zadania WPML zapisuje przetłumaczone teksty w załączniku dla języka docelowego i tworzy ten załącznik, jeśli jeszcze nie istnieje. Zobacz [Jak tłumaczyć multimedia](https://wpml.org/documentation/translating-your-contents/media/).
WPML wyszukuje obrazy w znacznikach `<img>` w treści, w galeriach, w obrazku wyróżniającym i w obsługiwanych blokach. Blok Blockstudio przechowuje identyfikatory załączników w komentarzu bloku, więc WPML ich nie wyszukuje.

Gdy aktywne jest WPML, Blockstudio dodaje do znalezionych obrazów WPML załączniki przechowywane przez pola bloków na stronie:

- Pola `files`, w tym ukryte, oraz pola `attributes` z `media` — te same pola, które edytor bloków wczytuje jako multimedia.
- Pola w grupach, kartach, wierszach pól powtarzalnych i blokach wewnętrznych.
- Pola [rozszerzeń](https://blockstudio.dev/pl/docs/extensions/), także w blokach podstawowych i blokach innych wtyczek, ponieważ ich wartości są przechowywane w atrybutach rozszerzanego bloku.

Wartości, które nie są identyfikatorami załączników, są pomijane. Nie trzeba niczego konfigurować, a `wpml-config.xml` nie bierze w tym udziału. Bez WPML nie są skanowane zadania tłumaczeniowe, a klasa integracji z multimediami nie jest wczytywana.

To działa niezależnie od konwersji identyfikatorów załączników: wygenerowane XML informuje WPML, który przetłumaczony załącznik ma wyświetlić, a ta integracja wskazuje, które teksty załączników uwzględnić w zadaniu tłumaczeniowym. Odwołania do ciągów i identyfikatory wpisów, które nie są załącznikami, nie są dodawane do zadań tłumaczeniowych dotyczących multimediów. Zapisane wartości zagnieżdżonych pól mają pierwszeństwo przed wartościami najwyższego poziomu w blokach Blockstudio, tak jak podczas renderowania.

Teksty są uwzględniane w zadaniu tylko wtedy, gdy włączono jedną z opcji tekstu obrazów w sekcji WPML > Settings > Media Translation: „Automatycznie wykrywaj najlepsze opcje tłumaczenia tekstów obrazów” lub „Tłumacz teksty z biblioteki multimediów podczas tłumaczenia treści” — tak samo jak w przypadku obrazów w blokach podstawowych.

Blockstudio raportuje obrazy za pomocą filtra
`wpml_ids_of_media_used_in_post`, który WPML stosuje do multimediów wpisu w
`PostWithMediaFiles`. Aby pominąć obraz w zadaniach, usuń jego ID w
funkcji zwrotnej tego samego filtra z priorytetem wyższym niż 10:

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