Skip Navigation
March 23, 2023

WPML Sticky Links prevents links between pages and posts from ever breaking, even if pages move and get renamed.

WordPress makes it all too easy to change page addresses, causing all incoming links to break (404 error). Here are a few actions that may result in a 404 error:

  • Changing the page’s parent
  • Changing the slug
  • Changing the site’s permalink structure

WPML prevents changes in URLs from breaking incoming links. When you create a link, WPML automatically makes it sticky. Instead of storing the URL of that page (at the time the link was created), it stores the page number. This can never change, no matter what you do.

Then, when the page is displayed, WPML inserts the permalink of the page you are linking to. Whenever the URL changes all pages linking to it update immediately and will link to the correct address.

The following screenshots show how internal links look like in the database, once Sticky Links are enabled.

Links turned Sticky by WPML viewed within Block editor
Links turned Sticky by WPML viewed within Block editor
Links turned Sticky by WPML viewed within Classic editor
Links turned Sticky by WPML viewed within Classic editor

Your users will never see these “strange” links. Instead, WPML will replace them with the current permalinks when displaying the pages.

Once you enable the Sticky Links module, you can control what strings it handles. To do this, go to the WPML  → Sticky links page.

Sticky Links before processing
Sticky Links before processing

By default, WPML will turn all links in the post body to sticky links. You can also turn links in widgets and strings into sticky links.

WPML will let you batch replace all regular links to sticky links. It will also report any existing broken links and help fix them.

If you have enabled Sticky Links after creating some content, links in that existing content are not immediately turned into sticky ones.

The Sticky Links admin screen tells you how much content may include normal (not sticky) links. WPML can scan that content and convert all links to sticky links. Click on the Scan button to do that.

You can always return your links to regular (not sticky) permalinks by clicking on Revert sticky URLs to permalinks.

Linking to pages in a different language

Sometimes, you might want to insert a link to a page that is in another language. Since Sticky Links adjusts the links automatically, it might prevent you from doing this and adjust the link to point to the same language instead.

To be able to add links to pages in other languages, you need to add the following filter to your theme’s functions.php file.

Allow links to pages in other languages
add_filter( 'wpml_sl_blacklist_requests', 'wpml_sl_blacklist_requests', 10, 2 );

function wpml_sl_blacklist_requests( $blacklist, $sitepress ) {
    $blacklist[] = 'documentation';
    return $blacklist;

In the above code, use the $blacklist array to specify all the URL slugs for the pages in the original languages that you want to link to.

In our example, we want to link to English version of “Documentation” (slug “documentation”) and “Page Builders” (slug “page-builders”) pages, so we use the following two lines:

Example of specifying the list of URLs to allow linking to
$blacklist[] = 'documentation';

$blacklist[] = 'page-builders';

By default, the Sticky Links plugin does not search for links generated by shortcodes.

If you have a shortcode on your page that generates a link like “?page_id=XX“, it will be displayed to your users without being converted to a permalink.

To handle these shortcode content with Sticky Links, add this snippet to your functions.php file:

Handle links inside shortcode content
if ( class_exists( 'WPML_Sticky_Links' ) ) {
	global $WPML_Sticky_Links;
	add_filter( 'do_shortcode_tag', [ $WPML_Sticky_Links, 'show_permalinks' ], 0 );