1. Code
  2. WordPress

How To Make Your Theme Multilingual and WooCommerce Compatible

Sponsored Content

This sponsored post features a product relevant to our readers while meeting our editorial guidelines for being objective and educational.

Matt Mullenweg, who is the co-founder of WordPress and the CEO of Automattic, was interviewed by Josh Janssen, where he stated that in May of this year the non-English downloads of WordPress for the first time exceeded the English downloads.

This trend continues with WordPress 4.0 which makes localized WordPress sites so much easier to install and maintain. WordPress 4.0 now gives you the ability to download WordPress in the language of your choice. This will make the installation process a breeze for non-English speakers. In previous WordPress versions, English was the default and other languages were treated as exceptions. WordPress 4.0 makes all languages equally accessible. This change will surely make WordPress even more popular around the world.

The goal of these new features in WordPress 4.0 is to bring an increase in the number of international users of WordPress, who were previously unable to use WordPress due to the language difficulties. What’s more is the Asia-Pacific countries like China, Japan, India, South Korea, and Indonesia are projected to overtake North America in Business-to-Consumer eCommerce sales, according to eMarketer.

What does that mean for you as a theme or plugin developer? First, it means that your product must be ready for localization. All texts have to be wrapped in `gettext` calls, allowing users to run it in other languages; however, internationalization is only the first step. In many countries, being able to run a site in only one language is a major limitation. To truly go global and tap into the huge potential outside of the English-speaking market, your products should also be multilingual-ready.

Fortunately, with WPML, running multilingual sites is easy. We will outline the top seven best practices to follow, so that your themes and plugins work great on both single-language and multilingual sites. By following these simple guidelines and sticking with clean coding, your products can power multilingual sites.

How End-Users Will Translate and What You Need To Be Prepared For

When you develop your theme, it’s critically important to understand how your end-users will translate their sites. Once you realize their perspective, you will realize what you need to do to make your theme multilingual-ready.

A typical theme displays a header, footer, menus, widgets, content and your own custom elements. Here is an example a WooCommerce site, based on a modified Twentyfourteen theme:

WPML descriptionJPGWPML post descriptionJPG

WPML allows you to translate all the standard WordPress elements. This includes:

  • Menus

  • Standard widgets

  • Navigation elements

  • All texts wrapped in `gettext` calls

  • Post content including custom fields and taxonomy

  • Products

  • Theme options

  • Images and strings related to them

You don’t need to add anything in your code to allow all these sections to be translated. Be sure to pay attention to your custom elements, so that your users can translate them, too.

Below is a table, that summarizes how the end-user will translate standard site-elements with WPML. 

What End-Users Can Translate using WPML

Translate the header using WPML String Translation Tool

Since it’s not part of any post, page or taxonomy, we need to use WPML’s String Translation to translate it. Go to WPML->String Translation, search for the string by its content (the title of the site) and translate.

 title of siteJPG

title of site using string translationjpg

Translate WordPress menus

When you go to Appearance> Menus, you will see WPML’s menu translation controls. Learn more about translating menus to see how this works.

Main MenuJPG

Translate Custom Theme or Plugin Elements

Many themes or plugin have unique features, that store texts in the wp_options table. The Introductory Message, by Resort does that exactly.  The theme or plugin saves these texts in the wp_options table and we need to tell WPML to translate them. We add this information to the Language Configuration File. There, we tell WPML which entries in the wp_options table require translation.

This technique is good when the keys the options are fixed (like in most themes). If your theme uses arrays of entries, which may grow with user input, you need to register these entries dynamically. Use WPML’s icl_register_string and icl_t functions to do this.

Custom headerjpg

Translating the Post Body

WPML lets users translate content with ease. The post-edit screens include WPML’s translation controls, allowing to create new translations and edit existing ones.

You don’t need to do anything in the theme or plugin to make this happen. Translating content is a core feature of WPML.

What you do need to check is that any text that your theme adds to the output is translatable.

If you’re new to using GetText, learn more about it in our theme texts translation FAQ.

Post Edit ScreenJPG

Translate Widgets with String Translation

WPML lets users translate the content of text widgets. It also translates titles of all other widgets. If your theme or plugin creates its own custom widgets, make sure that you pass their titles through the standard WordPress filters. This way, WPML will allow users to translate the titles of your widgets via the String Translation screen.

Widgets ESJPGWidget editingJPG

Translating the Footer

 Some themes have a custom admin screen to store the footer texts. Like other texts that we saw, the theme or plugin saved the footer texts in the wp_options table too. We will add these entries to the language configuration file, telling WPML to translate them.

custom footerjpg  

For a full detailed explanation on how end-users will use WPML visit our Tutorial on Achieving Compatibility with WPML.

You do not have to rewrite your entire theme or plugin because WPML handles all of this.  This tutorial is not as hard as climbing Mount Everest, but there are a few things that you will need to edit in order to make it easy for your end-user.

Now that we’ve covered how people will translate the standard WordPress elements, let’s review together what you should do to ensure multilingual-compatibility for your custom elements.

The Top 7 Best Practices To Make Your Theme Multilingual and WooCommerce Compatible

1. Add GetText Functions to Hard-Coded Text

For plugins or themes, be sure to wrap your hard-coded text in `gettext` functions. This includes the header, footer, and widget text. Your template files display an assortment of product information and hard coded text. For example, most templates will include the product name and a ‘buy’ link. The product name comes from the database, so you don’t need to worry about translating it.

You should make sure that all hard-coded texts are translatable, using `gettext` functions.



<p><?php _e(‘Similar products:’, ‘my-textdomain’) ?></p>

<input type=”button” name=”buy-button” value=”<?php esc_attr_e(‘Buy now!’, ‘my-textdomain’) ?>” />

<p><?php echo ‘Similar products:’; ?></p>

<input type=”button” name=”buy-button” value=”Buy now!” />

“Similar products” and “Buy now!” are not wrapped in GetText calls.

Make sure that you use your theme’s textdomain for all GetText calls.

2. Use API Functions to Link to WooCommerce Pages

Many e-commerce themes include special pages, like the ‘cart’ or ‘account’. The theme often includes links to these pages, appearing on every page on the site.

If you use a WordPress menu for these links, you should be all set. WPML displays a different WordPress menu for each language, so the links to these ‘special page’ will be different, per language. However, if you hardcode these links in template files, you need to allow WPML to replace the links, with links to these pages in the right language.

The right way to link to the special WooCommerce pages is by using the WordPress API functions and the WooCommerce page IDs. WooCommerce Multilingual filters calls to `get_option()` with the WooCommerce page IDs. It will return the ID of the page in the current language.



<a href=”<?php echo get_permalink(get_option(‘woocommerce_shop_page_id’)) ?>”><?php _e(‘Shop page’, ‘my-textdomain’) ?></a>

<a href=”<?php echo get_permalink(wc_get_page_id(‘shop’)) ?>”><?php _e(‘Shop page’, ‘my-textdomain’) ?></a>

‘shop’ is the slug of the page in the default language.

<a href=”<?php echo get_permalink(5) ?>”><?php _e(‘Shop page’, ‘my-textdomain’) ?></a>

The ‘shop page’ ID is hard coded. It will be different for different sites and for different languages.

<a href=”/shop”><?php _e(‘Shop page’, ‘my-textdomain’) ?></a>

The ‘shop page’ URL is hard coded. It will be different for different languages.

3. Add Multilingual-Ready Product Listings

If you use the WooCommerce shortcodes to display the product listing, you are all set. WooCommerce will load the products in the correct language and display them.

If you prefer to load products manually, using your own code, make sure that you are using the WordPress API, or WooCommerce API calls. If you access the database directly, WPML will not filter your call and you will get a mix of all of the products in all languages.



[featured_products per_page=”12″ columns=”4″]

[product id=”99″]


<?php $products = get_posts(array('post_type' => 'product', 'suppress_filters' => 0)); ?>


$args = array(

'post_type' => 'product',

'posts_per_page' => 10,


$products = new WP_Query( $args );


<?php $products = get_posts(array('post_type' => 'product')); ?>

suppress_filters will be set to true by default, preventing language filtering.

$products = $wpdb->get_results($wpdb->prepare(“SELECT * FROM {$wpdb->posts} WHERE post_type=’product’ ORDER BY ID DESC LIMIT %d”, 10));

WPML doesn’t filter low-level SQL queries. All products in all languages will be returned.

Once you’ve loaded the right products, you don’t need to worry about languages when displaying them. Each product will come with its own custom fields, with information in the correct language.

4. Add Multi-Currency Payment Options

Some global eCommerce sites need both multiple languages and multiple currencies. Your theme should support those sites that require multi-currency. For many non-American sites, supporting multiple currencies is a very important feature. For example, many European sites will need to charge in Euros, British Pounds and US Dollars. Eastern European sites often require Russian ruble and Asian sites need a variety of different other currencies.

Currency SwitcherJPG

Multi-currency support is included in WooCommerce Multilingual. To allow visitors to switch between currencies, your theme should include an optional currency switcher.

You can display a currency switcher, either using a PHP call or by inserting a shortcode.

<?php do_action(‘currency_switcher’, array(‘format’ => ‘%name (%symbol)’)); ?>


For a full tutorial, visit the tutorial on Multi-Currency for WooCommerce. Keep in mind that the currency switcher will only display if the site uses multiple currencies.

5. Become RTL Compatible

English – LTR

Hebrew – RTL

English LTRJPG

Hebrew RTL2JPG

WooCommerce themes must follow the RTL guidelines, just like WordPress themes. You should create an `rtl.css` file, with the CSS rules for RTL display.

Create a new `rtl.css` file and put it in your theme’s root directory. The ‘dir’ direction in CSS will do most of the work and you only need to patch a few places. For RTL languages, set the ‘direction’ attribute in CSS to ‘rtl’.  Additionally add the ‘unicode-bidi- attribute.

Good RTL display added to .body selector:





Now your theme will display in RTL.  To handle exceptions go to the RTL Themes Support Guidelines.

6. Manage Different Text Lengths in Different Languages

When you create your multilingual ready WooCommerce theme, understand that some texts will be longer in certain languages and shorter in others. Some language lengths, you cannot test, because your end-users will translate the content on their own.

For example, look at these two product blocks.

Default LanguageJPG

CSS Optimized for Short Text in English

Different LanguageJPG

Longer Spanish Text Doesn’t Fit the Space

The best way to achieve multiple length compatibility is to test your theme with texts that are x2 longer and ½ shorter. In most cases, this will cover any language that is translated. It is highly recommended to use fluid layouts to handle text of different sizes. A fluid layout will allow each element to resize and capture the area that is needed. Achieving a fluid layout takes time, but prevents visual glitches.

Style definitionJPG

Text Overflows Seamlessly onto the Next Line with No Display Glitch

WooCommerce `style.css` uses the designation `white-space: no-wrap`.  But in our example, in order to wrap the text properly you must use `white-space: normal;`.

7. Create a Language Configuration File

To make your theme fully WPML compatible, you should make it simple for others to run multilingual sites with the theme by creating a language configuration file.

WPML can read a configuration file that details what should be translated in the theme or plugin.  Create and name the file `wpml-config.xml`.  Save the file in the theme’s root directory.  Use the structure and section layout in the example in this sample file and edit it with your own custom content.

The content in the `wpml-config.xml` file must be wrapped in the following <wpml-config> opening and closing tags:



In the `wpml-config` file you set which features need to be translated by WPML, your custom post types, custom taxonomies, custom fields, and admin text (string coming from wp_options), and you can also set the way your theme’s language switcher will look just follow this short tutorial for full examples and details on structuring your language configuration file visit our Language Configuration File Tutorial.

Test Your Site

Now that you understand the need to make your theme or plugin multilingual and WooCommerce ready, and after following customary development practices as outlined above, it is time to test your theme or plugin.

Usually when you test, you would attempt to translate everything by putting in dummy translations in every area of your site.  But this would take a lot of time. Therefore, we have created a Testing tool for you: WPML Compatibility Test Tools Plugin.

This tool will inject dummy translations for your site, so you can switch languages,  and see what got translated, and what stayed in your original language. Our testing tool will save you several hours of testing and will help you see what areas you need to improve in your theme or plugin.

Install the Right Plugins for Multilingual WooCommerce

Your clients will need to have the following plugins for multilingual e-commerce sites with WooCommerce:

WPML comes with the core plugin and add-ons. This architecture allows different people to install different parts that they need. For multilingual WooCommerce sites, you will need the following WPML components:

  • WPML (Core)

  • WPML String Translation

  • WPML Translation Management

  • WPML Media Translation

GoGlobal Partnership

WPML is used on over 400,000 websites and any theme or plugin using the WordPress API can gain multilingual compatibility using WPML.  Why take the risk of not having a multilingual compatible and WooCommerce compatible theme or plugin?

WPML has a GoGlobal Program where we offer free WPML accounts to theme and plugin authors for compatibility testing.  We have numerous themes that are currently compatible including several WooThemes, all of Elegant Themes, Avada, and many themes on ThemeForest.

At WPML we take compatibility seriously with five expert developers and consultants that work full time on compatibility for all theme and plugin authors to gain multilingual compatibility. Sign up for free today to our WPML GoGlobal Program.

Distributing Multilingual-Ready Themes

When you distribute your theme, you want people to be able to use it for single-language and multilingual sites. The design tips that we gave throughout this article mostly rely on WordPress best practices, so your theme code barely includes any specific code for WPML.

Your clients will need to install WPML and its required components to run multilingual sites. As WPML is trademarked (and for other good reasons), you should not bundle WPML with your theme.

Instead, WPML offers a small purchase and auto-install component, which you are very welcome to use. This component lets your users buy WPML directly from inside the WordPress admin. It also credits you with affiliate commission for any such referral.

Integrating this tiny auto-install component in your theme is a great way to show people that your theme is truly compatible with WPML and can power multilingual sites. It also gives your users a streamlined process for buying and installing WPML, without having to use FTP to upload it to their servers.


Now that we have covered the top seven best practices of making your theme or plugin WooCommerce and Multilingual ready, we hope that you are ready to get started. Being multilingual-ready is easy and possible for every theme author.  

It is as easy as using WordPress best practices such as using `gettext` Functions and properly handling hardcoded WooCommerce Links, to finally adding a Language Configuration File to your theme.  Increase the versatility of your product on the market by focusing on the internationalization of your theme or plugin.

We're giving away $8,000 in our latest WPML and WooCommerce WordPress Themes Most Wanted event. You've got to be in it to win it!

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.