How to make a translatable WordPress theme

1 – Add the needed functions

Let’s start by the basics: Paste the following lines of codes on your functions.php file.

load_theme_textdomain( 'Cats Who Code', TEMPLATEPATH.'/languages' );

$locale = get_locale();
$locale_file = TEMPLATEPATH."/languages/$locale.php";
if ( is_readable($locale_file) )
	require_once($locale_file);

On line 1, you see the load_theme_textdomain() function. This function allow you to load a Text Domain. You can pick up any name, but keep in mind that it have to be unique. So the best practice should be to use your theme name.

2 – Internationalize your theme

For translating our WordPress theme, we’re going to use the php gettext functions.
GetText has two functions: _e and __ (two underscores).
The “_e” function is used to print “simple” text, and the __ function is used when the text to be displayed is already wrapped in php tags.

Examples:

<?php _e("The page you're looking for doesn't exist", "Cats Who Code"); ?>
<?php the_content(__('Read more...', "Cats Who Code")); ?>

Notice again the text domain name (Cats Who Code) above, remember that it should be the same as in the functions.php file.

The boring part is that you have to replace each single string by the required function. Depending on how many strings your theme have, this can take a lot of time. I’ve heard of some GNU tools to easily extract strings from files, but as I never tried it I can’t say anything about it. For those interested, google xgettext.

3 – Create your .po file

Now, your WordPress theme can easily be translated to any languages. But to display text in a foreign language, you have to add a .po file.
.po files stands for Portable Object. basically, theses files contains a string, and its translation in another language. For example, if you download the French version of WordPress, you’ll have a fr_FR.po file in the archive. This file contains all the translations needed for your theme to speak French, so your theme will say Bienvenue instead of Welcome.

Good news, you don’t have to search throught your theme files for all the string to be translated. A free online tool named icanlocalize.com can scan PHP files and create .po files for you ICanLocalize will extract all strings wrapped in __(”txt”, “domain”) and _e(”txt”, “domain”) calls. Strings can be enclosed in either double quotes (”) or single quotes(’) and with any character encoding.

Po files can be edited with PoEdit, a free software especially dedicated to that task:

As you probably guessed, you have to translate each text string. Once you translated it all, save the .po file. PoEdit will also generate a .mo file, which is basically a compiled version of the .po file.

4 – Implementation

Right now, you have done the most “difficult” part of the job. The only thing you have to do is to define your WordPress locale.
To do so, the first thing to do is to get your language and country code. For example, if your language is French and France is your country of residence, your code will be fr_FR. The GNU gettext manual contains pages to help you find both your country and language codes.

Once you have your codes, open your wp-config.php file and look for the WPLANG constant. If it exists, simply replace the existing code by yours. If it doesn’t exists, simply paste the following line (with your own code, of course)

define ('WPLANG', 'fr_FR');

Sources

The following articles has been very useful to me for writing this post. Thanks to the authors.

• Making it Translatable – Internationalize / Localize WP Themes
• Premium themes are translatable themes