Every WordPress theme and plugin can become compatible with WPML. Follow this tutorial to learn how to test WPML compatibility and make the required changes to make your code fully multilingual-ready.
This tutorial explains how you can make different parts of your theme multilingual-ready. It takes about 1-2 hours to go through all of this any apply to your theme.
- Installing WPML Components
- Case Study – WooThemes Resort Theme
- Translating the Header
- Translating Menus
- Translating the WooThemes Slider
- Translating Custom Theme or Plugin Elements
- Translating the Post Body
- Translating Widgets
- Translating the Footer
- Creating a Language Configuration File for Your Theme
- GetText Support for Hard-Coded Strings
- WooCommerce section compatibility
- Tips and Debug Ideas
1. Installing WPML Components
WPML includes several components. Some are required for your theme-compatibility work and some are intended for site admins, who will later manage the site’s content.
You should activate the essential WPML components, which will allow you to fully translate your theme, including WPML core, WPML String Translation and WPML Translation Management.
To get them, go to your WPML account and click on Downloads.
Of course, you are welcome to learn about the other components in WPML core and addons.
2. Case Study – WooThemes Resort Theme
Let’s look at this example of a website created with Resort, from WooThemes:
As we go through the different elements in this site, we’ll learn how to translate rich themes or plugins with WPML!
3. Translating the Header
The theme’s or plugin’s header comes from the WordPress general settings:
Since it’s not part of any post, 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.
You don’t need to do anything in the theme or plugin to make this happen. WPML handles it automatically. We showed how to translate the site name, because we’re going to use WPML’s String Translation for many other things in your theme or plugin.
4. Translating Menus
WPML translates WordPress menus without you needing to do anything. As long as your theme uses the standard WordPress menu system, WPML will translate the 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.
5. Translating the WooThemes Slider (using Custom Post Types)
The example theme that we are looking at uses a CPT, called ‘slide’ for the slider. This means that it’s easy to translate with WPML, with little configuration.
We need to tell WPML that the ‘slide’ custom post type is multilingual. This means that WPML offers users to translate it.
You might wonder why WPML allows some content to be multilingual and some without language information, on the same site. Good question!
When content is multilingual, WPML filters it and will only return results in the current language. In some cases, you want to use the exact same content for all languages. For instance, if you want to show the exact same slides (with the same titles) for all languages, you’d keep the slide CPTs untranslatable. We want to translate the slides, so that slides can have different titles per language.
In WPML’s GUI, edit a slide and scroll all the way down. You will see a section called ‘Multilingual Content Setup‘.
Click on the checkbox to make the CPT translatable and Apply.
Can you see that it’s grayed out in our screenshot? It’s not an accident. This is because we’ve provided a Language Configuration File with the theme or plugin.
The language configuration file tells WPML everything it needs about your theme. This includes which CPTs and taxonomy needs to be translatable, what custom fields to translate or sync and what strings to translate.
6. Translating 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 API functions to do this.
7. 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. For example, the highlighted texts in this screenshot should be wrapped in gettext calls.
If you’re new to using GetText, learn more about it in our theme texts translation FAQ.
8. Translating Widgets
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. Have a look at the “Translating Widgets” article for additional information.
9. Translating the Footer
This theme has 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.
10. Creating a Language Configuration File for Your Theme
When you are done and your theme is fully WPML-compatible, you probably want to make it as easy as possible for others to run multilingual sites with the theme.
Create a language configuration file for your theme and save it in the theme’s root directory. The file tells WPML which custom post types, taxonomy, fields and options are translatable.
This tiny XML file will save hours for your clients, allowing them to run multilingual sites without effort. Your clients will get everything working, without the need to configure what to translate. This will also help you save on support work.
11. GetText Support for Hard-Coded Strings
Although this is not strictly related to WPML, you should remember to wrap all the strings in your theme in GetText calls. This means that hard-code texts will appear in the correct language in the site. You should do it for both texts in the theme admin and texts that display on front-end pages.
All WordPress themes and plugins, whether they are multilingual-ready or not, should use GetText to translate hard coded strings. The WordPress default themes use GetText very accurately and are a great reference, if you are just getting started with it.
Wrapping texts in GetText calls is a big subject by itself. If you are not familiar with it, or need help debugging localization for your code, have a look at these:
You should know that WPML integrates fully with GetText. Once you have wrapped hard-coded strings in GetText calls, you will be able to translate them directly from the WordPress admin using WPML’s String Translation screen. WPML can also export and import .po files for you, letting you translate your theme’s strings all from within WordPress.
12. WooCommerce Compatibility
Themes that include a WooCommerce section may need to follow a few other suggestions. Mainly, you should use get_options WooCommerce to get the IDs of WooCommerce pages. Have a look at our guide on making WooCommerce themes multilingual and multi-currency ready.
13. Tips and Debug Ideas
If you are already familiar with WPML basics and are working on compatibility with your theme or plugin, have a look at the debugging theme compatibility guide. You will find tips and ideas on how to make your theme easily compatible with WPML.
If you need our help, just give us a shout. Head over to our technical support forum, explain what’s wrong and we’ll help you quickly.