How to make a translatable WordPress theme

by Jean.

Althought English is the most represented language over the Internet, it is a good thing to think about people who speak other languages and offer them trabslated WordPress theme. In this step-by-step tutorial, you’ll learn how to take a WordPress theme and make it translatable for any language.

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) )

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.


<?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 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');


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


CWC Special Deal!

Get one year of quality hosting + domain from A Small Orange for only $40 with our exclusive deal!

Featured WordPress Theme

Bridge - Creative Multi purpose WordPress theme

  • Pingback: How to make a translatable WordPress theme | Webs Developer()

  • Ozh

    I strongly recommend *not* to use something as “Cats Who Code” as the textdomain, but preferably something like “catswhocode”. A textdomain with spaces (and mixed case) is a loud call for file problem depending on the platform.

  • Jean-Baptiste Jung

    @Ozh: Good advice, thank you!

  • Frank

    Use the plugin Localization and you have no problems and many support at the translation: different files for frontend and backend, automaticly transaltion via Google API and more, the best tool for translate a plugin or theme.

    @ozh: right, it must use a string without empty and –

  • Pingback: How to make a translatable WordPress theme | Neorack Script()

  • Pingback: How to make a translatable WordPress theme()

  • Pingback: How to make a translatable WordPress theme « Netcrema - creme de la social news via digg + delicious + stumpleupon + reddit()

  • Jerry

    You’ve cited a nice idea about translation. Hopefully, this works out for either a plugin or theme once I use it.

  • Pingback: Daily Digest for August 18th -

  • http://www.hobbes tkhobbes

    Interesting – but I am actually looking at something that would CHANGE the language, based on the client browser’s preferences…. is there something like that available (I guess I would have to build upon the solution here and add stuff to detect the client’s language)…

    Obviously, the challenge would be to create at least the static pages 1x per language and then select them dynamically…

  • Best CSS Gallery

    Great guide

  • Tom

    Nice tut. Thanks for it!

  • Dara

    Great instructions. Tutorials that provide screenshots and step-by-step instructions are completely invaluable.

  • haily

    useful post, thanks !

  • Pingback: Интересното от 19.08.2009 |

  • J Themes

    Very informative topic!

    I wonder how many people actually struggle with translating a theme. I guess I take it for granted since I speak English.

  • Andri Irawan

    Thank you for your guide.

  • SecretsPedia

    I like this tutorial

  • Pingback: Darklg Web (darklgweb) 's status on Thursday, 20-Aug-09 21:20:42 UTC -

  • Pingback: How to make a translatable WordPress theme | PHP()

  • Pingback: How to make a translatable WordPress theme | Webs Developer()

  • Pingback: Como criar um template Wordpress traduzível para multi línguas | Wordpress Love - Themes, Plugins e tudo para Wordpress, em Português()

  • Pingback: Wordpress Resources #1 | wpcrunchy()

  • Pingback: Recursos para la Creación de un Theme WordPress | Area Photoshop()

  • Ed

    Cheers, this will come in handy for a project I’m working on!

  • Konstantin

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

    I usually solve this problem by defining a contant with a unique name and use this constant in the load_theme_textdomain() function and all gettext functions.

  • Pingback: Como hacer un theme WordPress traducible | Ayuda WordPress()

  • rotem

    Good tips, thank you!

  • Pingback: Как создать переводимую тему для WordPress | Очередной блог фрилансера()

  • Pingback:   Localizing WordPress themes by Free WordPress Themes Blog()

  • Gabriel

    Great guide! Screenshots are very useful so that we can follow the tutorials in a step-by-step manner. I’d better try this one.

  • Oron

    Thank you, very helpful.

  • Pingback: wazzup » Blog Archive » Como criar um template Wordpress traduzível para multi línguas()

  • Hakeem – technology and gadgets

    Cool code. Thanks for the information.

  • Spicy Web Design

    Another way to make translatable WordPress themes is to create a WordPress child theme using a parent theme framework such as Thematic that has the translation capability already built in.

  • RWH

    informative tutorial. thanks a lot. Have to implement it for its functionality.

  • Pingback: Rendere traducibile un tema di WordPress ‹ Ubuntu block notes()

  • Ralph MIller

    What affect does this have for search engines? Is each translation have it’s own unique URL? Or does it maintain it’s URL structure and just translate the page? We offer search engine ranking services, but I haven’t encountered anything regarding multi-language websites, so I’m very curious if this has any added value from a marketing perspective..

  • ejakulasi dini

    That’s good explanation, thanks for the lesson very much.


  • Milch


    Whats the best way to make a multi language wordpress blog? I tried some plugins but none of them really impress me. Does anyone have any experiences with this and any good advice?

  • Rene

    for some reason I get:
    “Fatal error: Call to undefined function load_theme_textdomain() in /home/content/01/5138501/html/blog/wp-includes/functions.php on line 27”

    anyways regarding a good tool for wordpress translation I use WPML widget and it is phenomenal!!

  • Pingback: 5 Tips for Free Wordpress Theme Authors | Devlounge()

  • Pingback: Localizing WordPress themes « Temas e Dicas para Wordpress()

  • Pingback: Best practices for WordPress coding()

  • Mario

    That’s good explanation, thanks for the lesson very much.

  • JesperA

    Hi, i have some problem when using the comments_popup_link function in WordPress with multiple values like this:

    comments_popup_link(‘No comments’, ‘1 comment’, ‘% comments’);

    How do i implement the translating feature into that?

  • Pingback: WordPress Resources #1 « AsterHost()

  • Chris

    Hi Jean,

    Thanks for the great post/site.

    I have a quick question. I would like to know where to keep the langauge (.mo,.po) files? Do i just keep them inside the theme folder? I already have a language folder that contains the relevant language files for wordpress but I want to know where to keep these files that translates my theme.

    Best wishes,


  • Pingback: Translate a WordPress Theme in 3 Easy Steps | Solostream()

  • anmari


    You may want to update this bit:

    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.

    If you have a plugin (and possibly this is there for themes too) hosted in wordpress. Login, go to the admin section for your plugin

    There is a box to
    1) enter a text-domain
    2) browse to your php file,

    hit submit and Voila you have all your __ and _e and _x calls updated with the text domain in new file.

    Works for any php file (does not appear to have to belong to the plugin!). WP probably should put this somewhere more central!

    • George Dina

      Or you can use add-textdomaina.php to update all your gettext string with the correct domain.

      Details here:

  • Salem Alshamsi

    Thanks Friend for posting such a nice post.

  • Paul Blake

    Hi Jean Baptiste,

    Can you tell me whether this will cause any issues with the Thesis theme and wordpress?



  • Timo

    I don’t understand this line:
    $locale_file = TEMPLATEPATH.”/languages/$locale.php”;

    Why include a PHP-File? In Twentyeleven’s functions.php, it is the same code. But they don’t have any PHP-Files in the languages-Folder. What the heck?

  • Gilles Hoarau

    Thanks, its very clear !

  • jahur

    your article helps me lot.

    _e(“txt”, “domain”) . Can you tell me what is “domain”? I want to translate my theme into french. Will it be fr_FR?


    • Aziz

      Domain is the text domain that declared in first step (Add the needed functions). In this tutorial it is ‘Cats Who Code’.

  • Vanessa

    Do you know any other localization plugin for wordpress?

  • Jason


    Is it compatible with the Catalyst/Dynamik theme?


  • Jonas Lundman

    Nice and clean get started explained turtorial about how to translate a WordPress theme. Thanks. Its getting old and as mentioned in this thread, maybe you should edit the article about Text domain names and whitespaces. What I understand, the codex recommend using dashes like cats-who-can, am I right?

  • James

    About 5 years latter, is there a better way to do this?

  • summ3r

    To collaboratively translate WordPress themes, I recommend the localization platform

  • David

    we use and are more than satisfied with this tool!