Beginner’s Guide to Coding WordPress Theme Translations

Getting started in WordPress development does not take a lot of time. Even 1-2 hours a day toying around in PHP can teach a lot. Plus when you start getting into writing your own custom functions there is a lot of interaction required within the backend WP libraries.

For this tutorial I would like to delve into the topic of WordPress theme translations. More specifically I want to look at two different resources for translating your themes into other languages. WordPress allows for many common languages by default, however you should be able to support more than one at a time. If you check out the list of WordPress Language Packs you may be surprised to find a recent copy for your website!

Follow along with my process below and I will explain how we can get these language packs installed and working properly. Additionally I want to go over some of the more complex internal WordPress functions used for translating direct theme text. These are more helpful when updating static text, such as datetime metadata and footer credits.

Translating Existing Themes

Some WordPress users would prefer to stick with an existing theme name. These could be some of the free themes you find on WordPress, or other premium themes around the web. Either way the developers will often include files used for translating. These files are contained inside the .pot filename which stands for Portable Object Template.

If you want to follow this route I recommend you download Poedit for free off their site. It is a free download and should work for translating any WordPress theme using .po and .pot files. I would also reference this excellent guide on the topic of replacing the text in your theme files.

Basically you need to replace the global variable for your WordPress WPLANG settings inside the wp-config.php file. This is usually set to English by default, however WordPress does support a myriad of additional languages. Now aside from translating existing themes new developers may want to offer support for translated languages. This can be tricky when getting started, but I want to lay down the basics for moving forward.

New Language Settings

Each new theme language should come with its own set of .po and .mo files. These are used as libraries for locating specific phrases in your content and replacing them with the translated text. Now this could be done automatically as we saw in Poedt, which still does have some use for writing custom translations.

But this also requires coding your theme in a special way. We need to include a few methods and global functions which will overwrite the static text in your pages. We will go over these in the next section, but I want to point out a technique for building your initial .pot file.

Using Poedit we can quickly piece together the keywords and functions related to WordPress translations. Open the program and go to File -> New Catalog. Enter some details in the Project Info tab which are related to the current WordPress theme. Then on the paths tab you should use the dot(.) if you are keeping all files in the same theme folder. If you are placing language files inside a sub-folder then use the two dots(..) instead.

Now the Keywords tab is where we need to get into the various WordPress methods. This requires a list of text strings which we can search and replace inside the document. Here is a list of what you should include, and I will provide some more information in the next section.

• __
• _e
• _n:1,2
• _x:1,2c
• _ex:1,2c

Custom WordPress Functions

Each of these characters represents the name of a WordPress translation function. Applying the colon with two numbers implies that our function may have two separate actions. But each of the terms can be referenced using the WordPress documentation pages:

• __( 'Some text' )
• _e( 'Some text' )
• _n( 'Some text' )
• _x( 'Some text' )

Let's go over what these four different methods will perform. The first two __() and _e() are the most basic forms of translation. The double underscore function will return our text while the _e() will output the text using echo. Both functions will search our local translation directory(.mo and .po files) to see if there are any matches. If so then they return the translated text, otherwise it is left alone.

Now the _n() method is used in cases of plurality. So at times you may be displaying post/posts, comment/comments, user/users, and other types of words together in the same space. Instead of passing an if/else clause we can just use this one function to check the logic. I have included a sample code snippet for how this might look:

echo _n( 'There is a comment' , 'There are comments' , get_comments_number() ); 

Now _x() and _ex() are a bit more complicated, and most developers will not get into these functions. _x() is used for differentiating between words with similar meanings and applying context into the situation. Take for example the word project or produce. Are we talking about a website project or projecting onto a screen? And are we talking about producing quality content, or the produce growing in my backyard?

The _x() method will take these various levels of context and sort them out for other languages where it may be more ambiguous. The _ex() function is the same except it will directly echo the value instead of returning. All of these functions are worth implementing for some instances, but I would argue that _x() is the least popular among all of them.

Progressing From Here?

For developers who have read this far I recommend venturing into the realm of translating your existing themes with custom phrases. This provides excellent practice and you aren't risking any real damage if you don't push the changes live to your website. After going through and updating all your files with new functions, you can run Poedit and ship out your new .pot file.

Generally other users will contribute their own .po translations for WordPress developers to download and include as necessary. But if you want to jump into writing your own I recommend skimming this fantastic blog post. When writing your own translations it is much easier to include words that are not likely to be covered in general language packs.

Also if you get stuck developing along the way be sure to ask questions! My favorite website is WordPress StackExchange which has an excellent community of very knowledgeable coders.

Final Thoughts

I do hope this guide can be informative to any WordPress developers out there. Learning the ins-and-outs of the system is very complicated. And this can be especially true as we delve into the backend PHP code. However I feel that translations are a huge part of globalization which has made the Internet such a wonderful place.

This guide does not cover everything, but I have provided a stable ground framework for moving into more advanced topics. Some developers will not need to go much further and that is okay! We all have various purposes and requirements for CMS engines. If you have additional comments or questions on WordPress language translations, feel free to share with us in the post discussion area.