Multilingual Atahualpa theme

I’m going to show how to use Atahualpa, by Bytes For All, for building multilingual WordPress sites using WPML.

A theme for a multilingual WordPress site needs to have all strings wrapped in gettext calls, but it’s not quite enough. Using gettext in the theme allows it to display in a different (single) language from what it was originally built with.

To run multilingual, the theme needs to to allow visitors to choose their display language and deliver the correct content per language.

A multilingual version for Atahualpa

Let’s start at the end. Here is a demo site powered with a modified version of Atahualpa and here is the modified theme which you can download and use.

What we changed to make Atahualpa multilingual

1. Adding wpml-integration.php to the theme’s directory

wpml-integration.php is found in WPML’s directory under docs/theme-integration. It includes a collection of functions which help turn themes into multilingual.

All these functions are designed to make themes use WPML if it’s active or ignore it if it’s missing. This means that the theme would run multilingual if WPML is available or normally (single language) otherwise.

Added to functions.php:

include dirname(__FILE__) . '/wpml-integration.php';

This statement loads wpml-integration.php and makes it available to all the files in the theme.

2. Adding language selectors

Language selectors make it possible for visitors to choose the language in which the site is displayed. Often, it’s a good idea to add several types of language selectors. Visitors scan the site quickly and look for visual hints to contents in their languages. Different people look at different places, so adding different types of language selectors to different parts of the page will help move visitors find their language.

We added WPML’s drop-down language selector to the sidebar by adding it to header.php:

<?php wpml_languages_selector() ?>

We also added a horizontal list of languages to the site’s footer. Many users first scroll all the way to the bottom to see what’s there (and how long pages are), so it’s a good place to tell pages are available in other languages. We added the following code to footer.php:

<?php wpml_languages_list() ?>

Finally, we added a language selector at the end of each post. This adds a sentence to each post, telling in what other languages it’s available. Added the following to index.php (which includes a custom version of WordPress’ display loop):

<?php if(is_singular()) wpml_content_languages(); ?>

3. Making the home page link go to each language’s home

When visitors click on ‘Home’, they expect to get to the home page without switching language. Since each language has a ‘home page’ with a different URL, a single value for all will not work.

Normally, WordPress themes calculate the address for the ‘Home’ page based on the ‘Blog URL’ value set in the admin page. WPML created a function that calculates the correct home address according to the display language.

We replaced get_option(‘home’) with wpml_get_home_url(). Also, the get_option(‘home’) function returns the site’s localication without a trailing slash (/), so themes add it manually. WPML’s function includes this slash (there’s a long story behind this).

To do this change, we had to edit two files. Modified functions/bfa_get_options.php and change:

$bfa_ata['get_option_home'] = get_option('home');

into

$bfa_ata['get_option_home'] = wpml_get_home_url();

Also, edited functions/bfa_header_config.php and removed the trailing slash from the home page link:

'<a href="' . $bfa_ata['get_option_home'] . '">' . $bfa_ata['bloginfo_name'] . '</a>'

4. Really advanced – translating texts users enter in the theme admin screen

Atahualpa allows controlling some texts through the admin screen. This is a great thing which allows to manage the site without editing PHP files. WPML can translate these strings too using its String Translation mechanism.

To do this, the theme needs to tell WPML which strings need to be translated and then display the translation if it exists.

When users go to the theme’s admin screen, update the texts and click on Save, the function bfa_ata_add_admin from functions/bfa_ata_add_admin.php is executed. We added the following section to it (starting at line 11):

global $wpml_translatable_strings;
 foreach($wpml_translatable_strings as $wpml_str ){
   if(isset($_REQUEST['bfa_ata_'.$wpml_str]) && trim($_REQUEST['bfa_ata_'.$wpml_str])){
    wpml_register_string('atahualpa theme', $wpml_str, stripslashes($_REQUEST['bfa_ata_'.$wpml_str]));
  }
 }

What this does it run through a list of strings defined in the global variable $wpml_translatable_strings. It registers each string in WPML’s string translation list.

The first argument is the context for the strings. Any name would go, but you should select a name that describes the strings. The second argument is the name for the string (doesn’t get translated). The last argument is the value of the string – gets translated.

To display the translations (if they exist), we added the wpml_t function to functions/bfa_get_options.php (starting at line 204):

global $wpml_translatable_strings;
foreach($bfa_ata as $k=>$v){
   if(in_array($k, $wpml_translatable_strings) || $__first){
    $bfa_ata[$k] = wpml_t('atahualpa theme', $k, $v);     
  }
}

This code is run when the site is displayed to visitors. It will loop through the list of strings, check if it’s been registered for translation (in_array) and if so, get the translation. The wpml_t function will return the translated string in the current language, if translation exists, or just return the original string if there’s no translation.

Turning other WordPress themes multilingual

We’ve already done similar work on iNove and Arras and are planning to convert more themes to multilingual.

Our intention is to provide ready-to-use multilingual themes and help you build your own multilingual-ready themes. Using the techniques we described here, you can build themes that will run multilingual when WPML is available or in a single language without WPML.

If you’re building themes and need help turning them multilingual, feel free to open new threads in the forum.

You can also make money (really passive income) by adding multilingual support to your themes. We’ll talk about including affiliate IDs in themes in the next post.