Prototype a Breadcrumbs block supporting internationalization

[bobbingwide]

• The idea of having a breadcrumbs block is not new.
• There are already many plugins and themes that deliver some sort of breadcrumb functionality.
• I decided I wanted to extend the logic in the sb-parent-block plugin to support the breadcrumbs trail.
• I also wanted to find out how to properly implement internationalization and localization of plugins that implement blocks.

The purpose of this issue is fourfold:

1. To develop basic block called Breadcrumbs ( sb/breadcrumbs-block )
2. That can be translated into other languages.
3. Demonstrate it using the UK English language ( en_GB locale) in my local development environment
4. Demonstrate it using the bbboing language ( bb_BB locale) in my local development environment

Miscellaneous Notes

• I commented on WP Tavern's post about the new block directory guidelines ( https://wptavern.com/revised-block-directory-guidelines-proposal-updates-wording-but-changes-little-else ) wondering whether or not I could get some single block plugins that use server side rendering accepted into the block directory.

• I searched for a Breadcrumbs block and found https://github.com/phpbits/breadcrumbs-block/ but thought it used more code than necessary.

• I also found Site Editor: add block breadcrumb WordPress/gutenberg#21274, but soon realised this is for Block breadcrumbs in Full Site Editing, and not a core block called breadcrumbs.

[bobbingwide]

OK, so I've tried to use wp_set_script_translations to register translations for the script but I can't see any translations appearing in the editor. This is the content of $this->registered for the handle I used to encrypt the JavaScript for the sb-breadcrumbs-block.

[sb-breadcrumbs-block-block-editor] => _WP_Dependency Object
        (
            [handle] => sb-breadcrumbs-block-block-editor
            [src] => https://s.b/wp54/wp-content/plugins/sb-breadcrumbs-block/build/index.js
            [deps] => Array
                (
                    [0] => wp-blocks
                    [1] => wp-editor
                    [2] => wp-element
                    [3] => wp-i18n
                    [4] => wp-polyfill
                )

            [ver] => 40ff2cd7d053a2e8ceaa1e7ee4a5dc84
            [args] => 
            [extra] => Array
                (
                )

            [textdomain] => sb-breadcrumbs-block
            [translations_path] => C:\apache\htdocs\wordpress\wp-content\plugins\sb-breadcrumbs-block/languages
        )

What's wrong? What files does it actually look for? Let's follow what happens in load_script_textdomain()

[bobbingwide]

OK. when

• the $handle used to register the block is sb-breadcrumbs-block-block-editor
• the text-domain is sb-block-editor
• and the locale is bb_BB
  then $handle_filename is set to sb-breadcrumbs-block-bb_BB-sb-breadcrumbs-block-block-editor.json

When the $path is set then load_script_translations() is called to look for $path/$handle_filename`.
It doesn't find this file so continues to try to determine the file name to load.

• The logic tries a number of names.
• I eventually worked out how to use the 'md5' stuff documented in https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/
• My solution was first documented here: Update to support makepot logic run against JavaScript files oik-i18n#6 (comment)
• I'll write it again below.

How the md5 method works

• wp i18n make-pot creates a .pot file from all the .php and .js source that contains translatable strings
• l10n ( localisation ) creates .po and .mo files for each locale required ( en_GB and bb_BB )
• wp i18n make-json creates a .json file for each .js file mentioned in each .po file

If make-pot was run against the source files ( src ) there would be many different .js files listed in the .po files.
For each .js file found a separate .json file is created, with the md5 value calculated from the .js file name

• md5 for src/index.js is 1fdf421c05c1140f6d71444ea2b27638
• md5 for src/sb-breadcrumbs-block/edit.js is 30338b81b9d834a0a3ccc281c0c5c485

But WordPress needs one .json file per .js file.
So we need the .json file that matches the strings in the file that's being enqueued; which is build/index.js

• md5 for build/index.js is dfbff627e6c248bcb3b61d7d06da9ca9

Therefore, the files that we need are:

• sb-breadcrumbs-block-bb_BB-dfbff627e6c248bcb3b61d7d06da9ca9.json
• sb-breadcrumbs-block-en_GB-dfbff627e6c248bcb3b61d7d06da9ca9.json

We therefore need the following two lines in package.json

"makepot": "wp i18n make-pot . languages/sb-breadcrumbs-block.pot --exclude=node_modules,vendor,src",
"makejson": "wp i18n make-json languages"

make-json has two additional parameters

[--purge]
Whether to purge the strings that were extracted from the original source file. Defaults to true, use --no-purge to skip the removal.
[--pretty-print]
Pretty-print resulting JSON files.

As noted previously see also bobbingwide/oik-i18n#6 (comment)

Previous thoughts

Assuming the solution above can be implemented for all my block plugins then these hacks are no longer necessary...

We can probably hook into

$file = apply_filters( 'load_script_translation_file', $file, $handle, $domain );

and fiddle the file back to the one we started with if the $handle is $domain-block-editor.

[bobbingwide]

sb-breadcrumbs-block v0.6.0 is now available. This issue can be closed.