Skip Navigation
March 30, 2023

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 are looking for how to register hard-coded texts from themes and plugins for translation, please refer to this article on finding strings that don’t appear on the String Translation page.

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 makes it possible to translate these 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 a user creates new strings or updates existing strings, they need to be registered in WPML’s string table.

You can do this call with the wpml_register_single_string action hook:

do_action( 'wpml_register_single_string', string $context, string $name, string $value )
  • $context
    • (string) (Required) The name of the plugin or theme, 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 wpml_register_single_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 textarea.

Using the wpml_register_single_string action hook
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'];
     * register strings for translation
    do_action( 'wpml_register_single_string', 'Widgets', 'Custom Widget - input field', $instance['custom_input'] );
    do_action( 'wpml_register_single_string', 'Widgets', 'Custom Widget - textarea field', $instance['custom_textarea'] );
    return $instance;

The code above tells WPML that the user input texts for the input field and textarea need to be translated. The texts 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 certain text translated (for example, if a users deletes your theme or plugin from their site), data related to the string translation package can be removed using the wpml_delete_package action hook.

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, you can use the wpml_translate_single_string action hook.

How String Translation Works Internally in WPML

WPML includes a String translation interface, which lists all the strings and allows users of your theme or plugin to manage their translations.

The WPML String Translation interface

When a user click on the plus icon to translate a string, a multi-language translation panel opens up, allowing them to edit the translation per language. When they complete the translation, a pencil icon appears next to the string. If needed, the user can click this icon to edit the translation. When translations for all the languages are complete, this pencil icon appears under each language flag for the given string.

When a change is made to the original string, all of its translations are marked with a spinning arrows icon. This means that the translations need to be updated.

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 String Translation with plugins or themes, it is 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, as a theme or plugin developer, you should consider the case where WPML is activated long after the user begins using your theme or plugin. In such cases, the call to wpml_register_single_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  wpml_register_single_string exists and then call it to register all user input texts.

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 wpml_register_single_string.

WPML uses different posts, pages, tags and categories for different languages. This means that if a site includes these two pages – and, they would be different WordPress pages.

Any text that’s added per page would already appear in multiple languages, as your 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 as translated for different language home pages.