Software, Development, and WordPress

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.


  1. Julien LE THUAUT

    Hi, the .pot catalog can also be generated with tools like PoEdit, which includes parsers to detect internationalizable strings in the code. I use this tool for my plugins and it’s very simple to use.

    • Tom McFarlin

      Yep – that’s my favorite editor of choice and I discuss it more here.

      This is another alternative that provides the similar functionality albeit in a slightly different way.

  2. Sami Keijonen

    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.

    • Tom McFarlin

      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? :).

  3. Sami Keijonen

    I’m still lost. Isn’t Poedit for you easier way to generate .pot file?

    • Tom McFarlin

      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 :).

      • Sami Keijonen

        Now I got it! Sorry for being dumb:)

        • Tom McFarlin

          LOL, you’re not dumb! The way I see it, if it’s in the written word and a reader doesn’t get it, that’s the authors fault.

          Perhaps I could’ve clarified a bit more :).

      • Middlesister

        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.

        • Tom McFarlin

          I did not know this, so thanks for sharing. Definitely something that matters – and it is certainly yet-another-reason to dig the i18n tools package.

  4. John P. Bloch

    Nice! I built an abstraction of this into a bash command a while ago. You can find the code, with installation instructions here:

    • Tom McFarlin

      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 ;).

  5. grappler

    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.

    • Tom McFarlin

      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!

  6. Piet

    Nice article although I agree it could use some clarification here and there.

    Another way of generating a .po file is by using a tool provided by ICanLocalize (the company behind the WPML plugin). You can upload single files or an entire zipfile and it “spits” out a .po file with all the strings neatly in it.

    You can find it via:

    • Tom McFarlin

      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 ;).

  7. Mathew Porter

    Great post, nice idea for expanding sales of plugins to international users.

  8. Vane

    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.

  9. Caspar Hübinger

    FYI, there’s a broken link on the word “Boilerplate” leading to viatom dot com.

  10. Ian

    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.

    • Zack

      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?

  11. Ian

    I realise in my previous comment I was getting confused between your Boiler plate plugin and this Bolier Plate POT file (

  12. Ian

    Kudos to @grappler for creating this github repo: which includes the pomo directory

  13. David

    How do you generate .pot files through POEdit?

    • Tom

      This page has the best answer for you — it’d be redundant for me to share the same thing :).

      • Robert H.

        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.

        • Tom

          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

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑