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
httpor no-trailing-slash version, while the canonical ishttpswith 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:
- 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.
- 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.
- 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.
- 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.