Here’s the third part of my series of articles on setting up a Multilingual WordPress site.
So far, we’ve looked at the basic requirements for setting up a Multilingual WordPress site, and how to set up the Language Switcher plugin to allow us to create multilingual content and let the site visitor switch between the languages.
The next steps are to:
- Internationalise our theme files (the subject of this article)
- Localise our theme files – which means translating English text in the theme files into our second language
- Set up WordPress to run in the two languages
Internationalising theme files
Although this sounds a little daunting, it is actually quite straightforward. But first, let’s step back for a moment and imagine we are browsing a WordPress driven site. Where does the all the text that you see come from? Three sources:
- the content added via Write Posts and Write Pages
- WordPress core files, eg standard WP widgets
- Text which the theme author has hardcoded into the various theme files
It is the last one in the list which concerns us today. We need to “internationalise” the theme files so that we can translate (in other words “localise”) this text which has been hardcoded into the theme files.
WordPress uses GNU gettext to handle the internationalising and eventual localisation of text in theme files (and WP core and plugins, come to that). It does this at “message” level, ie it treats each discrete section of text as a “message” and each “message” is translated individually. A “message” could be a single word, eg a heading at the top of a block of site content, or it could be several words, even several sentences.
To use this technology, it is necessary to find all text which will be output to the browser, and wrap it in PHP code using one of the two syntaxes which are recognised by gettext. These syntaxes are as follows:
_e("The text which is output to the browser")
__("Some other text which is output to the browser")
Which one you use depends on where the message appears in the theme file. If it is simply within XHTML code, and not already in PHP tags, use _e(). If the text is already within PHP tags, use the other syntax, ie __().
Here’s an example of a heading in a theme file:
You need to change it to this:
Here’s another example where the text is already within in PHP tags:
You need to change it to this:
As you can see, we’ve used the second gettext syntax mentioned earlier. Why? Because the text is already within a block of PHP.
Adding a textdomain
Before you rush out and start changing your theme files, there is one more thing we need to deal with, and that is the “textdomain”. WordPress requires that gettext used in theme and plugin files is attributed to a textdomain. This is simply a unique name which we will use so that WordPress knows which translation files to use for the text. Let’s keep things simple and call our textdomain “mytext”. So, taking the code that I showed you earlier:
As you can see, it’s simply a matter of adding a comma after the text, then ‘mytext’, before closing the brackets.
We haven’t told WordPress about our textdomain yet, so don’t worry about making these changes in your theme files – the text will still appear normally as before.
It’s now time to go through every one of the theme files (apart from style.css of course) and make the changes as shown above. Remember to include the textdomain name in your new code!
Telling WordPress to use the textdomain
Now that we have all the theme files “internationalised”, ready for translation, there’s one important thing we need to do – we need to tell WordPress that we want to use a textdomain.
Simply add this to your theme’s functions.php:
This code does 2 things:
- Tells WordPress that we want to use a textdomain called ‘mytext’
- Tells WordPress that the translation files can be found in a folder called languages within our theme folder.
In the next article we shall look at the process of “localising” the themes, in other words translating the text that we have just internationalised and creating the necessary translation files to be used by WordPress.