Hreflang Implementation: A Practical Guide for International Websites

Hreflang is an HTML attribute that tells search engines which language and region each version of a page is written for, so that a searcher in Germany sees the German page and a buyer in the UK sees the UK English page. Hreflang implementation is the work of planning, adding and maintaining those annotations across every version of an international website. It sits within the technical side of SEO for B2B organisations and when it goes wrong the result is usually the wrong page appearing in the wrong market rather than an obvious error.

This guide is written for marketing and IT teams running a website with more than one language or regional version. It follows the rules in Google’s own documentation and covers language codes, the three implementation methods, a correct code example, canonical tags, WordPress and how to check the set-up once it is live. A sound hreflang implementation follows these steps.

1. Decide which markets and languages you serve and settle the URL structure.
2. Assign a valid language code, with an optional region code, to every version.
3. Choose one method, either HTML link elements, HTTP headers or an XML sitemap.
4. List every version on every page in the set, including the page itself.
5. Add an x-default fallback for visitors who match none of your versions.
6. Align canonical tags so each version points to itself.
7. Crawl and test the annotations, then check them after every release.

The sections below explain each step in more detail. The order matters, because most hreflang problems trace back to decisions made before a single tag was written.

What Hreflang Does and When You Need It

Hreflang tells Google that a group of pages are localised variations of the same content, so it can point each searcher to the most appropriate one. Google’s guidance on localised versions of a page gives three situations where this is recommended. These are a page where only the template such as navigation and footer is translated, content in a single language with small regional variations (for example English for the US, the UK and Ireland) and content fully translated into several languages.

The second situation is the one UK businesses most often overlook. A company with near-identical UK and US product pages, differing only in prices, spelling and contact details, has a duplication problem as much as a targeting one. Hreflang helps Google understand that the pages are deliberate regional versions rather than copies, so the US page is not shown to UK buyers looking for sterling pricing.

It is worth being clear about what hreflang does not do. Google states on the same page that it does not use hreflang or the HTML lang attribute to detect the language of a page and relies on its own algorithms instead. Hreflang is a signal about which version to show to whom, so it will not fix thin translations or make a weak page rank in a new market.

Plan Your International URL Structure First

Your URL structure should be settled before any tags are written, because every annotation refers to fully qualified URLs that need to stay stable. Google’s documentation on managing multi-regional and multilingual sites sets out the options as country-code domains such as example.de, subdomains such as de.example.com and subdirectories such as example.com/de/. It does not recommend URL parameters such as ?loc=de.

Each option has trade-offs. Country-code domains give the clearest geotargeting signal but cost more to run, subdirectories keep everything on one host with low maintenance and subdomains allow different server locations while keeping separation simple. Our guide to international SEO specialists covers that decision and the market research that should come before it.

Google also recommends separate URLs for each language rather than switching content with cookies or browser settings. Its crawler usually originates from the US and sends requests without an Accept-Language header, so content that changes dynamically may never be crawled in every version. Planning the full list of markets, including those you expect to add later, avoids a costly restructure when the next region launches.

Choosing the Right Language and Region Codes

Every hreflang value starts with a language code in ISO 639-1 format, optionally followed by a region code in ISO 3166-1 Alpha 2 format. The Library of Congress publishes the ISO 639 language code list and the two-letter codes in that list are the ones to use. The W3C article on choosing language tags explains the wider convention of lowercase language subtags and uppercase region subtags.

The most common error on UK websites is using en-UK. The ISO code for the United Kingdom is GB and Google states that reserved codes such as UK, EU and UN have no effect in hreflang annotations, so en-UK quietly fails. The table below shows how Google treats some typical values.

Values are case-insensitive in Google, though writing regions in uppercase follows the ISO convention and makes audits easier to read. Use a language-only code such as de when a single version serves a language across every country and add a region only when the content differs by country.

Three Ways to Implement Hreflang

Google accepts hreflang in HTML link elements, in HTTP response headers or in an XML sitemap and it treats the three methods as equivalent. Using more than one at the same time brings no benefit in search and makes the set-up harder to maintain, so the sensible choice is the one your platform and team can keep accurate.

HTML link elements in the head of each page suit most websites with a manageable number of versions, because the annotations are visible in the source and easy to check. HTTP headers exist mainly for non-HTML files such as PDFs, which have no head section to hold the tags. XML sitemaps suit large websites with many versions of each page, since the annotations live in one place and do not add weight to every page. If your current sitemap set-up is unfamiliar, our explainer on what a sitemap is covers the basics.

Whichever method you pick, the content of the annotations is identical. Every version of a page carries the same complete set of entries, one for each version including itself and every URL is written in full with the protocol included.

A Correct Hreflang Code Example

The example below is for a UK business with UK English, US English and German versions of a page, plus a country selector at the root of the domain. The same four link elements go in the head of all three language pages.

<head>
  <link rel="alternate" hreflang="en-GB" href="https://www.example.com/uk/services/" />
  <link rel="alternate" hreflang="en-US" href="https://www.example.com/us/services/" />
  <link rel="alternate" hreflang="de" href="https://www.example.com/de/services/" />
  <link rel="alternate" hreflang="x-default" href="https://www.example.com/" />
</head>

Each page lists itself as well as its two alternates, which is what Google means by a self-referencing annotation. The German version uses de on its own because it serves German speakers in any country, while the English versions carry regions because the prices and spelling differ between the UK and the US.

The sitemap method expresses the same relationship with xhtml:link elements under each URL entry. For a simpler website with only UK English and German versions, the entries would look like this.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://www.example.com/uk/services/</loc>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://www.example.com/uk/services/" />
    <xhtml:link rel="alternate" hreflang="de" href="https://www.example.com/de/services/" />
  </url>
  <url>
    <loc>https://www.example.com/de/services/</loc>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://www.example.com/uk/services/" />
    <xhtml:link rel="alternate" hreflang="de" href="https://www.example.com/de/services/" />
  </url>
</urlset>

Note the xhtml namespace declared on the urlset element, which Google requires. Each URL gets its own entry and each entry repeats the full set of alternates including itself.

Return Links and the x-default Value

Hreflang only works when pages point to each other, so if page A lists page B but page B does not list page A, Google may ignore the annotations. Google designed it this way so that another website cannot claim to be an alternate version of your pages. Missing return links are the first thing to check whenever hreflang appears to have no effect.

On larger websites a complete set of links between every language can be hard to maintain. Google says it will still process the pairs that do point to each other and advises prioritising return links between new language versions and the original, dominant version of the website.

The x-default value names the page to show when a visitor’s language settings match none of your versions. Google introduced it in its announcement of x-default hreflang for language selector and auto-redirecting home pages and those pages remain its main use. If you have no selector page, pointing x-default at your main English version is a reasonable fallback.

Hreflang, Canonical Tags and Redirects

Canonical tags and hreflang need to agree, which means each language version should carry a canonical pointing to itself. Google’s guidance on specifying a canonical URL says that when hreflang is in use, the canonical should be a page in the same language. Pointing every regional page at the UK version tells Google the others are duplicates, which undermines the hreflang set entirely.

Every URL in a hreflang set should also return a 200 status and be indexable. Annotations that point to redirected, broken or noindexed pages are a frequent finding in technical audits and they usually appear after a migration or a URL change in one market that was never reflected elsewhere. These issues sit alongside the others in our list of common technical SEO issues.

Automatic redirects based on IP address or browser language cause a related problem. Google advises against redirecting users to a language version based on assumptions about their language, because it can stop both people and crawlers reaching every version. A visible language or country selector is the safer approach and it pairs naturally with an x-default page.

Most of these errors are simple to fix once found. The difficulty is finding them, because a broken hreflang set rarely produces a visible error on the page itself.

Hreflang on WordPress Websites

On WordPress, hreflang is usually handled by the multilingual plugin rather than written by hand. WPML, for example, states in its documentation on adding hreflang to WordPress that it inserts hreflang tags automatically and updates them as content changes. That removes much of the manual effort, but it does not remove the need to check the output.

Plugins can only annotate what they know about. Pages that were never linked as translations, custom post types left out of the translation settings and a theme or SEO plugin adding a second set of tags are all common causes of incomplete or conflicting annotations. Checking the rendered head of a sample of pages in each language, rather than the plugin settings, shows what search engines receive.

Priority Pixels specialises in WordPress for SEO because it gives the deepest technical control over schema, internal linking and content structure. Where international versions are part of a build, our WordPress development team and SEO team plan the URL structure and hreflang output together, so the annotations are correct from launch rather than fixed afterwards.

Testing and Monitoring Hreflang After Launch

Testing hreflang means checking that every page in each set lists all of its versions, uses valid codes, receives return links and points only to live, indexable URLs. A crawler that reports hreflang relationships is the most efficient way to do this across a large website, backed by spot checks of the rendered HTML on key templates.

Search Console no longer reports hreflang errors directly. Google deprecated the International Targeting report in 2022 and Search Engine Roundtable reported that it would stop working after 22 September 2022, while Google confirmed it continues to support hreflang. In practice this makes regular crawls more important, because nothing in Search Console will flag a broken set on your behalf.

Performance data shows whether the annotations are doing their job. Rising impressions for the US page from UK searchers, or German pages appearing for English queries, both point to a hreflang or content problem worth investigating. Every Priority Pixels SEO retainer client can filter our reporting platform by country as well as date range, device and source, which makes this kind of shift easier to spot month by month.

Hreflang also needs checking after every release that touches URLs, templates or plugins, since one change in a single market can break the return links for every other version. Our technical SEO services include hreflang alongside canonicalisation, indexation control and crawl budget, so international annotations are reviewed as part of the same audit cycle rather than left until rankings slip in a market.