How To Internationalize WordPress Plugins

During my time on working on the WordPress Plugin Boilerplate, I’ve had some really good discussions with Gary Jones about some of the practices and conventions used throughout the code.

Up until this point, I’ve traditionally included a plugin.po file with each of my plugins to make it easy for translators; however, Gary’s been kind enough to point out the a .pot file should actually be included.

From a discussion on GitHub:

If you read the Codex page you linked to, you’ll see that it explains that .pot is the correct extension to use for the original translation file, since it is the template from which .po and .mo files are generated.

I’m not above admitting when there’s something I’ve not been doing correctly – after all, most developers should constantly be improving right?

At least I hope that’s the case.

Luckily, there are tools that make generating this catalog trivially easy so I thought I’d provide the steps necessarily to internationalize WordPress plugins specifically how I did so for the latest release of the Boilerplate.

Internationalize WordPress Plugins

This is actually a two-step process both of which will be covered here.

First, we’ll need to download the tools from a Subversion repository necessary to generate the .pot catalog, then we’ll actually use said tools to process our plugin.

1. Download i18n-Tools

The WordPress Codex provides an article specifically about i18n for WordPress that’s worth a read (in it’s entirety, I might add :)).

They also provide a Subversion repository of the tools necessary to generate a catalog. Of course, it’s a bit of pain to actually download the trunk (not to mention, that isn’t how repositories are supposed to work, right?)

So to checkout the i18n Tools, load your favorite Subversion client. Mine is Cornerstone so that’s what the screenshots will show:

The Cornerstone Homescreen
The Cornerstone Homescreen

Some Subversion clients should be able to detect the URL of a Subversion repository when it’s on your clipboard, but if not, make sure that you have the following URL readily available:

Next, click on the “Add Repository” option in your Subversion client:

Adding the i18n Tools Repository
Adding the i18n Tools Repository

Because this is an open repository, no login credentials are needed. Simply select “HTTP” as your protocol, then paste in the URL from above.

Make sure that you have the tools/trunk path selected as your repository path. After that, add the repository and it should pull everything down into your active list of repositories.

From there, you can perform a check out of the code. The internationalization is somewhat arbitrary but I’m a fan of placing it in the wp-content/plugins directory.

Checking out the i18n Tools
Checking out the i18n Tools

The reason for placing it in this directory is because it makes it much easier to work from the command line when generating the .pot files.

And since we’ll be doing that in the next step, it’s that much more convenient.

Once the tools have been checked out, you should have a i18n-tools directory in the wp-content/plugins directory. At this point, we’re ready to generate the .pot file for the plugin.

2. Generating The POT FIle

Once you’ve checked out the i18n Tools, navigate to the wp-content/plugins directory using your command line:

Navigating To i18n Tools
Make sure you’re in the plugins directory.

Once you’ve navigated to the proper directory, you need to issue a single command in the terminal in order for the i18n Tools to generate the .pot files:

php i18n-tools/makepot.php wp-plugin plugin-directory/

Generate the POT File
Generate the POT File

So, as you can see, in the case of my plugin, I executed the following command:

php i18n-tools/makepot.php wp-plugin WordPress-Plugin-Boilerplate/plugin-boilerplate/

Depending on your PHP configuration, the console may generate some warnings about the date format – that’s okay. It’s nothing that prevents the file from being properly generated.

Anyway, this will generate plugin-boilerplate.pot in the root of the wp-content/plugins directory. Obviously, this isn’t where you want to keep the file so simply move it to the lang directory (or languages or whatever you happen to call your directory) and you’ll be good to go.

From here, translators can use their tool of choice to generate the .po and .mo files for their plugin.

30 Replies to “How To Internationalize WordPress Plugins”

  1. I could be totally wrong here but why not use PoEdit for this? Simple open .po which you’ve done and save it as .pot.

    Or if the plugin is in the wp repo you can generate .pot file in

    I actually have never needed .pot file and I do a lot of translation work.

    What is more valuable to me in your great boilerplate plugin that you can save you .po/.mo files in wp-content/languages/plugin-name-locale folder. That way I don’t loose my translations anymore when I update the plugin or I can do custom translations for custom jobs.

    1. I’m a fan of POEdit myself, which I mention here; however, since releasing the latest version of the Plugin Boilerplate, I’ve been having a discussion in one of the issues that lead me to ultimately to choose .pot.

      If you read the Codex page you linked to, you’ll see that it explains that .pot is the correct extension to use for the original translation file, since it is the template from which .po and .mo files are generated. Yes, POEdit handles them fine, since they are both text files, but other software may not (some of the WP translation plugins may be looking for a .pot extension for instance).

      POEdit can read those files, but others tools can as well. I want the Boilerplate to be as universally applicable as possible, so I’ve opted to go with the most compatible file format.

      And for what it’s worth, I’ve always used po myself until now. Learn something new (or valuable) every day, huh? :).

    1. POEdit is definitely an easy way to generate a POFile, but a not everyone uses it, you know?

      As such, I’ve just been trying to provide steps for an alternative way to generate pot files that’s agnostic to any particular program and that just uses a tool provided in the Subversion repository.

      Not trying to say this way is necessarily better. Just an alternative way for those who don’t wanna use POEdit :).

      1. One drawback of using PoEdit is that is will not recognize any /* translators: */ note that you have in your code. So if you have any translators notes and want them to be included in your pot-file, the i18n tools is the way to go.

    1. Why am I not surprised you did this?

      Every time there’s something cool or something really useful available, you (and or Schinkel) go and either level it up a bit and/or have a solid opinion on it ;).

  2. I applaud you for adding images. It is difficult for people like me who never use command line to understand ny following the instructions on the codex.

    I did get it to work on my Windows PC. I needed to install php first. Did you need to do that on the mac too?

    One advantage of makepot over POEdit is that makepot is able to pull the meta data like Page Template titles in themes and for plugins it would be the descriptions etc.

    So that it is translated “Text Domain: my-text-domain” needs to be added to the header.

    1. I’m glad the images helped – I often include them but am never sure how people respond to that versus having to entry a variety of commands in the terminal so thanks for sharing. Means I’ll keep it up :).

      I didn’t need to install PHP on a PC, but I did on a Mac – I use MAMP to manage all of that stuff for me, so it was really easy to get going.

      One advantage of makepot over POEdit is that makepot is able to pull the meta data like Page Template titles in themes and for plugins it would be the descriptions etc.

      Yeah – that is an advantage. Similar to what Middlesister mentioned above!

    1. Thanks for sharing the link, Piet.

      The thing about Internationalization is that there are a number of different tools available and different people like different things. I’ve done what I can to keep it as general as possible, but you know how it goes – always one or two things that’ll need to be tweaked ;).

  3. I also want to suggest a tool that competes with poedit and goes on top of it, to my mind: It has a very simple UI, it works online, no need for download, and it has many helpful features. On top of that, it has its own wordpress plugin to work with.

  4. First, congratulations, you’re Boilerplate POT file is genius as it is simple. Its the only thing that made sense in what I’ve been trying so far!

    I can’t see how makepot.php would actually work given you’re suggested setup. The extract.php file ( used by makepot.php requires pomo/entry.php and pomo/translations.php so you have to make sure that you’ve got the wordpress wp-includes/pomo directory included as well.

    Beyond that as well, I also got an error “‘msguniq’ is not recognized as an internal or external command” in windows Windows because the makepot.php file calls msguniq which is a unix program (

    Even with the error it did generate the pot file in the plugins directory but I hadn’t realised that it did because of the error.

    However you’re Boilerplate POT file is still a step up because it assumes putting the files in the languages directory.

    1. I got the same error: sh: msguniq: command not found.

      I’m using Mac. Just like you said, there is still a .pot file generated. Will there be any problem if I use that file?

      1. Thanks, Tom. But Otto of WordPress says “This does not work for WordPress and the specific changes to the translation system. It is incomplete at best.” He goes on to say the only non-broken method is to use WordPress’s own makepot.php.

        1. Hey Robert, thanks for the heads up. Given this post is three years old, a good bit has changed since it was first written.

          I’m working on an updated set of articles specifically around i18n that you can see here.

          Even still, in this post I use makepot.php specifically which you can see in the line of the post that contains:

          php i18n-tools/makepot.php wp-plugin plugin-directory/

          Again, thanks for the heads up!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.