Localizing a WordPress Plugin Using poEdit


Localizing a WordPress plugin enables your plugin to reach widest possible audience. Fortunately, WordPress makes it rather simple for plugin authors (and theme authors) to ensure their work is available in many languages.

This post will go over the steps that are necessary from a plugin author’s end to make it easy for others to translate a plugin. For those then wishing to translate, I will go over a program called poEdit, which will allow you to translate the plugin for your use and for others.

The Benefits of Localizing a Plugin

The more languages your plugin is in, the more people that can download and understand it.

If a plugin is popular enough, you’ll have people volunteering to translate in order to adhere to a different part of the world. The hard way would be someone going through your code after each release and translating word for word. However, there is an easier and more portable way to translate: the .po file.

With the .po file, anybody can translate your plugin as long as they are familiar with the original language. And if you make any changes to the plugin’s source, a user doesn’t have to dig through your code to re-translate. The translations are preserved in the .po file and all the user has to do is update the .po file in their language.

Preparing a Plugin for Localization

WordPress makes use of GNU gettext for translations. WordPress has two functions that can be called by plugin authors: _e, and __. Every time you output text to the user, you should use one of the two functions.

  • __($message, $domain) and _e($message, $domain)
  • Both the above functions take in a $message as the first argument and an optional $domain as the second. For plugin and theme authors, the second argument is not optional and should be a name unique to your plugin or theme. For example, if you have a plugin named WordPress Automatic Upgrade, you could probably use WPAU.

According to the WordPress Codex, the __ function should be used if text is going to be used in a calculation.

Loading the Localization File

After ensuring the text outputted to the user is ready for localization, you must also setup your plugin for loading in the appropriate .mo file. The .mo file is a compiled .po file, which poEdit automatically generates upon a save.

The code inside your plugin would look something like this:

load_plugin_textdomain('your-plugin-domain', "/wp-content/plugins/your-plugin-directory/");

  • load_plugin_textdomain($domain, $path)
  • The $domain variable is the same $domain variable you used in the __ and _e functions. The $path is relative to the ABSPATH variable as defined in your wp-config.php file. If your plugin doesn’t have its own directory, you can leave the $path variable empty.

    One thing to note here is that any generated .mo files will have to have your domain as a prefix to the file. For example, if you plugin’s domain is WPAU, then the .mo file would be named (assuming the translation is in German).

Using poEdit to Translate

There’s already a good step-by-step tutorial on how to use poEdit to translate a plugin or theme, but I’m going to use a real-world plugin to show you the steps.

Step 1: Download poEdit

Head over the poEdit project page and download yourself a copy. The install is painless as well.

Step 2: Find a Plugin to Translate

Find your own (or another) plugin to translate. For this example, I’ll be using a plugin I wrote called Ajax Edit Comments.

Step 3: Open up poEdit and go to File -> New catalog…

After the ‘Settings’ dialog comes up, enter your project’s name. In my case, my project is named WPAjaxEditComments. I also went ahead and gave it a UTF-8 charset.

poEdit New Catalog Settings
You’ll be presented with a Settings dialog after selecting File -> New catalog…

Step 4: Enter Your Plugin Path

While still having the ‘Settings’ dialog open, go to the ‘Paths’ tab and click the icon for new item. Assuming that your plugin resides in its own sub-directory and that you will save the .po in this sub-directory, enter “.” (this tells poEdit to scan that directory and all sub-directories for your plugin).

poEdit Settings Paths

Step 5: Set up the Appropriate Keywords

Since WordPress uses the _e and __ functions for localization, you need to let poEdit know that is what it should look for. Click on the ‘Keywords’ tab and input both _e and __ as keywords. To enter a keyword, click on the ‘New Item’ icon.

poEdit Settings Keywords

Step 6: Click Okay and Let the Translating Begin

Click the “Okay” button and save the .po within your plugin’s directory. What you name the file right now is not important, but it will matter when it comes to translating.

After you have saved the .po file, a dialog will show showing all of the matches it has found.

poEdit Update Summary

If you do not plan on translating the plugin, you can go ahead and save the .po file and distribute along with your plugin to enable other translators.

Step 7: Translate the Plugin

Once all the matches are pulled in, it’s time to translate the plugin. Simply find the text you want to translate, and add in your own language.

poEdit - Translate
From this screen, you can translate the plugin

Step 8: Save the Catalog

Remember the $domain that was mentioned earlier in this post? What if, for example, I want to generate a Spanish translation file? I’ll want to save a file with the $domain as a prefix, and the locale as a suffix. In this case, my domain is WPAjaxEditComments and my locale is es_ES. I would save my file as: WPAjaxEditComments-es_ES.

By saving the new file, I would automatically be generating a .po file that others can use, and a .mo file that can be read in through WordPress to localize the plugin.

Now if users have defined the appropriate WPLANG in their wp-config.php, their plugin’s options and output text should be in their local language.

German Translated Ajax Edit Comments
A German translation of Ajax Edit Comments (Thank you David May).


Localizing a WordPress plugin is a great way to reach out to a foreign audience. Localizing involves many people, including the plugin author to take the initial steps to ensure that the plugin can indeed be localized. Translators are required too, and their efforts to localize WordPress and WordPress plugins are tremendous.


Related Reading:




  1. gidibao (10 comments.) says:

    Ronald – great post!!!

    Thank you

  2. GaMerZ (24 comments.) says:

    I got a tutorial up quite some time also.

  3. Tim (1 comments.) says:

    Nice tutorial. As you already said, the same can be done with wordress themes. I have a tutorial for themes here: Localizing WordPress Themes

  4. Ronald Huereca (39 comments.) says:

    Thank you. Glad you found it useful.

    GaMerZ, Tim,
    I added you onto the end of the post as related reading. Thanks for pointing those links out. Most of what I could find regarding localization was unanswered support questions.

  5. John (2 comments.) says:

    Nice work Ronald! You might also be interested in Localizing a WordPress Theme or Plugin and Translating WordPress into another language.

  6. Can Erten (1 comments.) says:

    or you can use PO file integrator, if you have some localisation problems with your server.
    What it does it generates the localised code in the source code

  7. Ronald Huereca (39 comments.) says:

    Thanks for the links John. Hopefully there is now enough information here to answer most questions regarding localizing WordPress plugins and themes.

  8. Jamie Fehr (1 comments.) says:

    It’s worth noting that the .mo for a THEME translation won’t have the text domain as part of the file name. You should just save it as for example.

  9. Gregg says:

    NEED help getting multiple languages working. Will PAY! urgent timing.

  10. Martti says:

    Hey Ronald,

    this is by far the best guide to localize WordPress and to use poEdit. Thank you!

    Still, I am having trouble localizing Carrington Mobile. That is: a plugin and a theme. I managed to translate Carrington Mobile theme and plugin. At least almost. There are still some words here and there which didn’t appear on the poEdit.

    For example:
    about, more ?, Return to the Mobile Edition, Categories: Uncategorized
    are still untranslated. Any suggestions?

    It appears there are two project names: “carrington” and “carrington-mobile”. So, I should make two sets of .po and .mo files. Am I missing something? Where should I put the different files or should I somehow merge them? And how is this possible?

  11. rudolf (1 comments.) says:

    Hi, any chance somebody still looks into this post and these comments??
    I have one silly question regarding the PATHS
    If i have PoEdit in the usual Programs folder of Windows, and start it and get to the settings where i have to put in the paths it doesn’t just work with a dot as path, seems anyway impossible if i have the actual plugin lets say in
    so, what exactly do i have to do for PoEdit to go and fetch everything,if i use the above path as the default path i at least don’t get an error message anymore, but it doesn’t fetch anything either.
    Also, the support of PoEdit itself said that i could use multiple paths if i have plugin files in more than 1 directory / folder, but i have no clue where or how to set those in either, tried to put them all into default path, seperated by comma like keywords in an html meta – did not work, i am kind of completely lost on how this program fetches the stuff out of all those PHP files (that are all setup for transaltions).

    Any help??

    P.S. this
    Notify me of followup comments via e-mail
    where did you get this from, part of the Theme you are using or a special plugin for comments??? (love it!)

  12. Steve says:

    Hello, I want to handle 3 languages in my wordpress instalation, in your tutorial you only show for 2 languages, how can I connect the translations of the 3 languages, for example english, spanish and italian, how I know what is the translation from english to spanish, spanish to italian and so on !!

    I’ll appreciate your help, thanks.

    • Rudolf (1 comments.) says:

      It’s been a while since i did my own localizations, but if i understand you right you probably did not understand how PoEdit works.
      You only need to know how the translation from one language into one other works!!
      Let’s say you have an original in English.
      You make the translation first into Spanish and save the spanish files as (or es_ES.po) – done.
      Than you take once again the original English and set up PoEdit (as described above) for the next language (that is the important difference), so that you then have it to translate everything into your next language of choice, say Italian and in the end you save as or it_IT.po
      and so on, sorry simplified explanation, there are a few twists and tricks along the way i can not recall anymore, but that is the essential


  1. elarequi (Eduardo Larequi) (2 comments.) says:

    @onio72 y en (vale también para los temas).


  1. […] Weblog Tools Collection » Blog Archive » Localizing a WordPress Plugin Using poEdit (tags: wordpress plugins tutorial localizing) […]

  2. […] Localizing a WordPress Plugin Using poEdit – ??? ???? ???? ????? ????? ?????? ????????. […]

  3. […] Localizing a WordPress Plugin Using poEdit (tags: wordpress) […]

  4. […] ????? ??????????? ????? ???????? – Localizing a WordPress Plugin Using poEdit […]

  5. […] ????? Localizing a WordPress Plugin Using poEdit?????????????? […]

  6. […] is a gettext editor. It is available for all OSs. See this tutorial for a […]

  7. […] Hoe je plugins kan vertalen met poEdit. […]

  8. […] Localizing a WordPress Plugin Using poEdit […]

  9. […] ????? Localizing a WordPress Plugin Using poEdit?????????????? […]

  10. […] Localizing a WordPress Plugin Using poEdit Denne artikel beskriver hvordan man kan oversætte plugins ved hjælp af værktøjet poEdit. Læs artiklen og kom i gang med at lave danske oversættelser af dine yndlings plugins. […]

  11. […] 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). […]

  12. […] you want to help translate and internationalize WordPress Plugins, read the article by Weblog Tools Collection on “Localizing a WordPress Plugin Using poEdit”, with tips for helping WordPress Plugin authors to make their WordPress Plugin international, […]

  13. […] If you would like to read this tutorial in english, please visit Weblogtoolscollection. […]

  14. […] the help of Ronald Huereca, I learn how to use poEdit to localize wordpress component. What a great tool in translating, as easy as anyone knows how to […]

  15. […] poedit – it’s cross-platform and works well. I won’t get into too much detail – here is an excellent tutorial – just replace ‘__’ with ‘_’. btw, the Irish for “Pages” is […]

  16. […] of the hurdles I ran into in creating my own error manager was error localization. The WP_Error class makes localizing error messages extremely […]

  17. Project M says:

    […] his help, the bugs reported in the translation thread for my themes, and a great article about localization from Weblog Tools Collection, I’ve managed to start understanding this idea. I’m now […]

  18. […] you need to read the best article there is around on localization from Weblog Tools Collection. I won’t bother going into the details of this process since the […]

  19. […] Localizing a WordPress Plugin Using poEdit « Weblog Tools Collection […]

  20. […] a plugin or theme is relatively straightforward, but JavaScript presents its own difficulties since we can’t easily call the PHP functions […]

Obviously Powered by WordPress. © 2003-2013

page counter