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 – Sydney theme
- Translating the header
- Translating menus
- Translating Sydney theme’s Services and other custom post types
- Translating theme or plugin’s custom 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 compatibility
- Tips and debugging
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 – Sydney theme
Let’s look at this example of a website created with Sydney, from aThemes:
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 the WPML -> String Translation page, 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 are 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 the Appearance -> Menus page, you will see WPML’s menu translation controls. Learn more about translating menus to see how this works.
5. Translating Sydney theme’s Services and other custom post types
The example theme that we are looking at uses a custom post type “Services”. This means that it is easy to translate it using WPML, with little configuration. It also applies to “Testimonials”, “Clients”, and “Projects” post types.
We need to tell WPML that the “Services” 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 services (with the same titles) for all languages, you’d keep the “Services” post type untranslatable. We want to translate the “Services”, so we can show our offer in different languages.
In WPML’s user interface, edit a service and scroll all the way down. You will see a section called Multilingual Content Setup‘.
Click on the checkbox to make the custom post types translatable and click Apply.
Can you see that it is grayed-out in our screenshot? It’s not an accident. This is because we provided a Language Configuration File with the theme or plugin.
The language configuration file tells WPML everything it needs to know about your theme (or a plugin). This includes which post types and taxonomy need to be translatable, which custom fields to translate or sync and which strings to translate.
6. Translating theme or plugin’s custom elements
Many themes and plugins have unique features which store texts in the wp_options table. The slide captions, by Sydney 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 for 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
Just like many other themes, this one uses widgets to store the footer texts.
WPML allows users to translate the titles and content of your widgets via the String Translation screen.
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 to be 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-coded texts will appear in the correct language in the site. You should do it for both, the theme (or plugin) texts that appear in the WordPress admin area, as well as the texts displayed on the front-end.
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 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 debugging
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 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.