Fixing Hreflang in WordPress

Finding what writes your tags

Open a translated post, view the source and search for hreflang. Note how many sets of tags there are and where in the head they appear. Then list the active plugins. With WP-CLI:

wp plugin list --status=active --fields=name,version

Look for these families, any of which may output hreflang:

• Translation plugins such as WPML, Polylang and TranslatePress, which generate tags for the translations they manage.
• Multisite linking plugins such as MultilingualPress, which connect separate sites in a network and generate tags between them.
• Dedicated hreflang plugins, installed to fill a gap at some point and then forgotten.
• Themes and child themes, where a developer may have hard-coded tags in header.php or a function hooked to wp_head.
• SEO plugins such as Yoast SEO and Rank Math, which do not usually write hreflang themselves but do control canonicals and sitemaps, both of which interact with it.

To see which hooked function prints the tags, search the theme and plugin folders:

grep -rl "hreflang" wp-content/themes wp-content/plugins wp-content/mu-plugins

If more than one plugin appears in the results, deactivate them one at a time on a staging copy and reload the page source. The set of tags that disappears tells you which plugin wrote it.

How the main translation plugins handle hreflang

Plugin menus and option names change between versions, so use the table as a guide to where to look rather than exact labels.

WPML: codes, display setting and fallbacks

WPML lets you set the hreflang value for each language when you edit the language list, so an incorrect value can usually be fixed there without code. Check that British English is en-GB rather than a bare en if you also run a US version, and that no value uses an underscore. In WPML's SEO options, confirm that alternative languages are being shown in the head, and that the position setting places the tags where you expect.

Watch the translation mode for each post type. WPML can be told to show the default language when a translation is missing. That is convenient for visitors, but it can mean a page at a translated address is in the original language, and if hreflang is also printed for it, the tag claims a translation that does not exist. For content you want found in each language, translate it; for post types that are not translated, do not let them join clusters.

If you need to change the output in code, WPML passes the list of tags through a filter keyed by hreflang value. For example, to drop a language that is still being translated:

add_filter( 'wpml_hreflangs', function ( $hreflangs ) {
    unset( $hreflangs['nl'] ); // Dutch not ready yet
    return $hreflangs;
} );

Remove a language this way only if you remove it from every page, so the cluster stays symmetrical.

Polylang: locales, filters and imports

Polylang derives hreflang from the locale you choose for each language, such as en_GB, and converts it to the hyphen format. Depending on your set of languages, it may output only the language part, for example en, or the language and region. If you need a specific value, the pll_rel_hreflang_attributes filter receives the list keyed by code and lets you change it:

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

Put code like this in a small custom plugin or a child theme's functions.php, not in the parent theme, where an update would overwrite it.

Polylang only prints tags for translations that are linked together. After bulk imports, migrations or copying posts between sites, translations are often published but not linked, so each post prints only itself, or links exist on one side only. Open the post list, filter by language and look at the translation columns: a missing link icon marks a post that is not connected. Re-link them, one by one or with the import tool you used, and recrawl.

If the language switcher settings are set to detect the browser language on the home page, crawlers can be sent to a different language from the one they asked for. Check the behaviour with a request that has no cookies and no language header.

TranslatePress and multisite networks

TranslatePress

TranslatePress serves each language from a subfolder based on the slug chosen for it, and prints tags for each published language of a page. Two faults come up often. First, a custom URL slug such as /uk/ is only an address; check that the language behind it is set up as English (United Kingdom) so the tag reads en-GB, not something derived from the slug. Second, automatic translation may have been switched on and later limited, leaving some pages partly translated while tags still claim the language. Review the plugin's advanced settings for hreflang options and decide which pages are complete enough to offer.

Multisite networks

Running one site per language in a multisite network keeps languages separate, but WordPress does not know that post 12 on the English site is post 40 on the French site. A linking plugin, such as MultilingualPress, stores those connections and prints the tags. Errors arise when posts are never connected, when a site's permalink structure changes so stored addresses redirect, or when one site in the network is on a different domain whose protocol or host differs from what the plugin expects. Check connections for your most important content first, then crawl each site.

Clashes with SEO plugins, caches and redirects

• Canonicals. Each translation must be its own canonical. If an SEO plugin, a theme or a custom field sets every language's canonical to the original post, the translations are declared duplicates and the cluster fails. Yoast SEO and Rank Math are designed to work with the major translation plugins, but custom canonical fields filled in during a migration can override that.
• Sitemaps. If your translation plugin outputs hreflang in the HTML and a separate tool adds it to the sitemap, the two can disagree. Keep one.
• Page caching. A cache must store each language separately. If language is chosen by cookie rather than by address, a cached page can serve French text on the English address with English tags. Addresses that carry the language, such as a subfolder, avoid this; if you rely on cookies, configure the cache plugin to vary by that cookie.
• Language redirects. Plugins and hosting rules that redirect by browser language can stop crawlers from reaching some versions. Prefer a suggestion over a redirect.
• Trailing slashes and permalinks. Changing permalink settings on one language, or on one site in a network, turns stored addresses into redirects.

The fix, step by step

Keeping WordPress hreflang healthy

• One plugin owns translations and hreflang; nothing else adds tags.
• Custom changes live in a small plugin or child theme, never in the parent theme or a plugin's own files.
• Imports are followed by a check for unlinked translations.
• Language is always in the address, so caches and crawlers see one language per address.
• Plugin and theme updates are tested on staging with the Hreflang Checker before they reach the live site.

For cluster basics, see the Hreflang Guide. If you also run a Shopify store for some markets, the Shopify guide covers linking the two.