How to Translate WordPress Blocks: A Step-by-Step Guide for generating the json i18n file

Internationalization (I18N) is crucial for expanding the reach of your WordPress plugins and themes. With the introduction of Gutenberg in WordPress 5.0, the process of localizing JavaScript has become essential. This guide will walk you through translating WordPress blocks using JSON, leveraging the make-pot npm module.

Why JSON Translation for WordPress JavaScript?

With the shift to Gutenberg, WordPress now relies heavily on JavaScript for its block editor. This change necessitates a robust solution for internationalizing JavaScript. Unlike traditional PO/MO files used in PHP, JavaScript translations use JSON, making it compatible with the wp-i18n JavaScript package and the Jed JavaScript gettext library.

Setting Up `make-pot`

To get started, install the make-pot module globally via npm:

npm install -g @wp-blocks/make-pot

This module helps generate .pot files, which are the cornerstone for translating your plugin or theme.

Extracting Strings and Generating `.pot` Files

Use make-pot to extract strings from your plugin or theme and generate the .pot file. Here’s the basic usage:

npx @wp-blocks/make-pot [sourceDirectory] [destination] [options]

Options Include:

--slug <slug>: Plugin or theme slug.
--domain <domain>: Text domain.
--skip-js: Skip JavaScript files.
--skip-php: Skip PHP files.
--skip-blade: Skip Blade files.
--skip-block-json: Skip block.json files.
--skip-theme-json: Skip theme.json files.

For a complete list of options, refer to the module’s documentation.

Generating JSON Translation Files

After generating the .pot file, the next step is to translate it into different languages. Then, use make-pot to create the JSON translation files:

npx @wp-blocks/make-pot makejson language --scriptName="build/frontend.js"

This command creates a JSON file for each .po file in the languages directory. The JSON file will be named based on the md5 hash of the script file path, ensuring it matches the required format.

Registering JavaScript Block Translations

To make the translations available in your plugin or theme, register the JavaScript block translations. Here’s a sample implementation in PHP:

<?php
function my_i18n() {
    load_plugin_textdomain('my-text-domain', false, __DIR__ . '/languages');
}
add_action('init', 'my_i18n');

add_action('init', function () {
    register_block_type(__DIR__ . '/build', [
        "script" => "my-vendor-script",
        "viewScript" => "my-frontend-script",
        "editorScript" => "my-editor-script",
    ]);
});

function my_register_block_type() {
    $fe_assets = include __DIR__ . '/build/my-frontend-script.asset.php';

    wp_register_script(
        'my-frontend-script',
        plugin_dir_url(__FILE__) . 'build/frontend.js',
        $fe_assets['dependencies'],
        $fe_assets['version']
    );

    wp_set_script_translations('my-frontend-script', 'my-text-domain', plugin_dir_path(__FILE__) . '/languages');
}
add_action('init', 'my_register_block_type');

Conclusion

Translating WordPress blocks using JSON with the make-pot module simplifies the localization process for JavaScript-heavy projects. By following this guide, you can ensure your plugins and themes are accessible to a global audience, enhancing user experience and expanding your reach. Install make-pot today and streamline your internationalization workflow!

For further details and advanced usage, refer to the make-pot GitHub repository.