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

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:

http://i18n.svn.wordpress.org/tools/trunk/

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

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

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:

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

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.