Localizing Your Scripts

When adding scripts to WordPress, you will inevitably run into a small, but painful, issue of localization. For the cool kids, localization is basically internationalization (or i18n for short).

Localizing a plugin or theme is relatively straightforward, but JavaScript presents its own difficulties since we can’t easily call the PHP functions necessary (which is one reason authors embed JavaScript in PHP files).

Since embedding JavaScript in PHP files is never a good technique, we use localization to save the day.

When using Ajax with WordPress, the JavaScript file will need to know the exact location of the WordPress site it is to interact with.  You can’t hard-code this in unless you embed, so how does one get the location? Furthermore, if you display anything with JavaScript, chances are your users will want the strings to be translatable. I’ll show you in a later chapter how to allow translations for your strings without having to do the localization step.

Fortunately, WordPress provides the ultra-handy wp_localize_script function.

wp_localize_script

The wp_localize_script function takes in three arguments:

1. Script handle (the script you want to attach the localization to).
2. Object name (the object you’ll be referencing in JavaScript).
3. l10n (an array of items you want to be localized).

Script Handle

The handle argument will be the same handle you use for your script name when using wp_enqueue_script.

For example, if you have a handle of my_script, you would use the same name when calling the wp_localize_script function.

Object Name

The object_name argument is a string that tells WordPress to create a JavaScript object using the name you specify.

It’s important that the string you pass is as unique as possible in order to minimize naming conflicts with other scripts.

For the upcoming example, our object name will be swpajaxp.

l10n

The l10n argument is an array of strings you would like to localize.

Within this array, you create an array key and an array value. The array key will be what you reference in your JavaScript file, so please keep it short (and no spaces or funky characters!).

Example of wp_localize_script

Say, for example, we have enqueued a script with the handle: sample_wpajax_plugin. Let’s also make up an object name that we can use in JavaScript. Let’s use swpajaxp (short for Sample WP Ajax Plugin). Then, we have to decide what to pass as an array. In the example below, let’s choose a PHP version and a URL to WordPress’ admin-ajax file (I’ll go over admin-ajax in a separate chapter).

If we re-use the code I went over in Chapter 4, which you can find at https://github.com/wpajax, it’ll look something like this:

wp_enqueue_script(
	'sample_wpajax_plugin',
	SAMPLE_WPAJAX_URL . '/js/init.js',
	array( 'jquery' ),
	SAMPLE_WPAJAX_VERSION,
	true
);
wp_localize_script(
	'sample_wpajax_plugin',
	'swpajaxp',
	array(
		'phpversion' => PHP_VERSION,
		'ajaxurl'    => admin_url( 'admin-ajax.php' ),
	)
);

Now in our JavaScript file, we can access the swpajaxp JavaScript object because wp_localize_script outputs the necessary object and variables before our script is loaded. We can then get some variables that are essentially being passed from the backend.

Let’s modify our init.js file and output these to the console. For reference, here’s what’s currently in our init.js file from Chapter 4, which is just a simple “Hello World.”

jQuery(function($) {
	console.log('Hello World');
});

Let’s modify this to output our new variables to the console. Here’s what the code would look like:

jQuery(function($) {
	console.log('Hello World');
	console.log(swpajaxp.phpversion);
	console.log(swpajaxp.ajaxurl);
});

See how we’re just accessing the swpajaxp object and referencing its members using dot notation? It’s as simple as that.

Here’s what you should expect to see in your developer console:

It should output the current PHP version you are running and a path to WordPress’ admin-ajax file (more on that later I promise).

And it’s as simple as that. You can view the completed code at https://github.com/wpajax/chapter-5. Try playing with adding more variables to wp_localize_script and outputting them to the console.

Conclusion

The wp_localize_script function is useful for getting PHP functionality to show up on the front-end and its great for internationalization, which I’ll go over in a later chapter. In the next chapter, we’ll take a break from JavaScript (be thankful) and I’ll show you how to load CSS properly so you can slowly begin building your Ajax-based app and make it look pretty.