How to make a custom Gutenberg block multilingual

How to make a custom Gutenberg
block multilingual

🎯 Goal: Learn the best practices to make a custom Gutenberg block translatable and fully compatible with Polylang Pro.

How can this documentation help you

This guide explains how to make custom Gutenberg blocks multilingual and, as a result, exportable in an XLIFF file for both manual and machine translation.

Important things before you start:

To ensure Polylang detects your blocks, you need a configuration file (wpml-config.xml) that will define which parts of the block should be translatable.
Enable XLIFF export for professional translation workflows. Custom block data will be properly exported and reimported, allowing translation agencies to work with standard localization tools.
Control the machine translation scope. You can define exactly which block attributes should be translated. This prevents DeepL from mistakenly translating code fragments or system data, which could break HTML or waste API credits.

Before you start

Before you begin, make sure your project includes a wpml-config.xml file. If you can’t find any, create it from scratch, and place the file either:

In your custom plugin or theme folder.

In the global directory: /wp-content/polylang/ (create the folder if it doesn’t exist).

Basic usage

Here’s an example of a custom block:

html
<!-- pll:awesome-image
 	{
		"id":3,
		"foo": "Some text.",
		"bar": {
			"title": "Again some text.",
			"do-not-touch": "System Data"
		}
	}
-->

<figure class="pll-block-image">
	<img src="http://example.com/wp-content/uploads/2023/11/image.png" alt="Awesome image alt text" class="pll-image-3"/>
	<figcaption>My Awesome Image Caption</figcaption>
</figure>

<!-- /pll:awesome-image -->

In this example, the attributes to export are id, foo, and title. The content to export only includes the image alt text and the caption (“Awesome image alt text” and “My Awesome Image Caption”).

To make this data translatable by Polylang Pro, you need to define these attributes and paths in the wpml-config.xml file. This ensures that only translatable text is exported to XLIFF, and that you (or DeepL) translate only what’s needed.

Simply add the following lines to your configuration file:

xml
<wpml-config>
	<gutenberg-blocks>
		<gutenberg-block type="pll/awesome-image" translate="1">
			<key name="id"/><!-- ID attribute to export -->
			<key name="foo"/><!-- Text from "foo" attribute to export -->
			<key name="bar">
				<key name="title" /><!-- Text from "title" sub attribute to export -->
			</key>
			<xpath>//figure/figcaption</xpath><!-- Caption to export -->
	        <xpath>//figure/img/@alt</xpath><!-- Alt text to export -->
		</gutenberg-block>
	</gutenberg-blocks>
</wpml-config>

💡 Note for developers: wildcards are now fully supported.

With specific encoding

If your block includes encoded strings (for example, in URLs or JSON data), you can handle them easily with the correct syntax. Here’s an example of encoded data:

html
<!-- pll:encoded-data
 	{
		"data": "Some%20text%20to%20encode%20for%20some%20reason%21"
	}
-->

To make this block translatable, use the following configuration:

xml
<wpml-config>
	<gutenberg-blocks>
		<gutenberg-block type="pll/encoded-data" translate="1">
			<key name="data" encoding="json"/><!-- "data" URL encoded attribute to export, must use JSON though its URL encoded. -->
		</gutenberg-block>
	</gutenberg-blocks>
</wpml-config>

Notes

💡 Here, the json parameter actually corresponds to urlencode, it’s WPML which requires this specific syntax.

💡 XPath is a query language used to target specific elements within XML or HTML documents. It defines the exact path to the markup or attribute you want to export for translation. Although it can look technical, it’s very straightforward once you understand the document structure.

Limitations

Polylang can export all required data as long as the correct syntax is used.
However, note that the following is not supported:

Regular expressions (RegEx)

Related products