This guide is another in the Inside WordPress series and attempts to show how to produce a translation for an already-prepared theme, plugin, or WordPress itself. Even if you have little PHP or HTML skills you can still contribute to making WordPress a truly international experience by providing localizations for existing themes and plugins.
The guide will be written from a beginners perspective and will not assume any knowledge of PHP or HTML (although some will be helpful). Detailed explanations will be given at every stage and you are invited to provide feedback or pose questions.
If you are a plugin or theme writer then please take a look at Preparing A Theme Or Plugin for Localization, another in the Inside WordPress series that is specifically targeted at the steps involved before a translation can occur.
An Overview of localization
WordPress uses a standard localization framework called GNU gettext. This framework provides the programmer the ability to mark text inside code as being suitable for localization. The role of the translator is to take these marked pieces of text and produce a language-specific localization. No code needs to change and you do not need to understand how the program works.
Text is marked by wrapping it with special PHP functions. It is not important to know how these functions work, but it will be helpful to recognize them:
__($text)– Looks for a translated version of
$textand returns the result
_e($text)– Looks for a translated version of
$textand echo the result to the screen (i.e. effectively it is
$numberis 1 then looks for a translated version of
$single. If number is more than 1 then looks for a translated version of
With a suitably localized theme, plugin, or WordPress, the steps involved in translating it are:
- Run a tool over the code to produce a POT file (Portable Object Template), simply a list of all localizable text. Some themes and plugins may already provide you with this
- Use a plain text editor or a special localization tool to generate a translation for each piece of text. This produces a PO file (Portable Object). The only difference between a POT and PO file is that the PO file contains translations
- Compile the PO file to produce a MO file (Machine Object), which can then be used in the theme or plugin
Tools Of The Trade
Special software tools are needed in the translation process. There are many available options here and this guide will show you how to use two Open Source tools:
- poEdit – A cross-platform graphical tool that is available for Windows, Linux, and Mac OS X
- GNU gettext – The framework has its own set of command-line tools to produce the POT file and to compile the MO file. Use of these tools is considered advanced, and is more appropriate to people who want to automate the translation process
Before you continue you should ensure you have one of the above tools installed.
poEdit is a localization tool with a graphical interface. Windows and Mac OS X users can download a self-installing file from the poEdit download page, while Linux users will need to install it via their package administration system.
After installation you should take a few moments to configure poEdit. This is very simple and just requires your name and email address, which will be embedded in any files you produce. From the poEdit menu select Preferences to bring up the settings. Enter your details:
GNU gettext can be installed easily enough on Linux using a package management tool appropriate to your installation. Windows users can download a self-installing file from Gettext For Windows which will take care of any complexities. Mac OS X users have the choice of downloading gettext and compiling it themselves, or using a pre-built copy from a package management such as Fink or DarwinPorts. Details of any of these methods is beyond the scope of this guide and any problems should be directed at the appropriate website forums.
Note that this guide will assume that the gettext utilities are located somewhere in your path.
The naming of your PO and MO files is very important and must match the desired locale. The naming convention is:
Or, for non-standard encoded localizations:
That is, the file name must be the language code followed by an underscore, followed by a code for the country (in uppercase). If the encoding of the file is not UTF-8 then the encoding must be specified. For example:
en_US– US English
en_UK– UK English
zh_CN– Simplified Chinese
ja_JP.EUC-JP.mo– Japanese in EUC-JP encoding
Note that WordPress plugins have an additional naming convention whereby the plugin name is added to the filename: