The internet has opened the doors for social based organizations to leverage a communication medium that fosters engagement with an ever-connected planet. With those aspirations in mind, Promundo hired Radish Lab to create a web experience that caters to their existing Portuguese and English speaking audience but also allows easy entry into new lingual communities.
While there exists several plugins and technologies (like Google Translate) that make simple multilingual translations possible, Promundo’s unique situation required a distinct language-specific content strategy. Traditional solutions normally require a one-to-one approach, each word and sentence having a corresponding version in a desired language. To fulfill Promundo’s requirements we opted to create a Wordpress localized theme which lives within a Wordpress multisite. In essence we created multiples sites, each sharing the same localized theme. While our setup of the Wordpress multisite was fairly textbook, for the purposes of this article I will guide a potential theme developer through the process of localizing a Wordpress theme.
A brief overview of Localization
WordPress uses the popular localization framework gettext. Originally created for GNU Translation Project, it allows the developer 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. This means the code within your theme remains the same but references a translation file to output the appropriate language.
Preparing Your Theme for Localization
When adding a translation to a theme you’ll need to add a text domain to the theme’s header in the style.css file. A text domain is a unique identifier Wordpress uses to distinguish your translation from others that are loaded. The text domain must match the slug used for the theme, which in the following example is Promundo:
/*
*Theme Name: Promundo
*Author: Radish Lab
*Author URI: https://radishlab.com
*Text Domain: promundo
*/
Adding Translatable Words to Your Theme
To have a particular word added to your translation file, it will need to be wrapped in a translate function call. A few of the popular options are:
- __( $text, $domain ) - Retrieves a translated string. ( Codex )
- _e( $text, $domain ) - Displays the returned translated text. ( Codex )
- _x( $text, $context, $domain ) - Retrieves translated string with gettext context. ( Codex )
- _n( $single, $plural, $number, $domain ) - Retrieves the plural or single form based on the amount.
The L10n Wordpress codex page has a complete list of all the localization functions.
Once you’ve added the words you’d like to be translated, the next step is to add text domain support to the functions.php:
load_theme_textdomain( 'promundo', get_template_directory() . '/languages/' );
Understanding the Pieces Used to Translate a Wordpress Theme
- .pot File - Portable Object Template
Combing through your WordPress code for any markup enclosed within a __e() or __() function will generate a POT file. This file will contain all the text available for translating but not the actual translations. - .po File - Portable Object
Once you’ve compiled the list of available text, you can place the actual translations within the POT file and save your file as a PO file. Each individual language that is translated should be saved in a separate .po file using the original .pot as a template. - .mo File - Machine Object
The final step in the localization process, the PO file is run through a program that converts it into an optimized machine-readable binary (MO) file. Compiling the translations to machine code makes the retrieval of the file more efficient and faster for the server.
Creating a Portable Object Template
The next step in the translation process is to generate a .pot file which includes all the locations of your translation. Since we we’re using the popular task runner Grunt for our build process we used Stephen Harris’s grunt-pot .
Translate your POT files using POEdit
If you’re on Mac OS X, setting up the translation files couldn’t be easier. Poedit is an easy to use translation program for any site that uses gettext for location based translations.
Where to place your translation files
As a method of best practice each translation file should be placed in your theme’s directory within a “languages” folder:
/wp-content/themes/theme-slug/languages/filename
As an example here are the files we used on Promundo:
/wp-content/themes/promundo/languages/promundo.pot
/wp-content/themes/promundo/languages/pt_br.po
/wp-content/themes/promundo/languages/pt_br.mo
A complete lists of codes can be found at language codes, and country codes can be found on the GNU website.
Conclusion
Wordpress’s built in localization support makes creating a global content-based website easy. While we started with only two languages for Promundo, in the future we’ll be able to easily update their translation file as they begin to target new lingual communities. Wordpress continues to be my first recommendation for content focused multilingual websites.