How to Localize a WordPress Plugin and Make it Translation Ready

Localizing your plugins makes sense if you want to reach the widest audience possible. After all, two-thirds of WordPress users live outside the US.

It only takes a little effort to make your plugins translation ready and is easier to do than you might think.

This is the fourth post in a series on translating WordPress. Over the next week I’ll feature a new post every day on translating different aspects of WordPress. If you have any requests please me know in the comments below.

Last week we looked at localizing WordPress themes to make them translation ready. In this post I’ll show you how to localize your plugins and make them ready for a translator to work his/her magic. If you’ve read the post on localizing themes, you’ll find the steps in this post much the same.

This post is part of our Translation Week series:

Feature image world

As I’ve covered in previous translation posts, WordPress uses the GNU gettext localization framework for translation and there are three types of files used in the framework: POT (Portable Object Template) files, which contain the text ready for translation; PO (Portable Object) files, which contain the translated text; and MO (Machine Object) files, which are PO files converted into a machine readable format.

Getting to know what these files are and how they work is important to understanding the translation process.

Add a Text Domain

Localizing plugins is much like localizing themes in that you’ve got to tell WordPress where to find your language files by adding a text domain.

You’ll need to add the following function to your plugin’s main file:

1
load_plugin_textdomain('yourplugin', false, basename( dirname( __FILE__ ) ) . '/languages' );

Change “yourplugin” to the name of your plugin and “basename” to the location in your plugin’s folder where you want to save your translation files. I would recommend creating a “Languages” folder in your theme directory and saving your files there.

But you can’t just stick that code anywhere – the load_plugin_textdomain function should be called in the WordPress init hook, like so:

1
2
3
4
5
6
7
8
function ap_action_init()
{
// Localization
load_plugin_textdomain('domain', false, dirname(plugin_basename(__FILE__)));
}

// Add actions
add_action('init', 'ap_action_init');

Localize Your Plugin

Now you’re ready to start localizing your plugin. You’ll need to edit the text strings in your plugin files and turn them into functions so they are translatable. To do this, you need to wrap them in a __() function call:

1
<?php echo '<h2>Hello world!</h2>'; ?>

becomes

1
<?php echo '<h2>' . __('Hello world!', 'yourplugin') . '</h2>'; ?>

If you code echoes the string to the browser, use the e_() function instead:

1
<?php echo 'Hello world!'; ?>

becomes

1
<?php _e('Hello world!', 'yourplugin'); ?>

You can also wrap regular text:

1
Hello world!

becomes

1
<?php _e('Hello world!','yourplugin')

Don’t forget to replace “yourplugin” with the name of your plugin.

Create a POT File

The next step is to create a POT file. POT files are often created by plugin authors and included with themes so translators can translate the plugin.

Like the previous translation posts in this series, we’re going to use Poedit, an easy to use open source program available for Mac OS X, Windows and UNIX/Linux, to create our POT file.

1. Install Poedit.

2. Open Poedit and go to File > New Catalog.

3. In the Catalog properties window, enter your project’s information.

Poedit plugin information

4. Next, go to the Sources paths tab where you’ll need to enter the path for the folder Poedit will use to search for source files containing translatable text. Earlier in this tutorial I recommended creating a “Languages” folder in your plugin directory and saving your files there. So in this instance the base path would be “../”

5. Click on the Sources keywords tab. Here, we need to define the functions we used to localize the text in our plugin files, __() and _e().

Poedit sources

6. After you click “OK” you’ll be asked to name and save your POT file. By default, Poedit will want to save your file as a .po file but since the two file types are identical you can get around this by simply choosing to save the .po file as a .pot file. Name your file after your plugin, give it a .pot extension and save it in a folder named “Languages” in your plugin directory.

7. When you click “OK” Poedit will scan the folders you specified in the Sources paths tab and will list the localized text.

8. Last step – save your POT file.

Now your plugin is translation ready.

Come back tomorrow for a run down on how to translate translation-ready plugins.

Have you ever localized a WordPress plugin to make it translation ready? Was it easy/hard? Tell us in the comments below.

Image credits: LukePricePhotography.

Code credit: WPEssence

Comments (5)

  1. I agree with @luka_peharda above, although a great topic that deserves a lot more attention, I think that this article does not offer an awful lot.

    The beginning (explaining about the textdomain) is confusing at best and I think that if a plugin would only contain strings like `Hello World!` then almost all plugins would already be internationalized.

    Most plugins however contain lots of code strings and it simply is a bit more complex to internationalize those.

    Furthermore I think that although nice that PO-Edit is introduced, it doesn’t have an awful lot to do with making a plugin translation ready.

    I think it would have been nicer if you had split this article up in a few different ones, which then would have given the chance to talk more in-depth about the different aspects.

  2. Raelene,

    I am trying your tutorial in my project. But my poeditor does not recognize _e() keyword. Any idea, what should i do? I really stuck at this point.

Participate