WPML

WPML menerjemahkan atribut blok kustom hanya sesuai dengan deklarasi dalam file konfigurasi bahasa. Blockstudio menyimpan setiap nilai field dalam komentar blok di bawah blockstudio.attributes, sehingga setiap blok memerlukan entri yang mengarahkan WPML ke field teks dan ID lampirannya. Perintah wp bs wpml config menulis entri ini untuk setiap blok yang terdaftar.

Mengapa blok memerlukan konfigurasi

WPML membaca konfigurasi dari file bernama wpml-config.xml di folder root tema aktif dan setiap plugin aktif. Untuk plugin must-use yang berupa satu file, nama foldernya adalah nama file tanpa .php. Lihat File Konfigurasi Bahasa dan Jadikan Blok Gutenberg Kustom Dapat Diterjemahkan.

Blok tanpa entri diserahkan kepada deteksi string otomatis WPML, yang menawarkan setiap atribut string dalam blok untuk diterjemahkan. Untuk blok Blockstudio yang mencakup nilai select, referensi file, URL, dan kelas CSS. Penerjemah melihat nilai teknis ini bersama teks sebenarnya, dan nilai select atau kelas yang diterjemahkan dapat merusak blok.

Buat konfigurasi

Cetak konfigurasi dan simpan di folder root tema atau plugin yang menyertakan blok:

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

Atau biarkan perintah menulis file:

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

Blok dengan kolom teks, gambar, tautan, dan repeater:

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

menjadi:

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

Nilai style tidak dideklarasikan, jadi WPML menyalinnya ke terjemahan tanpa perubahan. ID gallery dan image juga disalin, dan WPML mengganti masing-masing ID dengan lampiran dalam bahasa halaman saat blok ditampilkan, sehingga gambar terjemahan dapat memiliki teks alt sendiri. Lihat “Mengonversi ID Secara Otomatis dalam Blok” di Jadikan Blok Gutenberg Kustom Dapat Diterjemahkan. Jika lampiran tidak memiliki terjemahan, WPML mempertahankan ID asli.

Yang dideklarasikan

Perintah membaca blok yang terdaftar setelah bidang custom/ dan bidang blok diperluas serta override dan filter atribut diterapkan. Bidang yang ditambahkan ekstensi ke blok Blockstudio disertakan. Bidang yang ditambahkan ekstensi ke blok inti atau blok plugin lain tidak disertakan, karena blok tersebut mendapatkan konfigurasinya dari WPML atau plugin masing-masing.

Blok tanpa bidang teks yang dideklarasikan akan mendapatkan translate="0". WPML lalu menyalin semua nilainya dan tidak menawarkan apa pun dari blok tersebut untuk diterjemahkan. Bidang files-nya tetap dideklarasikan di dalam entri, karena WPML mengonversi ID lampiran apa pun yang dinyatakan oleh translate. Blok dalam diterjemahkan seperti biasa.

Tidak dideklarasikan:

• Bidang dengan hidden, karena nilainya tidak ditulis oleh editor.
• Bidang dengan "translate": false, lihat di bawah.
• Bidang dari jenis bidang kustom yang tidak didaftarkan dengan translate diatur ke true. Perintah menampilkan peringatan untuk setiap bidang, karena hanya jenis bidang yang mengetahui apakah nilainya berisi teks. "translate": false yang ditetapkan secara eksplisit pada bidang juga meniadakan peringatan untuk bidang tersebut. Lihat di bawah.
• Atribut yang dideklarasikan blok dalam attributes aslinya, bukan sebagai bidang Blockstudio.
• Kunci penyimpanan yang bidang-bidangnya memiliki jenis berbeda, lihat di bawah.

Setiap bidang teks dideklarasikan, termasuk bidang yang menyimpan nilai teknis seperti kelas CSS, kecuali bidang tersebut menetapkan "translate": false.

Kecualikan bidang

Bidang teks dapat menyimpan nilai yang harus sama dalam setiap bahasa: nama akun, alamat email, jangkar, atau kelas CSS. WPML menawarkannya untuk diterjemahkan seperti teks lainnya, dan nilai terjemahan dapat merusak blok. Atur translate ke false untuk mengecualikan bidang dari konfigurasi, sehingga WPML menyalin nilainya ke terjemahan tanpa perubahan:

{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}

Pada group, tabs, atau repeater, "translate": false berlaku untuk setiap bidang di dalamnya, termasuk wadah bertingkat. Elemen turunan tidak dapat membatalkan pengecualian wadah dengan "translate": true. Pada bidang files, false juga mengecualikan ID lampiran, sehingga terjemahan mempertahankan lampiran asli.

Menghilangkan translate atau mengaturnya ke true mempertahankan perilaku yang ada: jenis bidang yang menentukan. Ini tidak membuat bidang tersembunyi atau jenis nilai seperti select dapat diterjemahkan. Opsi ini berlaku untuk bidang blok dan ekstensi, tidak menyembunyikan atau menonaktifkan kontrol editornya, dan tidak mengubah nilai yang tersimpan. Jalankan kembali wp bs wpml config setelah mengubah pengaturan, lalu perbarui wpml-config.xml Anda dengan konfigurasi yang dihasilkan.

label setiap kunci adalah label bidang, didahului label repeater dan grup penampung yang memiliki ID. WPML menampilkannya sebagai nama bidang di editor terjemahan. Dua kunci bidang link menambahkan Link text dan URL ke label. Akhiran ini diterjemahkan ke bahasa situs, jadi jalankan perintah dengan lokal yang digunakan penerjemah Anda.

Jenis bidang kustom

Jenis bidang yang menyimpan teks berupa string biasa menyatakannya saat didaftarkan. Atur translate ke true dalam definisi, yang mengharuskan attribute bernilai string:

bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);

Perintah tersebut kemudian menetapkan setiap field bertipe itu sebagai teks yang dapat diterjemahkan. Sebuah field tetap dapat mengatur "translate": false agar tidak disertakan. Tanpa opsi tersebut, field-field bertipe itu tidak disertakan dan dilaporkan seperti sebelumnya.

Ubah label

Label field ditulis untuk editor blok dan dapat memuat petunjuk seperti “Gambar (opsional)” yang tidak ada artinya di editor terjemahan. Filter blockstudio/wpml/config/label menerima setiap label sebelum label tersebut ditulis, beserta konteks key-nya:

• block: nama blok.
• path: jalur penyimpanan field di bawah blockstudio.attributes, dengan level * untuk baris setiap repeater, misalnya cards/*/link.
• field: definisi field.
• parents: label repeater dan grup yang menaunginya, beserta ID-nya.
• part: text untuk field teks, title atau url untuk kedua key pada field tautan.

add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

Kembalikan string kosong untuk tidak menyertakan label suatu key, sehingga WPML akan menampilkan label blok sebagai gantinya. Nilai kembalian yang bukan string akan mempertahankan label asli. Jalankan perintah lagi setelah mengubah filter.

Field dengan key penyimpanan yang sama

Dua field dapat memiliki key penyimpanan yang sama, misalnya field blok dan field ekstensi dengan id yang sama, atau field text di grup dengan ID cta dan field dengan ID cta_text. Perintah hanya menetapkan key semacam itu jika nilai yang disimpan di sana sudah jelas:

• Di antara field suatu blok, di luar baris repeater, Blockstudio mendaftarkan satu atribut untuk setiap key penyimpanan, sehingga field yang muncul belakangan menggantikan field sebelumnya, apa pun tipenya. Field ekstensi suatu blok bekerja dengan cara yang sama: field yang muncul belakangan, atau field dari ekstensi yang didaftarkan belakangan, menggantikan field sebelumnya.
• Field blok dan field ekstensi dengan key yang sama tetap berlaku. Templat blok menerima nilai sesuai definisi field pada blok, sementara ekstensi diterapkan dengan field-nya sendiri. Key hanya ditetapkan sekali jika kedua field memerlukan deklarasi yang sama: keduanya merupakan field teks (text, textarea, richtext, atau wysiwyg), keduanya tautan, keduanya field files (dengan multiple pada salah satunya, key mendapat level *), atau keduanya tidak dideklarasikan, misalnya select dan number. Dua repeater dibandingkan field demi field di dalam barisnya. Label diambil dari field blok.
• Dua field dengan id yang sama di baris satu repeater juga tetap berlaku dan dibandingkan dengan cara yang sama.

Jika tipenya berbeda, misalnya field text di blok dan field select di ekstensi, nilai yang disimpan berupa teks atau opsi pilihan, bergantung pada kontrol yang menuliskannya. Perintah tidak menetapkan key tersebut dan menampilkan peringatan:

Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)

Ganti nama salah satu field, atau samakan tipe keduanya, agar key tersebut ditetapkan.

Jaga konfigurasi tetap terbaru

Jalankan perintah lagi setelah menambahkan, menghapus, atau mengganti nama field, lalu sertakan file yang diperbarui bersama tema atau plugin. Buat ulang konfigurasi yang dibuat sebelum 7.7.5 agar deklarasi ID lampiran ikut disertakan. Konten yang sudah ada sebelumnya akan menampilkan field baru untuk diterjemahkan setelah konten sumbernya diperbarui, seperti dijelaskan dalam panduan WPML di atas.

Dengan --file, perintah membuat file jika belum ada. Jika file sudah ada, perintah hanya mengganti teks di antara <!-- blockstudio:start --> dan <!-- blockstudio:end -->, sehingga bagian lain dan entri untuk blok lain tetap seperti semula:

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

Untuk menggunakan file yang sudah ada tetapi belum memiliki penanda, tambahkan dua baris penanda itu sekali di dalam elemen gutenberg-blocks, atau tambahkan elemen gutenberg-blocks beserta penandanya jika file belum memilikinya. Tanpa penanda, atau jika hasilnya bukan konfigurasi yang valid, perintah tidak mengubah file dan keluar dengan kesalahan.

Entri untuk blok Blockstudio yang ditulis secara manual, seperti entri translate="0" yang menyembunyikan nilai teknis, tidak lagi diperlukan setelah bagian yang dihasilkan mencakup blok tersebut. Perintah memperingatkan setiap blok yang dideklarasikan lebih dari sekali, sehingga entri-entri ini dapat dihapus.

Teks gambar dalam pekerjaan terjemahan

WPML memasukkan teks gambar yang digunakan suatu halaman ke dalam pekerjaan terjemahan halaman tersebut: judul, teks alt, keterangan, dan deskripsi. Setelah pekerjaan selesai, WPML menulis teks terjemahan ke lampiran dalam bahasa target dan membuat lampiran tersebut jika belum ada. Lihat Cara Menerjemahkan Media. WPML menemukan gambar di dalam tag <img> pada konten, galeri, gambar unggulan, dan blok yang dikenalnya. Blok Blockstudio menyimpan ID lampiran di komentar blok, sehingga WPML tidak menemukan gambar apa pun di sana.

Saat WPML aktif, Blockstudio menambahkan lampiran yang disimpan oleh field-nya di blok halaman ke dalam gambar yang ditemukan oleh WPML:

• Field files, termasuk yang tersembunyi, dan field attributes dengan media, yaitu field yang sama dengan yang dimuat editor blok sebagai media.
• Field dalam grup, tab, baris repeater, dan blok dalam.
• Field dari ekstensi, termasuk pada blok inti dan blok dari plugin lain, karena nilainya disimpan dalam atribut blok yang diperluas.

Nilai yang bukan ID lampiran tidak disertakan. Tidak ada yang perlu dikonfigurasi, dan wpml-config.xml tidak terlibat. Tanpa WPML, tidak ada yang dipindai untuk pekerjaan terjemahan dan kelas integrasi media tidak dimuat.

Ini terpisah dari konversi ID lampiran: XML yang dihasilkan memberi tahu WPML lampiran terjemahan mana yang harus dirender, sedangkan integrasi ini memberi tahu teks lampiran mana yang perlu disertakan dalam pekerjaan terjemahan. Referensi string dan ID pos yang bukan lampiran tidak ditambahkan ke pekerjaan media. Nilai field bertingkat yang tersimpan lebih diutamakan daripada nilai tingkat atas pada blok Blockstudio, seperti saat dirender.

Teks hanya menjadi bagian dari pekerjaan jika salah satu opsi teks gambar di bawah WPML > Pengaturan > Terjemahan Media diaktifkan: “Deteksi otomatis opsi terbaik untuk menerjemahkan teks gambar” atau “Terjemahkan teks Pustaka Media saat menerjemahkan konten”, seperti pada gambar di blok inti.

Blockstudio melaporkan gambar melalui filter wpml_ids_of_media_used_in_post, yang WPML berlaku untuk media sebuah pos di PostWithMediaFiles. Untuk mengecualikan gambar dari pekerjaan, hapus ID-nya dalam callback pada filter yang sama dengan prioritas di atas 10:

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