Custom multilingual themes
This guide will show you how to create multilingual WordPress themes. A multilingual theme is more than just wrapping all the texts in GetText calls and providing a .mo file. Localizing the theme’s texts is one major step, but there are other things that have to be done.
A theme for a multilingual site needs to show available languages, allow selecting which language to view in and display correctly in each language.
These are the things that we’ll need to do:
- Providing localization for different languages.
- Allowing users to switch from one language to the other.
- Adjusting links in the theme so that they point correctly in different languages (like the home page).
- Returning the right content per language.
- Translating texts entered in the theme’s admin screen.
Making the theme multilingual-ready with optional support for WPML
WPML includes a set of helper functions which allows themes to run multilingual when WPML is installed or run in a single language otherwise. These functions make it possible to build themes that are multilingual ready without requiring that WPML be installed.
WPML’s helper functions are stored in WPML’s folder under docs/theme-integration/wpml-integration.php. To use those functions, copy that file to your theme’s directory and include it in your functions.php file. At the end of functions.php file (but before ?>), add:
include "wpml-integration.php";
Now, you can start using these helper functions to make your theme multilingual ready (but still run normally without any plugin installed).
Getting the theme ready for translation
In order for the theme to display in different languages, the texts need to pass translation before they are displayed. WordPress uses GetText for this and so should your theme.
We’ve written a post about localizing WordPress themes. It tells how to wrap the theme’s texts in GetText calls, create translations (.mo files) and apply them to the theme.
Switching between different languages
A language switcher shows visitors which languages are available and lets them choose.
Language switchers can come in different forms. Some people prefer a compact drop down menu with language names. Others display country flags and others show horizontal or vertical lists of languages.
WPML makes implementing language switchers easy. It comes built in with its own drop-down language switcher which can also be included as a widget. This language switcher can display country flags, language names and their translations. It can be configured from the Languages menu.
You can also create your own custom language switcher and insert to different places in the theme. The custom language switcher manual page explains how you can create it and provides examples for common uses.
To add an language switcher to your theme, you can use one of these helper functions from wpml-integration.php. If WPML is enabled the language switcher is added.
| Function | Where to add | What you get |
|---|---|---|
| wpml_languages_selector() | Added once for the site, normally to the header or sidebar. | A drop down list with language names. This language switcher can be controlled from WPML’s languages admin screen. |
| wpml_languages_list() | Normally added to the footer or sidebar. | This function creates a list of languages available. Optional arguments specify what to do for untranslated contents and which DIV to wrap the list in. |
| wpml_content_languages() | Normally appended to post contents. | This will show visitors in what other languages posts or pages are written in. |
Home page link
The home page link is a unique link in your site. It’s the only page where only the URL is provided and not the name of the page itself.
When you go to http://example.com/ you’re actually referring to page ‘/’ of domain example.com. WordPress will automatically redirect from http://example.com to http://example.com/.
We’re explaining this because this is very relevant for creating the home page link correctly. The normal WordPress practice is to create the home page link using this statement:
<a href="<?php echo get_option('home'); ?>/"
What this does is get the URL of the site (the get_options(‘home’) call) and append a trailing ‘/’ to it.
This habit isn’t possible to use when running multiple languages. The default language is indeed still in http://example.com, but other languages can be in different URLs. Instead, use this function from wpml-integration.php. If WPML is enabled, it will link to the correct home page per language. Otherwise, it will just link to the site’s home page.
<a href="<?php echo wpml_get_home_url() ?>"
You should use it in all places where there is a hard coded link to the home page.
Adjusting links
Many themes include hard-coded link to pages, categories and tags.
WPML includes a function that allows linking to pages, posts, tags and categories so that both link text and URL show in the correct language.
If your theme includes hard-coded links, replace them with WPML’s auto-adjusting multilingual links. To do this, replace hard-coded links with this function:
wpml_link_to_element($element_id, $element_type='post', $link_text='', $optional_parameters=array(), $anchor='')
If WPML is active, it will create language dependent links (both the URL and the anchor text). Otherwise, this create a regular link.
Returning the right contents per language
Some themes display a ‘featured posts’ or ‘news’ box on their home page. They allow selecting which posts to show there based on category IDs. When using WPML, the category IDs of translations will be different than the default language, so these IDs need to adjust.
To do this, use the following helper function, which returns the correct IDs according to the active language.
wpml_get_object_id($element_id, $element_type='post', $return_original_if_missing=false, $ulanguage_code=null)
When WPML is active, this function will return the ID of the object that corresponds to the object in another language. For instance, if you enter the ID of the English category, you will get the ID of the translation for this category in the current language. If WPML is not active, this function will just return the same value.
Translating texts entered in the theme’s admin screen
If the theme’s admin screen includes text entry fields that are later displayed in the theme, these texts need to be translated too. They cannot be translated using the theme’s .mo file as they are dynamic texts (entered by the user) and the .mo file is created when the theme is built.
To do this, the theme needs to tell WPML that there is something that needs translation. Then, it needs to display the translation.
To tell WPML that there is text to translate, use this function:
wpml_register_string($context, $name, $value)
- $context – puts the string in its right context. Normally, you would put your theme’s name (doesn’t get translated).
- $name – something that identifies the text (doesn’t get translated).
- $value – what gets translated.
To display the translation for the string, use this function:
wpml_t($context, $name, $original_value)
The arguments are the same. The $original_value is supplied too, so that if there’s no translation available, it is returned. Otherwise, the translation for the current language is returned.
Avoiding relative links
Some themes contain relative links to stylesheets, images, Javascript and other files placed in the theme’s directory. This will most surely cause problems when running multilingual.
Different language contents will almost always reside in different URLs. If you use relative links, they will be wrong and the files that need to be included will be missing.
You should always calculate absolute links to other files in the theme directory. WordPress can provide the full URL to your theme. For example, if you need to link to a favicon, located in the theme’s directory use:
<link rel="shortcut icon" href="<?php bloginfo('template_url'); ?>/favicon.ico" />
This will produce the absolute URL to the favicon and would be correct regardless of the URL structure used.
Want to get paid when we get paid?
If you’re creating themes you can add an affiliate code and get paid a 30% commission for every translation job that we do on sites running your theme. This affiliate code is passed as a variable to WPML, which would store it when creating accounts in our system. It doesn’t go out and is not displayed anywhere.
This is what you need to do:
- Create an account in ICanLocalize.
- Log in to your account and click on the Affiliate tab.
- On the top right, you’ll see a box labeled Affiliate information. It shows your affiliate ID and key.
- Add the affiliate ID and key to your theme. Best to place in functions.php.
define('ICL_AFFILIATE_ID', YOUR_ID);
define('ICL_AFFILIATE_KEY', YOUR_KEY);
Once you’ve added those, it’s a good idea to contact us, so that we can go over it and make sure it’s been added correctly and we can see who came in through your theme.
You can use the same ICanLocalize account for any number of themes, so if you’re doing several themes, just paste the same code and you’re done.
English
简体中文 
Deutsch 
日本語 
Español 
Subscribe via RSS
Follow
Hello, great plugin, It work prefect,
But I have change all my hard coded link in thme , but How to change the image localised for the theme (same as your logo in multilanguage but for other images on my theme).
thanks.
WPML doesn’t yet include any built in support for localizing images (service different images for languages).
You can implement it yourself using some simple PHP, which will check the current language and determine which image to display. I would just create different folders for each language and prefix that to the image path.
ok,
Thank you very much.
For other :
the function to check the current language and determinate which image to display is here and work :
http://forum.wpml.org/topic.php?id=164#post-1288
Hi, where it says ‘At the end of functions.php file, add:
include "wpml-integration.php";Now, you can start using these helper functions to make your theme multilingual ready (but still run normally without any plugin installed).’
I think it should say ‘At the end of functions.php file, but before the ?>’, add:’
I’ve been taking some instructions literally and learning some things the hard way.
[...] Cómo crear temas multidioma en WordPress Comparte esto [...]
How to e.g. show the list of languages inside a post? Is there a post tag code lige <<>> to put in a post or page, that will be swapped with the list of languages?
Best regards
Svend K.
Hi I wanted to post a quick-fix for relative links. I use Inline Posts plugin to have a single edit point for a table which is in three different pages – one for each language.
For example, my images are all kept in “/wp-content/uploads”. I have three languages, English, French, Spanish. My WordPress install folder is “wordpress2″.
Add this to your WPML active .htacces file:
#strip lang code for images
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} ^/wordpress2/(en|fr|es)/(.*)\.(jpg|gif|png)/?$
RewriteRule /(.*) $1
#redirect ‘safe’ url (lang code removed)
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} ^.*/+$
RewriteRule (.*)\.(jpg|gif|png)/+$ $1.$2 [L]
#redirect when there’s no prefix slash, prevents looping
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/wordpress2/(en|fr|es)/?
RewriteRule (.*) /wordpress2/wp-content/uploads/$1 [L]
#redirect when there’s a prefix slash
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/wordpress2/wp-content
RewriteCond %{REQUEST_URI} ^/wordpress2/(.*)\.(jpg|gif|png)/?$
RewriteRule /(.*) /wordpress2/wp-content/uploads/$1 [L]
before these default lines:
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.) /wordpress2/index.php [L]
# END WordPress
Hello,
Congratulations for your fantastic work.
I have a worpress site, with its own theme, and I am using iframes. The iframes are not translated (although the strings are). What is the instruction to tell a php page contained in an iFrame to be properly translated?
Many thanks!!!
Philippe
Hi,
Thank you for this excellent plugin. I have a small problem with page menu. On the default language (French), we have a menu on the top. When I select the second language (English) through the UK flag on the top-right, the top-menu disappears. Can someone advice me?
Regards,
GM.
You descripe my problem;
“Returning the right contents per language
Some themes display a ‘featured posts’ or ‘news’ box on their home page.”
But where must I build in the helper function:
wpml_get_object_id($element_id, $element_type='post', $return_original_if_missing=false, $ulanguage_code=null)in functions.php or home.php or am I missing something??
thanks
Don’t worry about that. WPML 1.7.0 (coming out soon) is going to make all this logic obsolete. It will automatically adjust your theme’s queries to return results in the right language.
This will include those ‘featured posts’ and anything else you can do in a WP theme. Stay tuned to the blog, we’ll introduce it there.
dear Amir, WPML is now at version 1.7.6 and it still has the same problem: it does not show automatically the right posts if you switch languages. How can one do this? I still have the same question as Lindebjerg! I do not know where to use this helper function:
wpml_get_object_id($element_id, $element_type=’post’, $return_original_if_missing=false, $ulanguage_code=null)
I and many others would be happy to get a clear solution to this!
Mihai, WPML’s lead developer is watching the forum and helping folks there. Did you post this question there?
Sounds great! Looking foreward too WPML 1.7.0
But I need to bring a concept for this site http://keine-werbung-bitte.de in a few days.
Maybee you could just show me on this piece of code here:
have_posts()) : $recent->the_post();?>
ID, "thumb", true) ): ?>
<a href="" rel="bookmark"><img class="thumb" src="/tools/timthumb.php?src=ID, "thumb", $single = true); ?>&h=&w=&zc=1" alt="" />
how too make the changes, too understand a bit more for me and maybee a few people out there.
Thank you for doing yours to makeing WordPress the best CMS in the World:-)
something went wrong, sorry
here the code again:
have_posts()) : $recent->the_post();?>
ID, "thumb", true) ): ?>
<a href="" rel="bookmark"><img class="thumb" src="/tools/timthumb.php?src=ID, "thumb", $single = true); ?>&h=&w=&zc=1" alt="" />
My Navigation menu and pages widgets disappears when I switch to any language other than English, how do I solve this? I know thre is an answer some where do damned if I can find it!
Hello,
i’m french and my english is not very good, I have a problem with my theme, the link to the home page is working but not translated when i switch in english
Her is the code in the header: have you an idea ….
<a href="” title=”Accueil”>ACCUEIL
excude me here is the entire code //<a href="” title=”Accueil”>ACCUEIL
//
[...] linguagens em todo o seu temas, imagens e etc. O próprio plugin tem um tutorial sobre isto chamado creating multilingual wordpress themes, muito bom e simples, ja estou usando aqui no site, e apresentou ótimos resultados. Submit this to [...]
Hi there I was wondering what code to use to tell WPML to Not translate or change a particular section of the home page.
On the front page I have the picture slideshow that is being affected by this and there is also a live feed from the blog menu that is also getting affected by this.
Thank you for your help.
I will also add to that in the theme that I am using some of the text are not being picked up by the string translation system.
I was wondering how I could adjust the php pages so that WPML could pick up on those ares?
Hi.
Congrats for your well fasntastic plug-in.
I am quite new to WP and not a php developer. My theme has a Menu Manager and a also a Menu Manager for categories – (I am using newscast theme from Kriesi.at). WPML does not interact with this admin menu. So, I cannot localise the Menu neither the Categories menu. I guess this data goes into the database. I am quite lost. Can I do something in the theme admin pages so that WPML adds language fileds to the menu managers?
BR
dinis
Again.
I guess the solution ought to be in the “Translating texts entered in the theme’s admin screen” section right?
Another idea,
There should be a way that the theme saves the menu items to the database as a _e() or __() and when it is retrieving them, WPML will translate those. At some point, I should have a place where to write the final language outputs … Do you think it might work that way?