6 Tips for Localizing Your WordPress Plugin

Localizing (or internationalizing) your WordPress plugin means making its text capable of being translated into other languages, without having to change the plugin itself. That’s something any plugin author should want to do, considering the huge communities of non-English-speaking WordPress users and the relative ease with which internationalization can be done.

Here is a list of things to keep in mind when you’re localizing your plugin, compiled from what I’ve observed plugin authors not often doing. (See John Godley’s blog entry for a thorough discussion of localizing details and Ronald Huereca’s good guide to creating the .po files WordPress uses for translating).

Here are my suggestions, proceeding from most commonly done to least often implemented.

  1. Remember the basics
  2. Include the text domain
  3. Load the domain at the right time
  4. Make good use of string formatting
  5. Handle plurals correctly
  6. Resolve ambiguities with comments

Remember the Basics

WordPress has two main localization functions: __ and _e. Wrap readable text in __ when you want just the text output (without printing it to the screen) and _e when you want to print, or echo, it. Examples:

<h2><?php _e('This is a printed header','my-plugin'); ?></h2>
$variable = __('This string or its translation will be saved in the variable','my-plugin');

When you’re internationalizing your text, try to imagine how it will appear to a translator. Below is how the translation file for one of my plugins appears in Poedit, a popular .po files editor. As you can see, each localized line appears by itself, out of context. Keep that in mind as you localize.

poedit screenshot

Because localized strings of text can seem disconnected when viewed by a translator, plugin authors should try to keep discrete thoughts together. Disjointed strings of text can be difficult for a translator to put back together in another language.

Don’t let markup or style be overly dependent on the structure of English. For example, a number of languages read from right-to-left instead of left-to-right; an interface that assumes priority on the left, for example, could confuse international users.

Include the Text Domain

Throughout the core WordPress files, you’ll see that only one parameter is passed to the localization functions. In the example below, it’s the string of text “Log out of this account.” The second parameter, the text domain, is omitted, because core WordPress just uses the default domain.

<?php _e('Log out of this account') ?>

But your plugin needs to specify its own domain, as the text you’re translating isn’t likely to be in the core WordPress translation files. The plugin text domain is an arbitrary string unique to your plugin; most authors use the plugin file name minus the “.php” extension. The following line appears in the WP-DB-Backup plugin, which happens to use the file name “wp-db-backup.php.”

__('Backup Complete!','wp-db-backup')

Load the Domain at the Right Time

For plugin localization to work at all, a plugin must load the .mo file by calling load_plugin_textdomain at some point. However, many plugins load it too soon. It’s a good idea not to call load_plugin_textdomain any sooner than the WordPress “init” action event, so that the plugin will work with other internationalization plugins, plugins which might be doing things that need priority. In the following example, “myplugin” defines a function that is executed at the “init” event:

function myplugin_init() {
     load_plugin_textdomain('my-plugin');
}
add_action('init', 'myplugin_init');

Make Good Use of String Formatting

It’s easy for native English speakers to forget that other languages don’t have the same syntax as English. Let’s say we want to internationalize output that in English has the form of the following:

ERROR Code 102: username is a required field

There is a bad way to do it (though not uncommon–this is a lightly modified example from an actual plugin):
$error = __('ERROR Code ','my-plugin') . $code_number . ':' . $field_name . __('is a required field','my-plugin');

Here is a better method:
$error = sprintf(__('ERROR Code %1$d: %2$s is a required field','my-plugin'),$code_number, $field_name);

The first, bad, example chops the sentence into parts, which might not work independently in another language or might confuse the translator viewing a series of cryptic phrases. As much as possible, try to keep a distinct thought within one localized line.

To do this, the second, good, example above uses PHP’s formatting function, sprintf. Translators would see the line “ERROR Code %1$d: %2$s is a required field” and know that wherever in the sentence the numeric error code should appear, they should insert “%1$d,” and insert “%2$s” wherever the required field string should be.

Handle plurals correctly

Sometimes in the case of handling plurals, string formatting does not provide sufficient flexibility. Let’s say you need to be able to translate a string like this:

3 podcasts available for downloading

String formatting won’t allow you differentiate between the singular “podcast” and plural “podcasts.” Instead, you can use __ngettext. __ngettext accepts four parameters: the singular version of the string, the plural, the actual number, and the text domain. So we could localize the above example like so:

__ngettext('%s podcast available for downloading', '%s podcasts available for downloading', $podcast_count,'my-plugin');

Resolve Ambiguities with Comments

Sometimes an English word has different meanings depending on its context. In WordPress, for example, the English word “editor” can mean both the user role (someone who has editing capability) and the text-area where one writes a post. In other languages, those different meanings have different words, so localization needs a way of distinguishing them for a translator. WordPress’s _c function allows you to provide that context.

Use _c just as you would __, except that if you insert a pipe—i.e. “|” —everything including and following the pipe will be ignored in the output, allowing you to use the pipe to demarcate comments. The following two lines output the same in English, but the piped comments allow one to present context to the translators.

__c('Editor|role');
__c('Editor|rich-text textarea');

6 Trackbacks

  1. [...] 6 Tips for Localizing Your WordPress Plugin by Pressed Words [...]

  2. [...] 6 Tips for Localizing Your WordPress Plugin · Pressed Words – [...]

  3. By Plugin Localisation Resources | Hugh Johnson on August 24, 2009 at 4:03 am

    [...] Austin Matzko (Pressed Words) provides a succinct summary of internationalisation, including a look at Poedit, a cross platform editor for the translation [...]

  4. By Waarom load_plugin_textdomain() niet werkte… on September 7, 2010 at 7:14 pm

    [...] Na deze doe-het-zelf ontdekking vond ik andere artikelen op het internet — is het niet altijd makkelijker te iets vinden wanneer je weet waarnaar je zoekt — over dit onderwerp. Eén daarvan muntte uit in volledigheid en hoewel het in het Engels is, wil ‘m zeker aanbevelen. Voor diegenen die zo’n beetje alles willen leren wat je moet weten om een plugin geschikt te maken voor meertaligheid: 6 Tips for Localizing Your WordPress Plugin [...]

  5. [...] beetje alles willen leren wat je moet weten om een plugin geschikt te maken voor meertaligheid: 6 Tips for Localizing Your WordPress Plugin Delen:FacebookTwitterMoreE-mailPrintPress ThisRedditLinkedInStumbleUponDigg Dit bericht werd [...]

  6. [...] that want to learn just about everything one needs to know when localizing a WordPress plugin: 6 Tips for Localizing Your WordPress Plugin This entry was posted in WordPress and tagged internationalization, load_plugin_textdomain(), [...]

8 Comments

  1. Posted September 28, 2008 at 6:40 am | Permalink
    Matthias

    Great tips! Going to use them for i8n support for wp-mollom right now :-)

  2. Posted July 7, 2009 at 1:18 pm | Permalink
    5ubliminal

    http://blog.5ubliminal.com/129#plugin-localization … try an alternative to your method, alternative that requires no .MO file.

    Cheers.

  3. Posted March 22, 2013 at 3:56 am | Permalink
    givenchyt-shirt

    Richer à établir veste est T ShirtGivenchy

  4. Vane
    Posted May 9, 2013 at 8:05 am | Permalink
    Vane

    Here is good a tool for localizing anything: https://poeditor.com/. It has its own wordpress plugin, so it’s really handy.

  5. Posted June 9, 2013 at 3:23 pm | Permalink
    http://www.1-

    hello there and thank you for your info – I have definitely picked up something new from right here.

    I did however expertise a few technical points using this site, since I experienced to reload the web site a lot of times previous to I could get it
    to load correctly. I had been wondering if your web host is OK?

    Not that I am complaining, but slow loading instances times will very frequently affect your placement in google and
    can damage your high quality score if ads and marketing with Adwords.
    Well I’m adding this RSS to my e-mail and can look out for a lot more of your respective intriguing content. Ensure that you update this again soon.

  6. Posted July 20, 2013 at 5:18 pm | Permalink
    wordpress Leren

    I don’t leave a response, however I browsed a few of the remarks here 6 Tips for Localizing Your WordPress Plugin · Pressed Words. I actually do have 2 questions for you if it’s okay.

    Is it simply me or do a few of the responses look like they are left by brain dead visitors?
    :-P And, if you are writing at additional social
    sites, I would like to keep up with anything new you have to post.
    Could you post a list of the complete urls of all
    your social sites like your Facebook page, twitter feed, or linkedin
    profile?

  7. Posted January 31, 2014 at 5:58 am | Permalink
    wordpress deveolper

    While the default out of the box setup is designed to be run as a blog, Word – Press
    is actually capable of far more. The best thing about WP customization
    is that you do not need the help of any professional to incorporate these simple features on your website’s web pages.
    Apart from this, a developer should always consider of building a public theme, developing a plugin, contributing a patch,
    and debugging.

  8. Posted June 13, 2014 at 9:40 pm | Permalink
    film en hd

    Fantastique post, pérennisez comme cela

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*