We’ve talked about it before, but I think that we never really gave a comprehensive guide about translating themes and plugins. Here goes.

Translation Languages

First, let’s talk a minute about which languages you’re translating between.

If the default language of your site is English, you can just skip this section. Otherwise, please pay full attention – this is important stuff.

Your theme and plugins needs to be translated from English. Even if the default language for your site is Spanish (for example) and you’re translating only to Portuguese (yet, another example), English is involved too.

The original language of almost all themes and surely all plugins is English. If you’re using .mo files, they would include translation from English to both Spanish and Portuguese. Yup, although you don’t have English anywhere in your site’s contents, it still appears in many places, so you actually need to translate from English to your languages.

Normally, folks don’t need to worry too much about it, because they just download .mo files. So, why are we making a big deal of it?

Because WPML’s String Localization mechanism works exactly like GetText. It will translate everything from English to other languages. This means that if you’re using it also to translate admin texts, these texts need to be in English. We’ve talked about this a bit (with an example) in this blog post.

How to Translate

Now that we understand which languages to use, we need to start translating.

WPML gives you two options for translating strings. You can either use the GetText .mo files or use WPML’s String Translation mechanism.

These two solutions are functionally very similar. There’s also no performance difference. The only difference is the process you’re using.

Have a look at our theme localization guide. It shows exactly where to click and what to do to scan your theme and plugins.

Translating With WPML’s String Translation

WPML’s String Translation editor allows you to enter translations for each string in each language. It’s a simple editor, with search functionality. This interface is convenient if you’re translating for yourself, or if your translators already have WordPress user accounts.

In case you’re using our professional translation, your translators don’t need to touch the String Translation editor or log in to WordPress. Just click on the button to send the strings to your translators and you’re done.

Translating Using .mo Files

MO files are like dictionaries, telling how to translate strings from on language to another. You would need to have as many MO files as your site’s languages.

The process of translating with MO files goes like this:

1. Create a POT file with the strings to translate. There are many tools for that. WPML includes a robust PHP scanner and can produce these POT files for you.
2. Send the POT files to your translators. You might want to know that ICanLocalize also provides translation service for PO / POT files. You’re also welcome to learn more about it in the tutorial on translating PO and POT files.
3. Get the PO and MO files from the translators and upload to your site. Each translator should return at least a PO (Portable Object) file. The PO file is the text version of the translation. From that, you can create a MO (Machine Object) file.

How is it Working for You?

Leave a comment and tell what you’re doing for theme and plugins localization!

But, with great power comes great responsibility. WordPress 3.0 is a major change from previous versions. True, it uses the same tables, but a lot of the API has changed. This can cause existing plugins and your theme to go wild.

I’d like to tell about what we did to make sure everything runs smooth after the migration.

Migrating to WordPress 3.0

1. Backup

First, you should do a complete backup. I just zipped everything from the wordpress directory (including WordPress core itself). Then, created a database backup.

You can make selective file backup as well, but a few more MB of backup are not going to hurt anyone and its way easier to use, should anything go wrong.

2. Create a test site

Going from WordPress 2.9.0 to 2.9.2 is pretty safe, but the jump to WordPress 3.0 calls for a staging site.

Create a new test site and unzip the files backup you made before.

Next, you need to copy the database.

For this, you can’t just copy. You need to edit the SQL dump. Open any text editor and do a global replace for the site’s domain. Supposing your live site is www.justgreat.com and your staging site is dev.justgreat.com, replace all:

www.justgreat.com -> dev.justgreat.com

This SQL dump replacement means that everything in the staging site goes to the correct URL. Now, you can apply the database.

3. Check that your test site is good

So far, we haven’t done much. We just have a full copy of our live site where we can test on. Check that it works correctly and we’ll move on.

4. Update to WordPress 3.0

And, we’re ready. Now, get the latest WordPress nightly build. Unzip it over your current version in the staging site.

Log in to the WordPress Admin. The first thing you’ll see if that WordPress suggests to update the database.

And, you’re done. Now, you’re seeing how your site looks like in WordPress 3.0.

Is it working?

GetText is a GNU’s text localization package. It allows replacing text in one language with texts in another language.

We’ve already talked about using GetText to build multilingual themes. Now, we’ll talk about how to make the theme’s texts translatable, from the translator’s point of view.

Complete sentences only, please

Translators cannot accurately translate single words. They need to see the entire sentence in order to translate correctly.

For example, what does You must be mean?

In English, the word be has one meaning. But, in Spanish, be mean what you are (ser) or where you are (estar). There’s no way a translator can translate this correctly without seeing the entire sentence.

This is the code that’s responsible for the text:

<?php _e('You must be') ?> <a href="<?php echo get_option('siteurl'); ?>/wp-login.php?redirect_to=<?php echo urlencode(get_permalink()); ?>"><?php _e('logged in') ?></a> <?php _e('to post a comment.') ?>

So, what do we do?

Using full sentences with placeholders

What we’ve actually done in this example is concatenate several parts into a sentence. The way we did it broke the sentence into different pieces, losing all meaning in the process.

Here is this same thing, built with a single sentence a placeholder:

<?php printf(__( 'You must be <a%s>logged in</a> to post a comment' ), ' href="'.get_option('siteurl') . '/wp-login.php?redirect_to=' . urlencode(get_permalink()) . '"') ?>

What we’ve done is:

1. Create one large text that includes a placeholder.
2. Use printf to replace the placeholder with an actual value.

The translator now needs to translate this sentence:

You must be logged in to post a comment

The translator can easily translate this entire sentence.  No questions to ask and no problems translating!

Besides being easier to translate, we need to remember that in different languages words appear in different order. Supplying the complete sentence with placeholders will allow the translator to flip the order of words and produce grammatically correct (and sensible) transaltions.

Really advanced case (appears in every WP site)

Look at this PHP code. It appears in almost every WordPress site in the comments section.
<h3><?php comments_number(__('No Responses'), __('One Response'), __('% Responses') );?>
<?php _e('to') ?> &#8220;<?php the_title(); ?>&#8221;</h3>

The translator would have to translate the word to. But, it’s impossible without understanding how to is used in the sentence.

The word to is part of a sentence, which would be:

3 Responses to new widgets

Once the translator sees the entire sentence, it all becomes clear and easy to translate.

To turn this into a single sentence, we’ll use this PHP code:
<h3><?php printf(__('%s to %s'),
get_comments_number_ml(__('No Responses'), __('One Response'), __('% responses') ),
'&#8220;' . get_the_title() . '&#8221;')?></h3>

This code produces a full sentence to translate. Now, the translator can produce correct translation to your comments heading.

Note: we’ve replaced the standard WP get_comments_number with an identical function that returns the comment count as a value and doesn’t echo to the screen. You can download this PHP code from get_comments_number_ml.zip.

What about your themes?

Are your multilingual themes built for correct translation?

An easy way to test is to open your .po file in poedit and review the strings. If you’re seeing anything that isn’t clear by itself, look for it in the source and revise.

In this guest post, Wolf-Dieter Grabner, tells about building a multilingual corporate site using WordPress, Thesis theme and WPML.

Wolf-Dieter gives both the why and the how, which are equally interesting. It shows how WordPress is used as a time saving tool for both the web developer and the client.

The Client

SBA Roll Shop Solutions is one of the leading manufacturers of roll grinders. While most of us haven’t seen these high precision devices in real life, a lot of everyday products like paper or metal foils depend on extremely even rolls.

In January 2010 SBA approached me through one of my clients, asking me for a new homepage, as the old one was still based on frames and static HTML pages.

We had a short time available, because there was an upcoming conference in South America that the company was going to attend so designing the website first and writing the content afterwards was not a good option. I supplied the members of the company’s marketing with a basic setup of WordPress and Thesis and they could easily start writing the content right away.

WordPress and Thesis

What I really like about WordPress is the ease of use in comparison to other content management system for this type of site (for example Typo3 or Drupal). If you can use a text editor or word processor, you’re ready to use WordPress. Thanks to plugins like WordPress Multi Language (WPML), even very complex sites work surprisingly well.

Clients often have problems imagining a prototype or draft version if is looking too rough and unfinished. After using quite a lot of open-source and custom-made templates, I have been switching to Chris Pearson’s Thesis Framework for all recent projects: I find it to be the best solution to design prototypes. It is very easy to customize, once you are accustomed to the use of the custom CSS file and the template’s hooks system. By keeping the template and the adaptions for the individual site separate, updating the template does not imply any changes to the site.

Going International

Right from the start, SBA wanted the site to be available in multiple languages. About one month after the English version, also the Chinese version went online; German will follow.

Setting up WPML took about five minutes. Apart from choosing the languages, almost nothing was changed from the defaults.

Using WPML with Thesis

Thesis’ default drop-down menu is quite nice as you can rearrange the items in the theme’s preferences and also rename pages. Nevertheless, it does not work with WPML right out of the box: it’s showing all languages of an individual page at the same time instead of just the current language.

As an alternative, one can use WPML’s drop down menu but it does not support more than two levels, which was not meeting the client’s requirements. Navigo 1.2 offers XHTML strict output, works with WPML and offers custom classes and IDs for formatting the drop down menu. It proved to be a nice companion to Superfish, a jQuery enhanced drop down menu.

Using Thesis custom_functions.php, the navigation can easily be added to the template:

Adding your own Navigation to Thesis

function custom_thesis_nav_menu() {
    echo ('<div id="top-nav"><div id="top-nav-fix">');
    if(function_exists('navigo')) {
      navigo('sort_column=menu_order&level1=sf-menu&level2=l2&level3=l3');
    }
    echo ('</div></div>');
}

remove_action('thesis_hook_before_header', 'thesis_nav_menu');
add_action('thesis_hook_before_html', 'custom_thesis_nav_menu');

The example shows a simple function that’s creating the needed nesting and also calling navigo with some parameters to get the desired markup.

After removing the default Thesis navigation, the new function is added to the appropriate hook. Two div-tags were used to fix the position of the drop down menu even when scrolling the page. After adding the Superfish CSS markup to the template’s custom.css file, everything works nicely. When not pinning the menu to the top of the page, you can of course use thesis_hook_before_header for it. The following source snippet allows you to use the default drop down menu of WPML with Thesis:

function thesis_navigation_wpml() {
    do_action('icl_navigation_menu');
}

remove_action('thesis_hook_before_header', 'thesis_nav_menu');
add_action('thesis_hook_before_header', 'thesis_navigation_wpml');

Breadcrumb Navigation

Because of the large number of pages, we have also added WPML’s breadcrumb navigation to the site. Again, by using custom_template.php, it’s a matter of minutes:

function custom_thesis_WPMLbreadcrumbs() {
    echo ('<div id="breadcrumbs">');
    do_action('icl_navigation_breadcrumb');
    echo ('</div>');
}

add_action('thesis_hook_before_content', 'custom_thesis_WPMLbreadcrumbs');

Add some custom styles to custom.css and you’re done.

Experience and next Steps

WPML works just the way it should – even details like the XML sitemaps plugin. Being able to teach via Skype a Chinese sales person how to use the tool for translating the site is certainly a good thing.

About the author

As a photographer with an engineering background and a business degree, Wolf-Dieter Grabner regularly works for clients like Coke, Universal Music, the Vienna Musikverein or Austrian petrol company OMV.

He’s lecturing visual communications at Linz University for Art and Industrial Design and still, he enjoys working on web projects a lot. One thing all his jobs have in common? Changing perspectives and bringing new views.

The video (3 minutes)

Steps to follow

1. Go to the WPML menu and click on Advanced.
2. Go to Theme localization.
3. Select to translate the theme using WPML.
4. Make sure that the language locales are set correctly and that the WordPress .mo files are found in wp-includes/languages.
5. Review your themes strings and click to translate untranslated strings. This will send you to WPML String translation page.
6. Click on translations, next to each string, translate and save.

Any edits that you make in WPML’s translation interface will appear in the site immediately. You don’t need to upload anything or change anything in the theme.

To work, the theme needs to be multilingual-ready. All strings need to be wrapped in gettext calls and have a textdomain argument. This is already standard practice for most WordPress themes. If you’re creating your own theme, you can check out the post about how to build a multilingual-ready theme.

More reading

• Theme localization in WPML’s getting started guide
• Building multilingual themes (the comprehensive guide)

The idea for this post came from a discussion in the forum about sharing custom fields and media between translations.

The goal -  a multilingual product catalog with WordPress

To set up my small bilingual shop I didn’t want to use a complex e-commerce CMS, WordPress was just the right thing for what I needed. Also I was looking forward to testing the WPML plugin on a slightly more complex project than the usual classical blog or website.

So, in my English/French online catalog, the products are each described in a dedicated post. To add a product I simply add a post in the back-end of WordPress, giving it the name of my product as title, typing the description in the content text-area, uploading the products photos to the images gallery of the post, and using the custom fields for values like price, reference and size.

Here’s how a product post in English (the default language) would look :

Now, after creating the original post for a product, how do I create the translated (French) version of it? Following WPML’s instruction, I simply click on the Language box under the post content window, click on “show” next to “Translations” and then click on “add”. It opens up a new post page where I can type in all the translated informations of my product : French title, French description, etc.

Problem – translations duplicate product information

But wait! Here is the annoying thing. I also have to type in again the custom fields values: reference, price and size. In my case those values are the same in any language so it makes no sense having to enter them twice. This is an obvious problem that would make me lose a lot of time if I had to type in the same information multiple times for each product post translation.

It’s the same issue with the product images, I don’t want to upload all the product photos a second time for the same product in it’s translated version. Logically, product photos are the same in any language, so I should be able to upload them only once.

So, let’s save the translated post just like this, without typing in a translation for the custom fields and without uploading the product images.

Ok, now let’s have a look at some code. Here’s a very basic example of a product listing page for a category (usually the archive.php file of your WP theme) :

<?php while (have_posts()) : the_post(); ?>
  <ul class = "product">
    <li class = "title"><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></li>
    <li class = "ref"><?php echo get_post_meta($post->ID, 'Reference', true); ?></li>
    <li class = "price"><?php echo get_post_meta($post->ID, 'Price', true); ?></li>
  </ul>
<?php endwhile; ?>

That’s the classical loop. It shows a list of my products and the associated custom field values – Price and Reference.

Now if I click on another language in the language selector on the front-end of my website (French in my case), it shows the translation of the articles title, but it doesn’t show the reference and the price value. That’s normal, remember we didn’t enter them in the translated post..

So, how do I get WordPress to show the custom values I entered in the original English post ?

Solution – sharing custom fields between translations

Well, WPML is a powerful plugin that provides us with a very useful function to fetch those values from the original post, even on the translated pages.

We are going to use the icl_object_id() function and replace the previous code by the following :

<?php while (have_posts()) : the_post(); ?>
<?php
  // Get the original post ID (in my case the english one)
  $o_ID = icl_object_id($post->ID, 'post', false, 'en'); ?>
  <ul class= "product">
    <li class = "title"><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></li>
    <li class = "ref"><?php echo get_post_meta($o_ID, 'Reference', true); ?></li>
    <li class = "price"><?php echo get_post_meta($o_ID, 'Price', true); ?></li>
  </ul>
<?php endwhile; ?>

Basically what we did was to retrieve the ID of the original post corresponding to any translated post, and using this ID to get the custom values. Depending on the original language of your posts, you can change the last parameter of icl_object_id (‘de’ for German, ‘fr’ for French, etc.). You can get more information about the other parameters of this function here and a list of other functions in the coding API page.

That was for the custom fields, now how do I do the same with the image gallery?

Let’s take our first example and also show three thumbnails images for each post in the list:

<?php while (have_posts()) : the_post(); ?>

<?php
  // Get the original post ID (in my case the english one)
  $o_ID = icl_object_id($post->ID, 'post', false, 'en'); ?>

  <ul class= "product">
    <li class = "title"><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></li>
    <li class = "ref"><?php echo get_post_meta($o_ID, 'Reference', true); ?></li>
    <li class = "price"><?php echo get_post_meta($o_ID, 'Price', true); ?></li>

<?php

  // Get 3 thumbnails from the original post
  $args = array('post_type' => 'attachment','numberposts' => 3,'post_status' => null,'post_parent' => $o_ID);
  $attachments = get_posts($args);
  if ($attachments) {
    foreach ($attachments as $attachment) {
      echo '<li class="thumbnail">'.wp_get_attachment_image($attachment->ID).'</li>';
    }
  }
?>
</ul>

<?php endwhile; ?>

Summary

You can easily customize this little script to fit your needs, showing more (or less) images or different sizes.

That’s it. Now we can show our product list in any language, and it will always contain all the product custom fields and images, even if technically these are only stored in the original post.

This gets really interesting for bigger catalogs with more languages. Imagine you have to change the price of a product in five languages. With the normal method you would have to edit all five posts. With this easy method you always have one “master” language with its posts containing the complete information about your products and translations reusing it.

Michael Wassmer is a freelance web designer based in Barcelona, Spain. You can contact him at mike@michaelwassmer.net

WPML is getting a major usability overhaul (by Joen Asmussen). This includes the WPML plugin and wpml.org. We’re going to do vast website changes, including theme edits, changes to page hierarchy and the addition of new pages.

These changes can’t be done gradually. We need to build everything offline and then deploy to the production server. However, we can’t just copy the database over as the site is running. During this update, we’re still going to write new posts and people leave comments.

We need to figure out a way to take a snapshot of the current site, work on the changes offline and then apply all the changes at once and merge with new content that’s been created on the live site.

Here is a diagram of that process:

A search in WordPress Codex for staging, reveals some interesting discussions about this, but nothing conclusive nor usable. People agree that it’s a problem, but no one has yet to create a full working process that can be used for any WordPress site.

The biggest challenge is merging between the development version and the live site. Remember that the live site keeps running while we’re working on the development version. When we update the live site with the new development version the new theme will upload, new pages created and some existing pages update. However, blog posts and comments that were written during that time will be preserved. It’s not trivial to do as posts and pages share the same table in WordPress.

The things that will need to move from the development site to the live server:

1. Everything from wp-contents, including the theme, new uploaded files and plugins.
2. New entries in the wp_options table. These entries control the way the site and plugins are configured.
3. New pages and updates to existing pages.

Many of our blog readers are professional designers and developers, so your feedback is very helpful. Do you have a process for moving a site from development to production? How do you handle major updates?

I’ll show a solution that doesn’t require any plugin, doesn’t go through an external service and doesn’t create any load on your site.

WordPress has default link aliases to every page

Let’s start with an example. This page talks about using Contact Form 7 multilingual:

http://wpml.org/wordpress-translation/translation-for-texts-by-other-plugins-and-themes/how-to-use-contact-form-7-in-multilingual-websites/

Do you think that’s a long URL, check out the Japanese version:

http://wpml.org/ja/%E3%83%9E%E3%83%AB%E3%83%81%E3%83%AA%E3%83%B3%E3%82%AC%E3%83%AB/%E3%81%9D%E3%81%AE%E4%BB%96%E3%81%AE%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E3%81%A8%E3%83%86%E3%83%BC%E3%83%9E%E3%81%AB%E3%82%88%E3%82%8B%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E7%BF%BB%E8%A8%B3/contactform7-m17n-steps/

It’s got 306 characters! Doesn’t even fit into two tweets.

But, try these two:

• http://wpml.org/?page_id=2496
• http://wpml.org/?page_id=2476

These are actually links to the same pages. There’s no magic here. These are the default-format links to those pages. Every page, post, tag or category can be accessed via its default link as well as its fancy link. It’s built into WordPress and doesn’t rely on anything else.

And, here is the function that produces those links:

function wpml_default_link($anchor){

  $qv = false;

  if(is_single()){
    $qv = 'p=' . get_the_ID();
  }elseif(is_page()){
    $qv = 'page_id=' . get_the_ID();
  }elseif(is_tag()){
    $tag = &get_term(intval( get_query_var('tag_id') ), 'post_tag', OBJECT, 'display');
    $qv = 'tag=' . $tag->slug;
  }elseif(is_category()){
    $qv = 'cat=' . get_query_var('cat');
  }elseif(is_year()){
    $qv = 'year=' . get_query_var('year');
  }elseif(is_month()){
    $qv = 'm=' . get_query_var('year') . sprintf('%02d', get_query_var('monthnum'));
  }elseif(is_day()){
    $qv = 'm=' . get_query_var('year') . sprintf('%02d', get_query_var('monthnum')) . sprintf('%02d',get_query_var('day'));
  }elseif(is_search()){
    $qv = 's=' . get_query_var('s');
  }

  if($qv){
    $link = '<a rel="nofollow" href="' . get_options('home') . '?' . $qv . '">' . $anchor . '</a>';
  }else{
    $link = '';
  }

  return $link;
}

What it does is:

1. Determines what kind of page you’re looking at now.
2. Constructs the default URL for that type of page. It’s different for pages, posts, tags, categories and archives.
3. Creates a link to that URL.

Adding short links to your pages

You can copy the function from above and paste it to your functions.php file. This will make it available to all the files in your theme. Then, add it somewhere. I think that the footer is a good place, but you choose for yourself.

For wpml.org, we’ve added it to footer.php, making it look like this:

Now, whenever I want to send someone a link to a page on my site, I just use that URL. When visitors come to that URL, they will be redirected by WordPress to the permalink (the fancy URL).

To include in footer, I added this code:

<?php echo(wpml_default_link(__('Short link to this page','yourtheme'))); ?>

Using WPML? It’s already built in!

WPML includes a set of theme helper functions, stored in a file called docs/theme-integration/wpml-integration.php. Just copy that file to your theme’s directory and include it from functions.php. It will already contain a modified version of that function (which also includes the language path), so you can go ahead and use in your theme.

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() ?>

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

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

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.

We’ll go over the theme used for nadelspiel.com, a German site about hand made needle sewing.

Things that need to change to go multilingual

nadelspiel.com uses a theme based on the very popular arthemia theme. It mixes between a magazine and a blog.

nadelspiel’s theme needed several changes in order to become truly multilingual:

1. Like all arthemia based themes, category IDs are hard coded to the theme’s PHP. WPML assigns a different ID to translations, so these hard coded IDs needed to be changed to dynamic IDs.
2. All the texts in the theme needed to wrapped in gettext calls, so that they’re translated using the theme’s .mo file.
3. The home link needed to change, so that it points to the home page in each language.
4. A language selector needs to be inserted.

We’ll go over each of these items and show how the theme’s files changed.

Hard coded category IDs

This is probably the biggest challenge when it comes to running multilingual sites that use complex themes. The arthemia theme includes a special featured articles box and also highlights certain categories. To do this, the category IDs are hard coded in the theme’s index.php file.

Since in WPML, translations for the category will receive different IDs, some translation is required.

Before:

<?php query_posts("showposts=1&cat=NN"); $i = 1; ?>

After:

<?php query_posts("showposts=1&cat=".icl_object_id(NN,'category')); $i = 1; ?>

What this does is use WPML’s ID translation function (icl_object_id), to convert from the category ID in the default language to the category ID in the actual language displayed.

Localization for texts in the theme

This is relatively straight forward. All the texts in the theme need to be wrapped in gettext calls. Then, you create a .po (or .pot) file that includes all the strings to translate, translate them and create a .mo file with the translations.

You can read about this in details in our previous post about localizing WordPress themes.

Changing the link to the home page

Normally, when you click on the site’s logo at top left corner of any page, you get to its home page.

When the site runs in a single language, its home page is found in the Blog address (URL) in Admin->Setting->General. The theme can access this value by reading get_option(‘home’), so normally people implement the home page link using:

<a href="<?php echo get_option('home'); ?>/"

To adapt the home page so that it points to the correct URL per language, this needs to be changed. WPML supplies its own home page URL function, which we’ve used for nadelspiel as well:

<a href="<?php echo icl_get_home_url() ?>"

You can read more about this where we talk about the home page link.

Adding a language selector

nadelspiel’s theme includes multiple widget zones, so adding WPML’s drop-down language switcher is very simple. We just add it to one of the widget zone and we’re done.

In case you need fancier language switchers, like a horizontal list of all languages, you can add a custom language switcher.