Only 71% of sites built in WordPress include the English language. Every plugin is expected to be translation-ready so that the users can translate the strings of the plugin into their preferred language.

So, in PHP instead of:

echo "The cold never bothered me anyway";

We write

echo esc_html__( "The cold never bothered me anyway", "text-domain" );

__() function helps to retrieve the translation of the text.

The next step in PHP is to instruct the plugin to load the translated text for the language you’ve set.

add_action( 'init', 'myplugin_prefix_load_textdomain' );
 * Load plugin textdomain.
function myplugin_prefix_load_textdomain() {
  load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' ); 

The final step is to create the pot file. There are various ways of creating a pot file. My favorite tool is wp i18n to create the pot file in the current directory. It creates the pot file in one command. The command would be $wp i18n make-pot . languages/my-plugin.pot

However, the strings in JavaScript are not translated in this way. Since react or JSX is used widely in the block, we’ll write strings in JavaScript files while writing the block. So, this topic is about translating the strings written in react or JSX for the custom blocks.

Translating JavaScript Strings

To make the strings translation-ready in JavaScript files, we’ll use the package @wordpress/i18n, to install the package, we’ll add this package to the plugin’s package.json file. Then, “wp-i18n” can be added as a script dependency.

  "dependencies": {
    "@wordpress/i18n": "^4.9.0",

You’ll probably don’t need to add dependency manually if you’re using the built-in build package like @wordpress/scripts, or @wordpress/create-block. In those cases, the dependencies are created in the dist/index.asset.php file depending on the packages you’re importing. Under the hood, they are adding dependencies while enqueuing the JavaScript file.

So, in the JS file, let’s import __ from i18n:

import { __ } from '@wordpress/i18n';

We can now use the __() function in JavaScript just like in PHP. Here’s an example:

import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

 * Internal dependencies
import Edit from './edit';
import save from './save';

registerBlockType( 'my-plugin/block', {
    title: __( 'My Plugin', 'my-plugin' ),
    description: __( 'The plugin description which is translatable', 'my-plugin' ),
    icon: 'admin-users',
    category: 'common',

    edit: Edit,
} );

In the example above, the block title and description are translatable. Like __, we can also import other i18n tools like sprintf, _n, _x

import { sprintf, _n, __ } from '@wordpress/i18n';

However, we’re not done here. We should tell WordPress to look for the translations in our JS files using the wp_set_script_translations  function in PHP. Example:

    function myplugin_set_script_translations() {
        wp_set_script_translations( 'myplugin-script', 'my-plugin', plugin_dir_path( __FILE__ ) . 'languages' );
    add_action( 'init', 'myplugin_set_script_translations' );

Please note that if you’re using grunt-wp-i18n to create the pot file, it does not scan for the translations in the JavaScript files. So, you can use either WP-CLI’s i18n make-pot or @wordpress/babel-plugin-makepot  package WordPress recommends.

 For JavaScript, the translation files must be in the JED 1.x JSON format. We can use the following WP-CLI command:

wp i18n make-json languages 

which creates the JSON files for all the JavaScript strings in .pot file.

I hope this is helpful!

Translating JavaScript strings in the custom block plugin

Sanjeev Aryal

Don't bury your thoughts, put your vision into reality ~ Bob Marley.

Leave a Reply

Your email address will not be published. Required fields are marked *