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 oraz Jak sprawić, by własne bloki Gutenberg były tłumaczalne.

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:

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

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

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

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

{
  "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ę:

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

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, 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:

{
  "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:

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.

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:

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:

<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. 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ń, 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:

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