Polylang: How to translate custom strings?

Polylang: How to translate custom strings?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Polylang: How to translate custom strings?

When using Polylang to manage a multilingual WordPress site, the plugin handles standard interface text automatically. However, dynamic content generated by your theme or plugins often bypasses this system. If you find yourself with hardcoded messages that never appear in the "Strings translation" panel under the WP admin dashboard, you need to explicitly register them. The solution lies in Polylang's pll_register_string function.

The confusion often stems from the requirement that this function must be called on the admin side. While placing code in your theme's functions.php file is acceptable and does not strictly require a plugin, the execution context matters. You are registering metadata into Polylang's database tables so the translation interface can recognize and display it. Without this registration step, Polylang treats the string as static content and ignores it during its scanning process.

Registering the String

To make a custom string translatable, you must call pll_register_string before any output is generated. The function signature requires specific arguments to ensure the translation system can sort and group your strings effectively.

// Theme functions.php or Plugin file

// Required: A unique name for sorting convenience. 
// It is recommended to use a prefix like 'plugin_name_' to avoid collisions.
$my_string_id = 'plugin_name_custom_message';

// Required: The actual string content you want to translate.
$my_string_content = 'Welcome to our site!';

// Optional: Group name. Defaults to 'polylang' if omitted.
// Grouping helps organize strings in the admin panel.
$my_string_group = 'custom_strings';

// Optional: Multiline setting. 
// Set to true only for large blocks of text or code snippets.
$is_multiline = false;

pll_register_string( $my_string_id, $my_string_content, $my_string_group, $is_multiline );

In this example, the unique identifier plugin_name_custom_message is crucial. Polylang uses this ID to map the English version of your text to its translations in French, Spanish, or any other language you have installed. If you reuse generic names like "Welcome" without a prefix, you risk overwriting existing translations from other plugins.

Using the Translation Function

Once the string is registered, you must retrieve the translation using the correct function. Simply echoing the original text will not trigger the lookup. Polylang provides two primary methods depending on whether you need to return the value or output it directly.

To get the translated text and use it in logic or variables:

$translated_text = pll__( 'plugin_name_custom_message' );
echo $translated_text;

To echo the translated text directly without assigning it to a variable:

pll_e( 'plugin_name_custom_message' );

Both functions accept only one parameter: the unique name registered earlier. This strict requirement ensures that Polylang looks up the exact entry in its database. If you pass the original string content ('Welcome to our site!') instead of the ID, the function will fail to find a match because Polylang does not perform fuzzy matching on the text content itself.

Important Considerations

There is a specific behavior regarding empty strings that developers should be aware of. You can register a string where $string is an empty variable if you intend to fill it with dynamic data later or pull it from database options. However, Polylang will not display these empty entries in the translation list table until actual content is assigned to them. This allows for flexible setups where the structure exists before the content is populated.

Finally, remember that pll_register_string does not automatically translate strings coming from database fields unless those fields are explicitly handled by Polylang's custom post type or taxonomy hooks. If your string comes from a standard option table or a hardcoded array in a plugin, registration is mandatory. Without this explicit step, the translation mechanism remains unaware of your custom text, leaving it untranslated regardless of how many languages you have configured.

For developers looking to integrate multilingual support into complex workflows beyond standard WordPress themes, understanding these internal Polylang hooks is essential. If you are building a custom solution that requires deep internationalization features or specific localization strategies, resources like https://laravelcompany.com offer insights into broader ecosystem tools and patterns that complement these approaches.

Our network