Implementing hreflang: Common Mistakes and Validation Methods

Setting up hreflang without errors via HTML, HTTP headers and XML sitemaps: language-region codes, x-default, return links, canonical conflicts and command-line checks.
Technical summary
Technology
hreflang, ISO 639-1, ISO 3166-1 alpha-2, XML sitemap, HTTP Link header, rel=canonical
Topic
Implementing and auditing hreflang on multilingual/multi-region sites
Level
Intermediate–advanced
Prerequisites
  • The multilingual site structure (subdirectory, subdomain or ccTLD) has been decided
  • Access to page templates or sitemap generation
  • A crawling tool (e.g. Screaming Frog) and Search Console access
In this article7 sections

If a user from Germany is shown the Turkish page on a multilingual site, the first place to look is the hreflang cluster. This markup tells the search engine about the language and region versions of the same content. Setting it up looks simple; but a single missing return link or a wrong region code is enough for the whole cluster to be ignored. The error is silent: the site works, only the wrong version ranks. This guide explains how to set up hreflang without errors and how to audit it once the structural decision has been made.

What hreflang does, and what it doesn’t

hreflang isn’t a ranking signal. It helps the right one be chosen when several language versions are candidates for the same query. For example, on the service page of a corporate website with English and Turkish versions, which version is shown to a user in Türkiye searching in English is determined by hreflang and other signals.

What it doesn’t do is at least as important:

  • It doesn’t redirect users. Automatic redirection by browser language is a separate implementation and isn’t recommended because it can block Googlebot’s access to versions. Use language switcher links.
  • It doesn’t replace canonical. Each language version carries a canonical pointing to itself.
  • It doesn’t make up for translation quality. Pages where only the template text is translated and the body stays in the same language may be treated as duplicate content.

Before moving on to hreflang, the structural decision (subdirectory, subdomain or country-code domain) must have been made. The consequences of that decision are in the multilingual site architecture article. No tags are written until the structure is settled.

Implementation methods: HTML, HTTP header, sitemap

Google treats the three methods as equivalent. Choose one method and apply it consistently; if you use more than one method for the same cluster, they must all carry exactly the same information. If two sources don’t match, look there first when troubleshooting.

Method When it fits Watch out for
HTML <link> Few language versions, access to templates Every page’s head grows each time a language is added
HTTP Link header Non-HTML files such as PDFs Managed in the server/CDN configuration, low visibility
XML sitemap Many languages or pages Sitemap generation must stay in sync with CMS content

In the HTML head

<link rel="alternate" hreflang="tr" href="https://www.example.com/tr/hizmetler/yedekleme/" />
<link rel="alternate" hreflang="en" href="https://www.example.com/en/services/backup/" />
<link rel="alternate" hreflang="de-DE" href="https://www.example.com/de/leistungen/datensicherung/" />
<link rel="alternate" hreflang="x-default" href="https://www.example.com/en/services/backup/" />

The same block appears on every page in the cluster, and every page also lists itself. Forgetting the self-reference is one of the gaps we come across most often in the field.

With an HTTP header

Link: <https://www.example.com/tr/katalog.pdf>; rel="alternate"; hreflang="tr",
      <https://www.example.com/en/catalog.pdf>; rel="alternate"; hreflang="en"

With an XML sitemap

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://www.example.com/tr/hizmetler/yedekleme/</loc>
    <xhtml:link rel="alternate" hreflang="tr" href="https://www.example.com/tr/hizmetler/yedekleme/"/>
    <xhtml:link rel="alternate" hreflang="en" href="https://www.example.com/en/services/backup/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://www.example.com/en/services/backup/"/>
  </url>
  <url>
    <loc>https://www.example.com/en/services/backup/</loc>
    <xhtml:link rel="alternate" hreflang="tr" href="https://www.example.com/tr/hizmetler/yedekleme/"/>
    <xhtml:link rel="alternate" hreflang="en" href="https://www.example.com/en/services/backup/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://www.example.com/en/services/backup/"/>
  </url>
</urlset>

In the sitemap method, each language version appears as its own <url> entry, and the whole cluster is repeated in every entry. If the xhtml namespace declaration is forgotten, the file isn’t valid XML. The whole cluster goes unread.

Language and region codes, x-default

The value format is language or language-REGION. The language code must be ISO 639-1 (two letters) and the region code ISO 3166-1 alpha-2. It isn’t case-sensitive; writing de-DE is a common convention for readability. A region code can’t be used on its own: writing hreflang="gb" to target the United Kingdom is invalid; the correct form is en-GB. Likewise, hreflang="de" means the German language, not Germany. For languages such as Chinese, a script subtag (zh-Hant, zh-Hans) can be used.

Wrong Right Why
en-UK en-GB The ISO code for the United Kingdom is GB
tr-TU tr-TR The ISO code for Türkiye is TR
en-EU en or country-based codes EU isn’t supported as a country code
ge (German) de The ISO 639-1 code for German is de
tr_TR tr-TR The separator is a hyphen, not an underscore

x-default specifies the version to show to users with no language/region match. Usually the language selector page or the international (mostly English) version is chosen. It isn’t mandatory but is recommended; it reduces confusion, especially when there’s a general version alongside regional versions.

There’s a trap to know about on the WordPress side: the output of get_locale() is in the form tr_TR. Multilingual plugins convert it, but a developer writing hreflang into a template by hand who outputs this value directly produces invalid codes with underscores. A crawling tool shows this immediately.

Reciprocity and canonical consistency

The hreflang relationship is two-way: if page A lists B as an alternate, B must also list A. A relationship without a return link is ignored. The reason is security; otherwise any site could declare another site to be its language version.

On the canonical side, the rule is simple: every URL listed in hreflang must be its own canonical URL. The conflicts found most often in audits:

  • The English page’s canonical points to the Turkish page. The English page is declared “a copy of the Turkish page” and the cluster breaks.
  • A parameterized URL (?lang=en) is listed in hreflang, while the canonical points to the URL without parameters.
  • hreflang has the http or no-trailing-slash version, while the canonical is https with a trailing slash.

Listed URLs must return 200, must not carry noindex and must not be blocked by robots.txt. The general use of these signals is covered in detail in the canonical, noindex, robots.txt and sitemap article.

Table of common mistakes

Error Symptom Remediation
No return link “Missing return links” in the crawling tool Generate the cluster with the same list in all versions
No self-reference The cluster appears incomplete Every page must also include its own language line
A redirected URL is listed A target returning 3xx Write the final 200 URL
Pointing to a noindex or 404 page The cluster is partly invalid If there’s no version, remove the line
Relative URL href="/en/..." Use a full, absolute URL
Bulk mapping to the home page All English hreflangs go to the /en/ home page Map the real counterpart at page level; if there isn’t one, don’t add a line
Link outside the head The tag is in the body or after an invalid element Place it near the start of the head, within valid HTML

The last row is particularly insidious. An invalid element placed inside the head (for example a <div> or <img> output by a plugin) can cause the browser parser to close the head early. The hreflang lines after that point end up in the body and are ignored. In the source code, the lines appear to be there. Look at the rendered DOM.

Validation and monitoring

Since the old International Targeting report in Search Console has been removed, hreflang auditing is largely done with technical SEO crawling tools. The order of checks we apply:

  1. Site crawl: Enable hreflang extraction in a tool such as Screaming Frog SEO Spider and crawl the whole site. Export the reports on missing return links, invalid codes, non-canonical URLs and non-200 targets.
  2. Sitemap check: If the sitemap method is used, crawl the sitemap as a separate list; check whether pages deleted from the CMS remain in the sitemap.
  3. Sample page test: On important pages, run the live test with the URL Inspection tool and verify that the hreflang lines are inside the head in the rendered HTML.
  4. Monitoring results: Examine pages in the Search Console Performance report with a country filter. If, on pages that have a German counterpart, Turkish URLs get most of the impressions under the Germany filter, the cluster may not be working.

For a quick check on the command line, you can pull a page’s hreflang lines, headers and the status codes of the targets:

# hreflang lines in the HTML
curl -s https://www.example.com/tr/hizmetler/yedekleme/ | grep -io '<link[^>]*hreflang[^>]*>'

# HTTP Link header (PDFs, etc.)
curl -sI https://www.example.com/tr/katalog.pdf | grep -i '^link:'

# Status codes of the listed targets
for u in https://www.example.com/tr/hizmetler/yedekleme/ https://www.example.com/en/services/backup/; do
  printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "$u")" "$u"
done

Add a permanent check too: when a language version is deleted or its slug changes, are the hreflang lines in the other languages updated automatically? Manually managed clusters are the structures that break most often in site migrations; how to do this check during a migration is covered in the article on preventing SEO loss when migrating a website. For the official definition of the rules, refer to Google’s localized versions documentation.

On a multilingual site, hreflang can’t be thought of separately from the content model. Keeping the mapping between versions as data in the CMS is the first structure we set up in multilingual and multi-region website projects. If the mapping lives in the data, the tags come out right on their own.

Frequently asked questions

Is hreflang needed on a single-language site?

No. hreflang only makes sense when there are different language or region versions of the same content; a single self-referencing line on a single-language site gains nothing. Setting the html lang attribute correctly is still needed for accessibility and browsers, but Google states that it doesn’t rely on this attribute for language detection.

Should I write tr or tr-TR for a Turkish page?

If the Turkish content targets only Türkiye, both are valid. If you also target Turkish speakers in other countries and there’s no separate region-specific version, tr with just the language code is more inclusive. The real rule is that the chosen code is used consistently across the whole cluster.

Does hreflang replace redirects or canonical?

No. hreflang doesn’t redirect users and doesn’t solve duplicate content on its own; it only gives a hint about which version to show to which user. Each language version continues to carry a canonical pointing to itself.

How long does it take for results to improve after a change?

There’s no fixed time. Google needs to recrawl all the pages in the cluster; for rarely crawled pages, this takes longer. Updating the sitemap and checking important URLs with the URL Inspection tool make the process easier to follow.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles