If you’re a WordPress plugin author, you can reach a wider audience by providing translations of your plugin in languages other than English. For step-by-step instructions on how to do that, read on.

Definitions

First, some definitions: Internationalization (or for short, “I18n”) is the process of modifying software so that it can be used in other cultures. Localization refers to the actual process of modifying software for a particular language and/or culture.

Caveat

I18n often involves more than just preparing software so that you can easily translate its interface; you may also find that your assumptions regarding units (imperial vs. metric), punctuation (using “,” as a thousands separator instead of “.”), and other cultural topics need to be reviewed in order to successfully localize your plugin. I’m going to discuss the portion of i18n that will allow you to prepare your WordPress plugin so that its strings can be localized, but you should also keep in mind that you may need to make other adjustments to your plugin in order for it to function well in the context of another culture.

Step 1: Choose a domain name

I’m not talking about Web site domain names here, but rather a text “domain” that will help keep your localized strings separate from localized strings used by other plugins or by WordPress itself. You can choose whatever you like for your text domain name, but it should be unique and also relevant to your plugin. For example, I chose the domain name “copyright” for my WordPress Copyright Plugin.

Step 2: Initialization

Before your plugin can use its localized strings, it needs to tell WordPress how to find them. If you don’t already have a centralized plugin initialization routine in your plugin source code, you’ll want to add a line similar to the following:

add_action( 'init', 'myPluginInit' );

This tells WordPress to call the function myPluginInit when your plugin is loaded. That function will tell WordPress what your text domain is and how to load localized strings, and it should look something like this:

// Initialize this plugin. Called by 'init' hook.
function myPluginInit()
  {
  load_plugin_textdomain( 'mydomain', 'wp-content/plugins' );
  }

The function load_plugin_textdomain is a WordPress function that tells WordPress to define a new text domain called “mydomain” (which you should replace with whatever text domain name you chose in step one), and that the files containing localized strings can be found in the folder wp-content/plugins. If your plugin lives in a separate folder you will probably want to put the localized string files in that folder as well.

Step 3: Prepare all strings

Next we need to change each static string to a function call that will let WordPress use the correct localized version of that string. The function has a special name that is both inobtrusive and short, in order to make it easy to internationalize strings; it’s the double-underbar function: __(str, domain). It takes two parameters; the first is the default string that gets used if no localized version is available, and the second parameter is the text domain that you selected in step one.

Here is an example of how your code might look before this step:

// Add the administrative page for the plugin:
function addMyAdminPage()
  {
  add_options_page(
    'My Page Title',
    'My Menu Title',
    7, __FILE__, 'myAdminFunction' );
  }

After this step:

// Add the administrative page for the plugin:
function addMyAdminPage()
  {
  add_options_page(
    __( 'My Page Title', 'mydomain' ),
    __( 'My Menu Title', 'mydomain' ),
    7, __FILE__, 'myAdminFunction' );
  }

Step 4: Localize

Now you’re finally ready to localize your plugin’s strings to another language. WordPress uses a technology called GNU gettext for string localization, which you don’t need to worry about except to know that you’ll need to create special text files that contain your localized strings which you then run through a tool in order to create the files that WordPress actually uses.

The WordPress codex has a tutorial on WordPress i18n and localization that is mostly aimed at developers who want to localize WordPress itself. However, that tutorial contains some useful links to further information on GNU gettext as well as the various tools that are available to create the requisite localization files. I recommend using poEdit because it is easy to use and has a decent user interface.

To create a localization for your plugin, you create a “.po” file that has a name based on your plugin’s filename and the ISO 639 2-letter codes for language and country. For example, if your plugin was named “myplugin”, and you were creating an Italian language localization, your localization strings file would be called “myplugin?it_IT.po”. Instead of using one of the tools mentioned above, it is often easier just to use a .po file from another plugin as a sample staring point. For an example, see my WordPress Copyright Plugin. Wikipedia has a brief overview of the .po file format, which basically consists of a header followed by string identifier and translation pairs such as the following:

msgid "Update Options"
msgstr "Aggiorni le opzioni"

The message “ID” is just the default string you provided in the double-underbar function call. Once you have created your localized .po file, use one of the tools mentioned above to create the “.mo” file that WordPress needs.

Step 5: Test

Now you’re ready to test your localized strings to see if you’ve forgotten anything, if any of the strings don’t make sense in context when translated, etc. To do this, we need to trick WordPress into thinking that you want to use the new localization. Edit your WordPress configuration file wp-config.php and find or add the following line:

define ('WPLANG', 'en_US');

If you had to add the line, test to make sure your WordPress installation is still working correctly. Then, when you’re ready, change the language and country code, for example:

define ('WPLANG', 'it_IT');

And then enable your plugin in the administrative interface. Once you’re done testing your localization, don’t forget to change your WordPress localization back to the original language that you want to use by default.

If you have trouble-shooting advice or questions, please feel free to leave a comment below. If you found this article useful, please consider leaving a donation via the PayPal button.