Internationalizing WordPress Projects: Updates With WordPress 4.6

Throughout this series, we've covered exactly what you need to do to internationalize your WordPress projects. If you've not read any of the previous posts, I recommend checking them out.

Though there have been some changes to how internationalization and localization work in WordPress 4.6, that doesn't mean the previous tutorials are irrelevant. It just means that the way you opt to distribute your plugins and their localizations will change.

And that's what we're going to be covering in this tutorial.

Before We Start

As mentioned, this tutorial is assuming that you're caught up on everything we've discussed so far in this series. This includes:

  • Understanding internationalization and why it's important.
  • How to set up a development environment to work with the sample code.
  • Understanding localization (and the difference between internationalization).
  • How to use tools to begin translating your internationalized strings.

If none of the above makes any sense, then please review the series. If you feel confident that you can explain or use each of bullet points above, then you're ready to proceed.

Understanding the Changes

The nice thing about this tutorial is that it's more informative than theoretical (or practical, for that matter). That is, there won't be any code to demonstrate. It's just about disseminating information and making sure you know what to use and when.

Before we get too deep into the topic, let's back up a little bit and talk about the whole internationalization process of WordPress and how it works with loading localized files.

How Internationalization and Localization Work

The concepts of internationalization and localization are relatively easy to understand, but they're also easily confused (when I first started my work in WordPress, even I misused the terms).

Internationalization is the process of developing your plugin so it can easily be translated into other languages.

Thus, this is how we prepare all of the strings and human-readable text in our plugin that need to be translated for other locales.

Localization, then, is the act of actually translating the strings and bundling them into language packs that will then be loaded by WordPress depending on the locale that is set in the installation.

For example, let's say I build a plugin and I'm using American English, or in the en_US locale as you may see it written. Then you're going to see all of the text I've written in my language.

But what happens when someone who wants to use the plugin wants to translate it into Spanish? First, the person responsible will use a tool such as POEdit to provide the translations for each of the strings. 

Then she or he will store these in the languages directory (or whatever directory is used). The file should be named based on the locale for which it's related. In this case, es_ES.

The languages directory for Debug Bar

When the plugin is loaded in an installation of WordPress that's been installed on a machine that has the es_ES locale set as its default locale, the localization file will be loaded and will replace all of the translated strings with their Spanish equivalents.

And for a long time, this is how the internationalization process has worked. Furthermore, if you're opting to distribute plugins outside of the WordPress Plugin Repository, this is something that you will still need to do.

But what about for those plugins being distributed in the repository?

Just-in-Time Translations

In computer science, there's a concept of JIT (or just-in-time), and we often hear it referred to as "just-in-time" compilation.

In computing, just-in-time (JIT) compilation, also known as dynamic translation, is compilation done during execution of a program – at run time – rather than prior to execution.

In the latest release of WordPress, that is WordPress 4.6, internationalized plugins following a specific protocol are able to leverage the advantage of just-in-time localization. From the Make WordPress blog, these changes can be summarized as follows:

Since translations files are usually inside wp-content/languages, WordPress now scans that directory for available translations and automatically loads them if it encounters a text domain for the first time.

What does this mean for us developers? In short, it means that if we're distributing our work via the WordPress Plugin Repository, WordPress will first scan its library of translations to see if one exists for the current plugin and its locale. If it detects one, then it will use that one.

If it does not detect a translation, there one of two things can happen:

  1. The plugin simply won't be localized.
  2. The plugin will use the localization file that's included with the plugin.

There are some caveats to this new approach, though:

  1. We no longer have to call load_plugin_textdomain() in our WordPress 4.6-based plugins.
  2. If you're in the habit of using unload_textdomain(), you'll need to manually load the translations after the call if you want to use them again.

Though they are simple, I highly recommend reading the blog post in its entirety to understand how it works, its functionality, and how it applies to the work you're doing day to day.

Generally speaking, I find this feature incredibly nice. It gives us a chance to distribute plugins that may already have translations available and that can be loaded via WordPress. 

That said, I don't think it's an excuse not to bundle the internationalized files. After all, if a language pack isn't found, then it will still need to be loaded from the languages directory. 

And if the ultimate goal is to have the most resilient, robust plugins available, then we shouldn't rely on something that may not exist. Instead, let's hope for the best, but plan for the worst.


And with that, we've covered everything we can about how WordPress handles internationalization and localization for plugins that will be available in both the WordPress Plugin Repository and those you'll be distributing through your own channels.

If you're interested in learning more about WordPress from a development perspective, note that I exclusively work with WordPress and often write about it. You can catch all of my courses and tutorials on my profile page, and you can follow me on my blog and/or Twitter at @tommcfarlin where I talk about software development in the context of WordPress.

As always, if you're looking for other utilities to help you build out your growing set of tools for WordPress or for example code to study and become more well-versed in WordPress, don't forget to see what we have available in Envato Market.

Don't hesitate to leave any questions or comments in the feed below, and I'll aim to respond to each of them.

Related Resources

There are a number of resources listed below. Note that these come from the previous tutorials as well as what's been mentioned in this tutorial, as well. All of that to say, if you've read the previous tutorials you should be in good shape. If you've opted not to do so, then at least review the links below.

Note also that you may be interested in downloading the demo project to examine the source code and see how it works. This is true especially if you're looking to market something outside of the WordPress Plugin Repository.



Related Articles