WPML String Translation allows you to translate user-generated content in addition to titles, taglines, and widgets. This article walks you through registering these strings to WPML’s string table.
If you want to learn how to register theme or plugin options for translation you will want to use a language configuration file.
If your theme or plugin is creating elements that are preferable to be translated as a group (as in forms, for example), have a look at String Package Translation.
The following article is for all other user input text stored in the database by themes and plugins.
We’ll start with an example.
You have created a custom widget with a title input field and some other options. You can register the widget title for translation using ‘apply_filters’ but you also want to register the input text you can save in all other option fields.
If all the texts are hard coded into the plugin/widget they can be localized using gettext (the plugin’s .mo file). However, how do you handle texts that the user enters?
String translation in WPML
WPML includes a String Translation module, that allows 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 themes 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 ( string $context, string $name, string $value );
- $context
- (string) (Required) The name of the plugin, in a human readable format
- $name
- (string) (Required) The name of the string which helps the translator understand what’s being translated.
- $value
- (string) (Required) The string that needs to be translated.
In our custom widget example, we need to call ‘icl_register_string()‘ when the widget options are saved or updated. This is done inside the ‘update‘ function of our custom widget.
This is an example of what it will look like. Our custom widget has a title, a single line input field and a text area.
function update($new_instance, $old_instance){
$instance = $old_instance;
$instance['title'] = strip_tags($new_instance['title']);
$instance['custom_input'] = strip_tags($new_instance['custom_input']);
$instance['custom_textarea'] = $new_instance['custom_textarea'];
//WMPL
/**
* register strings for translation
*/
if (function_exists ( 'icl_register_string' )){
icl_register_string('Widgets', 'Custom Widget - input field', $instance['custom_input']);
icl_register_string('Widgets', 'Custom Widget - textarea field', $instance['custom_textarea']);
}
//\WMPL
return $instance;
}
This tells WPML that the user input text for the input field and textarea need to be translated. They will be registered under the “Widgets” strings context with the name “Custom Widget – input field” and “Custom Widget – textarea field” respectively.
Useful to know: If the plugin no longer needs to have a certain text translated (for example, if the user deleted the plugin), the string can be removed from the translation table using this call:
icl_unregister_string ( string $context, string $name );
2. Using the translation when displaying widgets
When the custom widget is displayed on the front end, it needs to get the translations and use them.
To do this, we used to use the icl_translate function.
The way string translation works internally in WPML
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 them to edit the translation per language. Each translation includes a complete flag. If translations for 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.
How to integrate WPML’s string translation with plugins and themes
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 activated, 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 will 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 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 again ignored. 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.