Internationalize your WordPress plugin

WordPress plugins allow you to easily modify and enhance your blog by bringing new functionality not otherwise available in the base code.

Using plugins works more effectively than trying to modify the overall core programming that makes up WordPress. Defined as a program or a set of functions written in PHP, plugins add specific features that can easily be integrated with the blog through the WordPress API.

If you have written a WordPress plugin, you can make it much more accessible by translating it into another language. This is known as internationalization.

Internationalization vs. localization

Before you can internationalize your plugin, you must know what it means. Also known as i18n, this means modifying the plugin so that other cultures that speak other languages can easily use your plugin.

Localization by contrast, is the actual process of modification.

There is more to internationalization than just translating the interface. For example, assumptions you have made about imperial units and metric units, punctuation such as using a comma to separate thousands instead of a period, as well as other cultural topics need to be addressed before you can properly localize your work.

While this is a guide that addresses preparing to localize a plugin, it is still important to keep these additional adjustments in mind.

Domains and initialization

Localizing your plugin means you need to come up with a text domain, keeping each one separate from the ones that WordPress uses or that other plugins have defined. Whatever you want to use for a text domain is down to you, but you will want to pick something both unique and sensible, related to what your plugin is about.

Before you can fully localize your plugin, you need to make it tell WordPress how it can find your strings. If the code does not already exist, you will need to insert something like the following line into your coding:

add_action( 'init', 'myFunction' );

This code communicates with WordPress to tell it to use the function called myFunction once it loads. This function then names your text domain to WordPress and teaches it how it can load the localized strings, which should appear similar to this:

function myFunction() {
 load_plugin_textdomain( 'mytextdomain', 'wp-content/plugins' );
}

The WordPress function load_plugin_textdomain informs WordPress that there is a text domain called mytextdomain, and the files that have the localized strings rest within the server folder wp-content/plugin. (Naturally, if you put your plugin files in a different folder and path, you will need to replace this with the appropriate path.)

International image via Shutterstock.

Preparing strings

Following the initialization, you will need to change the static strings to a function that permits WordPress to use the proper localized version of that string. After all, it does not work well to have WordPress pull the wrong language.

This function offers a short name that makes it easy to internationalize: the double-underbar function _(string, domain). The function has two parameters, the first being the default string the plugin uses should there not be a localized version available. The second parameter is the same text domain that you selected in the code earlier.

Prior to this step, your code may appear like this:

function addMyAdminPage() {
 add_options_page(
 'A Page Title',
 'A Menu Title',
 7, __FILE__, 'myAdminFunction' );
 }

After adding the code, it may seem like this:

function addMyAdminPage() {
 add_options_page(
 __( 'A Page Title', 'textdomain' ),
 __( 'A Menu Title', 'textdomain' ),
 7, __FILE__, 'myAdminFunction' );
 }

International image via Shutterstock.

Localization

With all of the preparation out of the way, you are finally prepared for the actual process of turning your WordPress plugin into multiple languages.

Creating a localization for your plugin requires making a .po file with a name similar to your plugin file name as well as the ISO 639 2-letter codes for each country and language. For instance, if your plugin were called examplename and you wanted to localize it to Spanish (European), it would appear as “examplename-es_ES.po”.

While the WordPress codex offers tools that can assist with localization, it is often better to simply go with the .po file from one plugin as a starting point. .po files are made of a single header and then translation pairs:

msgid "Options"
msgstr "Opciones"

The msgid is the standard string that appears in the double-underbar function you dictate. With the .po file created, you can use one of the tools WordPress offers to create a .mo file, which is the other file that WordPress requires.

Letting other translators help

Nobody knows every single language, so you’ll want to expand your resources and let other people help translate into other languages. However, you will need to undergo a special procedure to generate the necessary files to give to your translators since you do not want them to have your source code to accidentally break.

The file you want to give to translators is a POT file, which looks similar to this:

#: wp-admin/admin-header.php:49
msgid "Options"
msgstr ""

There are two ways to generate this file. If you’ve put your plugin into the repository, just head to the admin page and select “Generate POT file”. This file is what you will send to translators for them to localize, though you will likely want to send your plugin with it so translators do not need to ask you questions about the plugin.

If you do not have your plugin in the repository yet, you can visit the WordPress I18n tools directory and use the makepot.php script in the following manner:

php makepot.php wp-plugin the-plugin-directory

Keep in mind that you will need to install your GNU internationalization utilities package on your server before running this command.

International image via Shutterstock.

Testing

With all of your localized files in place, it is time to test them out and see if there is anything you forgot. Testing your localization means changing a simple line on your WordPress configuration in order to trick it into thinking it should use a different file. Change the file wp-config and locate the following line:

define ('WPLANG', 'en_US');

If this line did not previously exist, you will want to double check and see that your installation still works fine. If so, return to the file and modify the country and language code. With the previous example, this would be as follows:

define ('WPLANG', 'es_ES');

Finally, enable your plugin to test how it looks. Remember to go back to your original default language once you have finished testing.

Updating your plugin

With all of the changes that WordPress makes over time, your plugin may not be fully functional with subsequent updates. Make sure you always take the time to update your plugin whenever possible. Assuming you already have it hosted in the WordPress Plugin Repository, you can take some steps to add new features or update patches to your plugin over time. You may do this as frequently as you need to.

When you have finished updating your plugin and want to release the latest version, you will need to keep a checklist in mind:

• Test your plugin and guarantee that the newest version actually works properly. Make sure you keep in mind all of the different WordPress versions there are and test them out with every version as possible. Do not simply test new features since you may accidentally break older features as well.
• Go into the trunk folder and modify the header comment in the main PHP file so that you can update the version number. Make sure that you also change the version number in the readme.txt file in the trunk folder in the stable tag field.
• It is always wise to create another subsection of the changelog area of the readme.txt file so that you can briefly describe what is new in the latest release compared to the previous one. Whatever you put in here will be added to the change log tab on the page for your plugin.
• Make sure you make a new SVN tag as part of the trunk.
• Allow a few minutes for the system to register the new changes, and then head to your plugin page and to a blog that has your new plugin installed to verify that everything is properly updated. Keep in mind that these update checks can be cached, so it may be necessary to wait a little longer for it to fully update.

All in all, there is not much else to internationalizing your plugin into different languages. As long as you follow these steps carefully, you can localize your plugin into as many different languages as you need to.

Have you localized a WordPress plugin? What languages do wish were more frequently supported? Let us know in the comments.

Aidan Huang

Aidan Huang is a self-taught developer, designer and blogger. He is also the editor-in-chief at Onextrapixel. Follow him on Twitter @AidanOXP