Making a Portable Object Template for your WordPress theme or plugin

Yes, a bit of a lengthy title but I feel will get the point across and it is after all what I’m wanting to share with you today.

A what now?

A .pot ( or a Portable Object Template ) file is what WordPress uses and many PHP programs use for translation purposes. There are three files used. According to icanlocalize.com the files are:

• MO – Machine Object. The MO file includes the same contents as PO file. The two files differ in their format. While a PO file is a text file and is easy for humans to read, MO files compiled and are easy for computers to read. Your web server will use the MO file to display the translations.
• PO – Portable Object. This is the file that you receive back from the translators. It’s a text file that includes the original texts and the translations.
• POT – Portable Object Template. This is the file that you get when you extract texts from the application. Normally, you send this file to your translators.

The one we will worry about is the last one. The POT file. There are several ways to create this file but the one I’ve found most useful was the one Otto was awesome enough to post for theme reviewers. It is super simple and does need a little tinkering and getting over the fear of the command line.

Yes, the command line. You know that little program that uses only text. No, not a text editor. Would be cool but no. Depending on the platform you are using it will be called a terminal window, command prompt or even powershell. All of these will work for what we will be creating.

Steps and requirements

Sorry, did I not mention there would be some requirements? The basic requirement is the command line and having PHP installed. The next would be getting the needed files from the repository. If you aren’t developing themes using a development version of WordPress leave your address in the comments below, I will find you and I will hit you. Hard. Even a release candidate is worth your investment unless you like to break things and have people yelling at you.

The tools and files you will need are in one of two locations. The first being in the svn developer site. You will need some sort of SVN software in order to get it, of course. The other would be from my github repo I created and modified. Yes, I created it just for this reason.

So the steps are as follows:

1. Get files
2. Extract files to correct folder
3. Open command line
4. Do some magic – or Voodoo, your choice
5. Do happy dance!

Getting the correct files

I mentioned and linked two places where to get the needed files. The github link is the one I will go over. Part of that reason is not everybody will be fully familiar with version control or comfortable enough to not break things. Once that is downloaded we can open the zipped folder and move on to the next step!

Extracting the files

This is super simple thing to do. Extract the files to the root of your WordPress folder. It should look something like the image.

Open the command line

Now, there are several tools that are available for this. For Windows user there are two that I will often switch between: command prompt and powershell. I like using powershell more. We then will change to the directory where we have our WordPress installation.

For the next step will be going over some code, so be prepared.

Doing the magic

So here is where the real magic will happen. Once we are in the folder of our installation we will once more change directories to the i18n folder where all translation files reside. From there we will run a quick line of code that will create our new POT file.

$ php makepot.php wp-theme /path/to/theme /path/to/languages/theme-slug.pot

The thing to keep in mind is the $ is just a placeholder for the current directory you are in. It may differ from machine to machine. Once we have run that it will create a new file ( theme-slug.pot ) with all translation-ready strings. So try not to forget to translate all text strings!

How it works

I know there are a few people wondering how this actually works. I know I was for bit. I’ll try my best to make it a little more understandable why you need to have certain things in your command line.

The first thing you need to know is what you are doing. When you state php you are to a degree saying, “I want to run PHP code and use this file.” The next three things are what you are going to pass that file.

1. The first thing we passed is what type of project you are creating the pot file for. In our case it is a wp-theme. There are a few other you can decide from like wp-plugin, wp-admin, wp-core and a few more that I just won’t list.
2. The second thing we passed is the location of where to look for the translation functions. If you read through the list of what functions it looks for you are in for a treat because that list you can add to Poedit. (I’ve slowly walked away from that but would still recommend for beginners.)
3. The last thing is the output of the file. Both the location and the name ( be sure to include the extension as well ) are what we will be using.

Now, you can do this with your plugins as well. Just be sure that the folder you are creating the POT file to does exist otherwise you will get errors and it won’t create the file for you.

I stated earlier that it works with a few changes; it’s true. The reason being I know there are some people who don’t like to use a development version of WordPress. Why? I don’t know but I made a few tweaks for it to work the way it works. Okay, I only changed three things but it works for the time being. I say that only because I’ve tested it on/off since the original post. If you encounter any issues please be sure to let me know!

Celebration will begin

There we have a newly created POT file ready to be sent to a translator. So, yes, by all means do your happy dance. Not only did you get over the slight fear of the command line but you possibly learned something new along the way.

Notes

If you don’t specify a path of where your theme/plugin resides it will create an error and will not work!
If you don’t specify a path, just a name for the file it will create the file in the i18n folder.