Table of contents

Intro

The purpose of this article is to give you a list of steps you can follow when implementing multilingual support in your custom WordPress FSE (Full Site Editing).

In my scenario, we have a custom WordPress theme and a plugin that contains a lot of custom Gutenberg blocks we’ve created. We want to translate the pages, the custom blocks, template parts, patterns, and everything else that comes to mind.

My approach is using Polylang. I assume something similar can be achieved with WPML.

You will need Polylang Pro in order to translate template parts. This is very important, as this is one of the key parts in WordPress FSE and the thing that I struggled with.

Prepare your Gutenberg Blocks

Before moving on, make sure you add language support to your Gutenberg blocks.

I’m using the @wordpress/scripts and the scaffolding has: edit.js and render.php.

In the plugin that we’re using for all the custom blocks, go through the render.php file and wrap your static strings in __() with a dedicated text domain. This will help retrieve the translation we’re going to generate with Loco Translate.

Copy Code 


__('String that needs translation','my-custom-plugin')

Make sure you go through all the blocks and wrap the static strings in the translation function.

You can also translate the strings that are for the back-end, the ones in edit.js, but only if you think it makes sense. Your editors might not need those bits translated into their language. More importantly, it’s the front end that needs to be translated.

Copy Code 


<div className="dm-related-product-wrap text-center">
	<p>
		{__(
			"No related products found for the current product.",
			"my-custom-plugin",
		)}
	</p>
</div>

Polylag

As mentioned in the introduction, you will need Polylang Pro to be able to translate template parts in WordPress FSE.

Some other extra options that you want from Polylang Pro are:

  • Share slugs: Allows to share the same URL slug across languages for posts and terms.
  • Translate slugs: Allows to translate custom post types and taxonomies slugs in URLs.

We’re going to use Polylang to manage the different language content and identify the language that your visitor is on and keep delivering in the correct language.

Loco Translate

Since we have custom Gutenberg blocks in our implementation, we need to translate the static strings that are present in those blocks.

In a couple of steps ago we added translation support for all those static strings. Now we need to use Loco Translate and generate the .po files that will hold the string translation.

Go to: Dashboard > Loco Translate > Home

Find the text domain that you used in the second step and click on the bundle name.

Click on New language >  Select the language you want (ideally the same you defined in Polylang) > Choose location, leave it on Custom

Loco Translate add new language

Once you do that, the Spanish version in this case will appear, and you can go in and edit the strings that were identified.

If you didn’t map out all the strings you can sync again and it will grab any new strings that have that text domain.

Once you translated the strings the .po files are being generated and added to the plugin folder, this way you can also commit them via git to your repository.

Loco translate string translation example

Convert patterns into template parts

With Polylang Pro, you can translate template parts from the Site Editor in different languages, but you can’t do the same with patterns.

What I ended up doing was to convert the patterns that I use into template parts. This way, I could translate them into Spanish.

We had a CTA section that was appearing in multiple places on the site, and we needed to translate it into Spanish. Converting it to a template part was the easiest solution.

Switching to Spanish

Now that template part has the option to switch languages and edit the content in Spanish. No matter where I use it, I know it will be rendered in the correct language.

Translate content

Translating the content is pretty straightforward.

You can create the translation version of an existing post/page/custom post type and add the content in there.

I recommend using the bulk selector, as it gives you the option to generate the Spanish (or whatever language you use) version by duplicating the English content (original language).

This made things easier for me, as some of the pages were very heavy with multiple different Gutenberg blocks that I didn’t want to copy-paste or recreate from scratch. Now all you need to do is change the English text into the one you want, and that’s it.

Polylang bulk translate duplicate content

I recommend translating the slugs and the custom taxonomies as well. This is also easily done with Polylang Pro, and it will be good for SEO.

Troubleshooting

Here are a few things to be aware of:

  • Do not restore a template part because it will delete the translation.
    If you made changes to the template via your .html files in the theme, do not restore them on the site as it will delete the translation.
  • Be sure to generate the .po files when you install Loco Translate in case you don’t have them.
  • If you don’t see your strings in Loco Translate make sure you added the text domain correctly and wrapped your static strings in the correct function mentioned in Prepare your Gutenberg blocks.
    Hit the “Sync” button inside the Loco Translate text domain language.

Conclusion

Getting multilingual support up and running in a custom WordPress FSE setup might feel a bit overwhelming at first, but it’s totally doable.

Using Polylang Pro to handle the structure and Loco Translate to take care of the static strings means you can translate everything from template parts to custom Gutenberg blocks and make sure your site looks great in every language.