WordPress Translation Made Easy with Poedit

Reading Time: 4 minutes

WordPress Translation for Your Themes and Plugins

If you’ve spent any time working with WordPress plugins or themes you’ve invariably come across somthing that looks like __( 'Some awesome string.', 'theme-text-domain). For the curious that’s a function that retrieves the translation of the string passed and outputs it. Using these functions allows for easy WordPress translation.

When that function (and a few others) are used, they first check the Site Language settings from Settings > General to see if a translation file exists for that language. The function will return the translated string if there is a WordPress translation file in the theme or plugin.

#: 404.php:22
msgid "Oops! That page can&rsquo;t be found"
msgstr "Oops ! Page introuvable."

#: 404.php:26
msgid "Try a search to find what you're looking for."
msgstr ""
"Faites des recherches dans leur base de données afin de trouver ce que vous "
"cherchez."

In order to easily create those translations, or allow others to, you need to generate a .pot (portable object template) file for your theme. If you use the _s starter theme to build themes from scratch you’ll see an example .pot file.

You could create your .pot file by hand, rigorously going through your theme and looking for all the translatable function and transcribing it into a .pot file, or you could set up Poedit. Poedit can scan your theme and output a .pot file.

Setting up Poedit for your WordPress Translation

First, you’ll want to download Poedit. There’s also a Pro version available that automates some the following process and can be used to start creating actual translations from both humans and machines, and at $20 it’s a great deal. I won’t be offended if you stop reading this article and grab the Pro version, but if you’d like to know how to set up a WordPress translation manually, read on.

Starting a New .pot File

Creating a .pot file for your WordPress translation is easy with Poedit, but it can be a little confusing since Poedit forces you to generate a .po file. Luckily a .pot file is just a .po file with the translations left empty so we can rename our final output. If you already have a .pot file you can open it in Poedit and skip step 13 and 14.

Steps

Open up Poedit and select File > New to create a new translation project.
Set the Language of the translation to whatever you’re starting out from. Likely English. Hit OK.
Select Catalog > Properties and with the Translation Properties tab active, fill out your project info. Your Charset and Source code charset are most likely going to be UTF-8. If you don’t know your charset, it’s almost certainly UTF-8.
Next click the Sources Keywords tab.
After that you’ll click the + icon to add a New Item. Here you’ll enter all of the functions you want to search for in your source files. For more info on what to enter here check out Setting up Sources Keywords below.
Click OK.
Select File > Save As… and navigate to the languages directory in your theme. If you don’t have one just create it. Name your file as your theme or plugin name. The current version of Poedit¹ will only let you save this as a .po file. Now we’ll rename the file to a .pot file. The .po files will be used for actual translations whereas the .pot is a template for those .po files.
Go back to Catalog > Properties.
Select the Sources Paths tab. Here you’ll be selecting your theme or plugin directory to pull translation functions from. For more details on setting up this section see Setting up Sources Paths below.
Click OK.
Next click either the Update catalog button or select Catalog > Update from Sources.
Save your file.
Navigate to your file and rename it to use the .pot extension instead of .po. Delete the .mo file as that is tied to actual translation files. For more information see I18n for WordPress Developers.
After you’re done close the file in Poedit before trying to do anything else as it won’t be able to find the renamed file. If you’d like to make edits or create translations simply open the renamed .pot file using Poedit and have at it.

Setting up Sources Paths

Your Base path is going to be the path to your theme or plugin directory. To set this you’ll click the + icon under the Paths box and select Add Folders, then select your theme or plugin directory. This will update the Base path and add a “.” into the Paths area.

To exclude certain folders and files simply click the + icon under the Exlcuded paths area and select the files or folders you wish to exclude.

Things you might want to exclude:

SASS or CSS directories
Fonts
Configuration files
Anything else in your theme that won’t be using translation functions

Setting up Sources Keywords

In this section we’ll tell Poedit what functions to look for with translatable text. Some of the more common functions are __(), _e(), esc_html__(), esc_html_e(), and on, and on. For a full list see the Codex.

In Poedit you’ll just want to enter the function name as a keyword. For example, to detect the __() function you’d enter your keyword as “__” (two underscores). Or for _e() you would enter “_e”. Once you’ve manually added the keywords you’re ready to generate your .pot file.

Poedit Pro

Now upgrade to Poedit Pro² and start the WordPress translation of your theme or plugin without the hard part of learning how to speak the language. Not saying that won’t help. Duolingo can help you with that.

WordPress Resources

Looking for more great WordPress Resources? Check out my resource page, and if you have any suggestions feel free to shoot me a message!

If you’re interested in getting more tips and articles directly in your inbox join my list.

2.0.2 as of writing
I’m not affiliated with Poedit at all. It’s just a really useful tool.

WordPress Translation For Themes and Plugins Made Easy with Poedit