Fixing WordPress block translations

Hi guys,

I’m currently working on a project that requires a custom block, which needs to be translated into multiple languages, both in the editor and the front-end, and I was messing around in Pinegrow to learn how to make this happen with the blocks it creates.

So I created a test plug-in with some strings and found that the translations only work with some strings entered via PHP. Translations in fields created with block attributes that use Javascript, for example, are simply not loaded when WordPress is used in another language.

Digging a bit into the generated block code, I found several missing pieces. Here are my findings for others interested in translating their blocks into other languages.

First, the native WordPress translation functions – for example, __( ‘My string’, ‘My text domain’) – are not correctly included for block attribute strings in the JavaScript function registerBlockType(), usually located in /blocks/your-block-name/your-block-name.js. In some cases, the translation function is included, but without the text domain, which makes them ineffective.

You can manually add these functions in the correct places, but it would be nice if Pinegrow would automatically insert them for us.

Also missing are some PHP translation functions in the /blocks/your-block-name/your-block-name-register.php file.

Another problem is that the wp-i18n Javascript package is missing from the PG_Blocks::register_block_type() method, located in inc/wp_pg_blocks_helpers.php. This package needs to be added to the array that loads the WordPress dependencies for the main block script (enqueued via enqueue_editor_script), which we edited in the previous step. Without this, WP’s native translation functions will do nothing.


Finally, we need to inform WordPress that our JavaScript contains translations using the wp_set_script_translations() function in the main PHP file (functions.php, for themes, or plugin-name.php, for plug-ins). You can add the snippet below to the end of the main PHP file:

function my_theme_set_script_translations() {
    wp_set_script_translations( 'block-my-plugin-my-block-script', 'my_text_domain', plugin_dir_path( __FILE__ ) . 'languages' );
add_action( 'init', 'my_theme_set_script_translations' );

It is important to add the correct identifier for this to work. For Pinegrow, it follows this formula:

block- + plugin-or-theme-slug + - + block-unique-id + - + script.

With the fixes in place, you can generate the translation files (in po/mo/json formats) by following the WordPress Developer official tutorial, and place them in the /languages/ folder in the root folder of your plugin or theme.

If you are using the LocalWP app to manage your WordPress installations, you can use the “Open site shell” link and navigate to the languages folder via the command line to use the necessary WP-CLI commands described in the tutorial.

Also, since we are talking about blocks, note that the load_theme_textdomain() and load_plugin_textdomain() commands included by Pinegrow for themes and plug-ins, respectively, are no longer needed.

Since WordPress version 4.6, translation files are automatically loaded on demand, freeing developers to explicitly invoke this function to load translations.

Here is a test theme for anyone who wants to take a look.

Again, it would be very nice if Pinegrow itself would fix these issues automatically, so that we could avoid a lot of manual work with every change in the block. What do you think @matjaz and @Emmanuel?