Translation for texts by other plugins and themes
WPML helps translate texts that are created by other plugins and by the theme. We’ll start with an example.
The popular Contact Form 7 plugin creates contact form that can be added to your site. You can use the default fields (like name and email) and add your own. When visitors see the site in different languages, the contact form needs to appear in those languages too.
If all the texts are hard coded into the plugin they can be localized using gettext (the plugin’s .mo file). However, how do ou handle texts that the user enters? If the user adds a new field to the contact form, like ‘Profession’, it cannot be translated using the theme’s .mo file. The user needs to be able to provide translation for this text.
String translation in WPML
WPML includes a mechanism for translating this kind of texts. By default, it helps users translate the blog’s title, tagline, text widgets and other texts that WordPress generates. Other plugins and the theme can also use this mechanism to provide translation for texts that they need to display.
1. Register the strings that need translation
When the user creates new strings or updates existing strings, these need to be registered in WPML’s string table. To do this call:
icl_register_string($context, $name, $value)
- $context – the name of the plugin, in a human readable format
- $name – the name of the string which helps the user (or translator) understand what’s being translated.
- $value – the string that needs to be translated.
In our contact form example, when we add a new field (called ‘Profession’), we would then call:
icl_register_string('Contact Form 7', 'Input field label', 'Profession')
This would tell WPML that the string ‘Profession’ needs to be translated. When users go to translate it, they would see that it’s part of the ‘Contact Form 7′ plugin and that it’s an ‘Input field label’.
If the plugin no longer needs to have a certain text translated (for example, if the user deleted that field from the contact form), the string can be removed from the translation table using this call:
2. Using the translation when displaying
When the contact form plugin displays, it needs to get the translations and use them. To do this, it uses the icl_t function:
icl_t($context, $name, $value)
WPML looks for a string with matching $context and $name. If it finds it, it looks for translation in the current language (the language in which the site is displayed). If translation exists, it will return it. Otherwise, it will return the original string.
The $value argument is supplied to icl_t() call so that in case WPML wasn’t active when the string was created, and it’s not registered, the normal string value is still returned.
WPML includes a string translation interface, which lists the strings and allows managing their translation.
When users click on translations for a string, a multi-language translation panel opens up, allowing to edit the translation per language. Each translation includes a complete flag. If translations to all the languages are complete, the string itself is also marked complete.
When the string changes, all its translations are marked as incomplete, so that users know that the translations need to be revised.
All string editing is done within the same WordPress admin interface and doesn’t require any external calls to external services.
When integrating the string translation in plugins, or in themes, it’s important to make sure that the calls exist.
The calls to WPML’s string translation functions should be wrapped in if_function_exists() statements. This way, if WPML is activate, it will be called. Otherwise, the normal operation is kept.
Additionally, plugin developers should consider the case where WPML is activated long after the user begins using their plugin. In this case, the call to icl_register_string isn’t made when new strings are created and they will never be translated. To overcome this, it’s a good idea to register all the user strings every time the admin screen for the plugin is loaded.
This will add a negligible execution time, but would guarantee that all strings are always sent to translation and are up-to-date. The code can test once to see that the icl_register_string exists and then call it to register all the strings users can enter.
If this function is called with blank or NULL values, it’s ignored by WPML. If the string already exists and is unmodified, the call is ignored too. It only has an effect if new or modified strings are registered.
The entire translation table is cached in memory so repeatedly calling it takes very little processing power.
What needs to be sent to translation
Let’s start with what doesn’t need to be registered using icl_register().
WPML uses different posts, pages, tags and categories for different languages. This means that if a site includes these two pages – example.com/about/ and example.com/es/sobre/ they would be different WordPress pages.
Any text that’s added per page would already appear in multiple languages, as the user would simply enter the correct text for the language in which that page is written.
What needs to be translated using WPML’s string translation are texts that don’t belong to any post, page, tag or category. For example, SEO plugins allow entering texts for the home page title, keywords and description. This text does need to be translated using WPML’s string translation. This way, it will display translated for different language home pages.