BugWP logo BugWP
Back to Community
Home / Community / Plugin → Polylang

Understanding and Customizing Polylang Hreflang Tags for Better SEO

22 threads Sep 16, 2025 Plugin → Polylang

Content

If you're using the Polylang plugin for a multilingual WordPress site, you've likely encountered hreflang tags. These HTML attributes in your page's <head> section are crucial for SEO, as they tell search engines like Google about the language and regional targeting of your content. A common point of confusion among users is how to control and customize these automatically generated tags.

What Are Hreflang Tags and Why Are They Important?

Polylang automatically generates <link rel="alternate" hreflang="xx" /> tags for all translated versions of a post or page. This helps search engines understand the relationship between different language versions, preventing issues with duplicate content and ensuring users are served the correct language version in search results.

Common Hreflang Challenges and Solutions

Based on community discussions, here are the most frequent issues and how to address them.

1. Adding an x-default Hreflang Tag

An x-default hreflang tag specifies a default page for users whose language doesn't match any of the provided alternatives. While Polylang adds this automatically in some cases (like when the homepage auto-redirects), you may need to add it manually. This can be done by adding a custom function to your theme's functions.php file.

function polylang_add_xdefault( $hreflangs ) {
    $default = array(
        'x-default' => reset( $hreflangs ) // Uses the first language's URL
    );
    return $hreflangs + $default; // Appends x-default to the end of the array
}
add_filter( 'pll_rel_hreflang_attributes', 'polylang_add_xdefault', 10, 1 );

To place the x-default tag at the beginning of the list instead, change the + operator to merge the arrays to $default + $hreflangs.

2. Changing Language Codes to Include Regions

By default, Polylang may use a simple language code (e.g., en). For better regional targeting, you might want to use a language-region code (e.g., en-GB or ru-UA). You can modify these codes using a filter.

add_filter( 'pll_rel_hreflang_attributes', function( $hreflangs ) {
    // Replace 'ru' with 'ru-UA'
    if (isset($hreflangs['ru'])) {
        $hreflangs['ru-UA'] = $hreflangs['ru'];
        unset( $hreflangs['ru'] );
    }
    // Replace 'en' with 'en-GB'
    if (isset($hreflangs['en'])) {
        $hreflangs['en-GB'] = $hreflangs['en'];
        unset( $hreflangs['en'] );
    }
    return $hreflangs;
} );

3. Removing the Self-Referencing Hreflang Tag

Some users notice a tag pointing to the page itself (e.g., hreflang="fr" on a French page) and wish to remove it. It's important to note that Google recommends including this self-referencing tag. However, if you choose to remove it, you can filter the array to unset the entry for the current language.

add_filter( 'pll_rel_hreflang_attributes', function( $hreflangs ) {
    // Get the current language
    $current_lang = pll_current_language('slug');
    // Remove the hreflang tag for the current language
    if (isset($hreflangs[$current_lang])) {
        unset( $hreflangs[$current_lang] );
    }
    return $hreflangs;
} );

Important Considerations

  • Cache: After adding these code snippets to your functions.php file, clear your site's cache (including any caching plugins) to see the changes.
  • Child Theme: Always use a child theme when modifying theme files to prevent your changes from being overwritten during updates.
  • Testing: Use tools like Google's Search Console or third-party hreflang validators to check your implementation after making changes.

By understanding how Polylang's pll_rel_hreflang_attributes filter works, you can gain fine-grained control over your multilingual SEO signals. For more detailed documentation, you can refer to the official Polylang filter reference.

Related Support Threads Support