How to Make User Input Texts Translatable in WPML

Learn how to register user input texts from plugins and themes for translation. Once registered, you can translate them with String Translation. 

How to Register User Input Texts

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 – The name of the plugin or theme, in a human readable format.
• $name – The name of the string, which helps the translator understand what’s being translated.
• $value – The string that needs to be translated.

Consider this custom widget example, which includes a title, single line input field, and a textarea. To register these fields for translation when the widget options are saved or updated, we use the update function:

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'];
 
    //WPML
    /**
     * 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'] );
    //WPML
 
    return $instance;
}

In this example, we tell WPML it needs to translate the user input texts for the input and textarea field. These texts will be registered under the Widgets strings context with the name Custom Widget – input field and Custom Widget – textarea field respectively.

Once you register texts, you can use the wpml_translate_single_string action hook to display translations on the front end. 

How to Integrate String Translation with Plugins and Themes

When integrating String Translation with plugins or themes, it’s important to make sure the calls exist.

Implement Conditional Calls

Wrap your calls in if_function_exists() statements so that, if WPML is activated, it will be called, and if not, the normal operation is kept.

Handle Late Activation of WPML

As a theme or plugin developer, you should also consider the case where WPML is activated long after the user begins using your theme or plugin.

In these cases, strings won’t be translated because the call to wpml_register_single_string isn’t made when they’re created. To overcome this, you should register all user strings every time the admin screen for the plugin is loaded.

Although this adds a negligible execution time, it guarantees strings are always sent to translation and are up-to-date.

The code should first check if the wpml_register_single_string function exists. If it does, the function should be called to register all user input texts. Here’s how it works:

• If the function is called with blank or NULL values, WPML ignores these calls.
• If a string already exists and is unmodified, WPML ignores the call.
• The function only takes action if new or modified strings are registered.

The entire translation table is cached in memory, so repeatedly calling it takes very little processing power.

Additional Resources

To register hard-coded texts from themes and plugins for translation, see our article about finding strings that don’t appear on the String Translation page.

To register theme or plugin options for translation, see our guide about using the language configuration file.

To translate theme or plugin elements as a group, see our String Package Translation.