Recently, I’ve had a lot of customers asking me about creating a theme translation file for some of my themes. What I always assumed was a straightforward process actually has a few little kinks that could confuse most people. It takes a couple of steps, but once you get the hang of it, it won’t seem so difficult.

First off, let’s discuss the software I use to translate my themes.

PoEdit translation software

Working with PoEdit

PoEdit is free, though there is a premium version you could buy. I opted for the premium version since I use it all the time and those extra features do really come in handy.

Once you load up a POT file, you will see all the translatable strings. Select your language and translate away. Once the strings have all been translated, click save and PoEdit will create the PO and MO theme translation files you need with the appropriate filenames.

Filenames are important and will help WordPress know which language file to use. You can read more about naming conventions here: https://make.wordpress.org/polyglots/teams/

You can see on that page that a Canadian English language file should be named en_CA.po and a French language file should be named fr_FR.po. Look through the list to see the correct name for your language.

Wordpress General admin setting

Switching WordPress into your language

This step of the process has become easier ever since the setting option was added to the General admin page. Before you had to edit wp-config.php but now you can just select your language from the drop down list.

Adding your theme translation file to the right folder

This is the one step that I actually didn’t really know much about. I thought you just had to add the new theme translation file to the theme’s languages folder. Though, this creates an issue if you ever update, since that folder is replaced and the custom language files are deleted.

The correct and safe way to store a language file is to create a languages folder in your wp-content folder. The hierarchy should look like this:

- wp-content
- - languages

Since you’re creating a translation for a theme, you need one more folder.

- wp-content
- - languages
- - - themes

We’re almost there. The languages folder we’re going to use is now outside of the theme folder, so we need to let WordPress know which files link to which themes. That means we have to change up the naming convention a little to connect things.

If you’re creating a French language file for the theme Arcade, this is how the folder/file setup should look:

- wp-content
- - languages
- - - themes
- - - - arcade-fr_FR.po
- - - - arcade-fr_FR.mo

You need to add ‘arcade-‘ to the name of the language file. If you were using Magazine Premium, you would have to add ‘magazine-premium-‘ to the file name.

Here’s another way to see the hierarchy:

/wp-content/languages/themes/arcade-fr_FR.po
/wp-content/languages/themes/arcade-fr_FR.mo

OR

/wp-content/languages/themes/magazine-premium-fr_FR.po
/wp-content/languages/themes/magazine-premium-fr_FR.mo

There’s the rub

It takes a few extra steps, but setting up a new languages folder this way will keep your theme translation files safe when you update.

If you’ve create language files for any of my themes, feel free to link to them in the comments below so everyone can benefit from your hard work.