16

atahualpa screenshotI’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() ?>
atahualpa_drop_down_language_selector
Drop down language 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() ?>
Horizontal language selector in footer
Horizontal language selector in footer

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(); ?>
List of translation languages
List of translation 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.

16 Responses to “Multilingual Atahualpa theme”

  1. Hi guys,

    thanks for a great plugin! But when I install this theme on 2.8.3, I get the following error in admin:

    Fatal error: Call to a member function read() on a non-object in /var/www/wp-includes/theme.php on line 387

    If I remove the theme, everything is fine again. Do you have an idea what is going on?

    • You might have not search well enough because it appears there. Here are the places where wpml_content_languages appears in:

      index.php: <?php if(is_singular()) wpml_content_languages(); ?>
      wpml-integration.php: // function wpml_content_languages($args)
      wpml-integration.php: function wpml_content_languages($args=''){

  2. Hi, I’ve installed the latest version of the Atahualpa theme (3.4.4), and installed WPML as a plugin, activated it and translated leftover strings in the MO file manually (English to Swedish), and finally made the above edits to the various PHP files.

    Now I get the error message:
    Fatal error: Call to undefined function wpml_get_home_url() in …/blog/wp-content/themes/atahualpa344/functions/bfa_get_options.php on line 29

    It seems like it won’t load wpml_get_home_url()

    Nothing will load. If I put back the unchanged backup versions of the PHP files everything is back to normal, but without the multilingual functionality.

  3. I’ve now installed your earlier, modified version of Atahualpa – it works OK although I only get the sidebar selector to work. (Not the footer, which would have been awesome)

    And…how do I change its color?

    • I Jonas,

      I’m glad to hear that this is working. Can you open a thread in our forum about this?

      It’s easier to follow up on technical issues there.

  4. I have installed WPML over atahualpa 3.4.4 and atahualpa widgets are not translated (BFA Recent Comments for example)

    This plugin is great and if I could solve this issue is really greatest! 🙂

  5. hello,

    thanks for the tutorial but unfortunately it’s outdated.
    Could you please give the process for the latest atahualpa version ? (3.7.3)

      • hello,
        thanks for the reply.

        wpml and atahualpa seems not working here.
        could you redirect me on a page giving some explanation about the how to link wmpl & atahualpa, please ?

        • It’s all possible. Can you please report this in our forum? Please don’t assume that the support folks know what you’re talking about. Explain the issues from scratch and show them what’s not working.

          You should start by posting links to where the can see the problems on your site. To see things in the WP Admin, they may ask for a temporary account, so that they can see what you’re seeing.

  6. Well, most of it works quite allright. What I am struggling with is the ‘Leave a comment’ like messages in by-line and footer of the posts and comments. In string translations it seems that i have translated, but they still appear in english on the site. Please help. What do i have to manipulate to make those string translateble.

    • We will be happy to get all this working properly. Can you please start a thread in our forum? Indicate that it’s about Atahualpa compatibility and ask for Dominykas. He is handling theme compatibility. Thanks!