WordPress: How to localize your JavaScript code?

Update (on 17th July 2017) – see the bottom of the page.

In WordPress, while writing theme or plugin, you should always keep in mind localization. Maybe your theme or plugin become so popular and someone would like to translate it into another language? It’s easy for me to think about localization, because I write my themes and plugins using english language and I usually add polish translation, because I’m Pole. So it isn’t very hard to achieve.

Localization in WordPress is very easy. Let’s see one example from my plugin, Google Analytics Head. Plugins requires some information in the file header, like plugin name, description, author etc. There is also a place for text domain, it looks like this:

Of course it isn’t whole file, just a few lines from the top of the main file. I used analytics-head as text domain as you may see. Then I need to load text domain in init action. This is file inc/plugin.php and appropriate fragment looks like this:

Originally it is in the class, PLUGIN_BASE is set in other place, but it isn’t important here. We know how to do that. Then we may use localized strings as simply as that:

String “Settings” is ready to translate. It’s easy. But what should we do, when we want to use translatable strings in javascript? It isn’t much more harder, just a bit. Let’s write example plugin. This plugin will be very easy, just to show you the basics.

First of all, let’s write some frame code to see the plugin in Plugin menu. We may activate it as well. It won’t affect our WordPress since there are no code to do anything:

Now, let’s add a page on the back-end (as you may see, this plugin will work only on back-end). We may use whatever we want, as this is just an example… Let’s add a page to “Media” menu:

By using this code, we will get new “LocalizedJS” sub-menu item in “Media” menu. Please note that I used “edit_files” capability for control user access. This capability is originally assigned to Administrator (and Superadministrator on Network sites) role. Please click this menu, you should get almost empty page with title and one link.

Now we need to add javascript file with our code, to handle link clicking. Of course we will control $hook parameter to prevent loading our script on other pages, it’s only for us. We will also add JQuery dependency, because we are lazy and we like to use it 🙂

Our localized.js file should be located in the same plugin folder, the same path as main file and now it looks like this:

Now, when we refresh our page, we should get standard message box with “ready” text. Now let’s handle our click. We need to edit localized.js file this time:

Now we’ve got the same effect, but only when we click “Draw the answer” link. Please note, that we get rid of default link behavior (using preventDefault function) and we remove focus from our link (using blur function). So, what’s next? Well, we will use ajax to draw the answer. We will draw the number between 1 and 2. First, we need to handle our ajax call, let’s get back to localized-js.php file:

Now we may call our ajax, let’s go to ‘localized.js’ file:

So, this could be it! But unfortunately it isn’t. Why? Because our javascript code has strings and we can’t translate it… now. So, what to do? There is a special function: wp_localize_script. And this is the main part of this article. At last! So, let’s get back to our php file once again. I will save you whole code, just admin_enqueue_scripts method:

As you may see, now we can translate all messages in javascript file. Of course we need to make some changes on our javascript code:

And that’s it. Now we’ve got it all. Or… maybe not? Well, one last thing. Security. We should use two things to improve our security. First, we need to check user permission. Of course we will use edit_files capability, because we use it in the admin menu creation. It’s simple:

But this may be not enough. We should also check WP nonce field… And to do that, we also have to use our localization technique! Finally, our files should looks like this:

1. localized-js.php

2. localized.js

This should work.

Update, 17th July 2017

You may download this plugin on GitHub repository. There are a few more things – I added text domain loading and polish translation as an example, so you may switch your WordPress to polish (if you dare!) and see that it really works. If you want, feel free to add another translations by forking this repository. Have fun!