How to Use Hreflang Tags: Complete Guide + Free Tool
If your site serves more than one language or country, hreflang tags tell search engines which URL belongs to which audience. A valid cluster helps Google show the right version to each audience; a broken one leaves Google swapping between duplicates or ranking the wrong version. This guide covers the syntax, return tags, x-default and the mistakes that silently invalidate an annotation set, plus a free hreflang tag generator outputting valid tags and an XML sitemap alternative.
What Are Hreflang Tags?
Hreflang is an attribute on the HTML <link> element that marks a group of URLs as localized versions of the same content:
<link rel="alternate" hreflang="de-DE" href="https://example.com/de/" />The tag goes in the <head> of every language version.
Two facts matter: hreflang is a hint, not a directive — a valid set helps Google show the right version, it does not force one. And Google does not use hreflang (or the lang attribute) to detect a page’s language; it determines that algorithmically.
Hreflang Syntax: Language, Script, and Region Codes
The value follows a fixed order — language, optional script, optional region — from ISO 639-1, ISO 15924 and ISO 3166-1 Alpha 2. Codes are case-insensitive; convention is lowercase language, uppercase region.
Valid codes:
en-GB— English for UK userszh-Hans— Chinese, Simplified script
The traps, called out in Google’s documentation:
en-UK— invalid:UKis not an officially assigned ISO 3166-1 element, so Google ignores it (same forEUandUN); useen-GB.gb-en— wrong order: the language always comes first.es-419— numeric UN region codes are unsupported; only ISO 3166-1 Alpha 2.beas “Belgium” — a region alone is invalid, andbeis the Belarusian language; usenl-BE,fr-BEorde-BE.
Google’s guidance for multi-locale languages: if you target several locales of one language (en-IE, en-CA, en-AU), provide a generic en catch-all for everyone else. Google calls this “a good idea,” not a requirement, and the catch-all may share a URL with one of the regional versions — en can point at the same URL as en-IE.
Return Tags: Why Every Version Must Point Back
Return tags are the reciprocity rule. If page X links to page Y, Y must link back to X — and every version must also list itself. Google’s rule: if two pages don’t both point to each other, the annotations are ignored. The commonly given rationale: without return links, anyone could declare their page an alternate of yours. On a site with English and German versions, the <head> of both pages contains the same set of tags:
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="de-DE" href="https://example.com/de/" />Both pages carry these two lines; omit the set on any version and the cluster starts to break. Google’s documented relaxation: when a complete bidirectional set becomes hard to maintain, omit some languages on some pages — pairs that still point at each other keep working. The stated priority: link newly added language versions bidirectionally to your site’s originating (dominant) language — a site that grew from French .fr pages wires new Spanish versions back to the French pages first, to each other second.
What Is x-default and When Do You Need It?
x-default is a reserved value naming the URL to serve when none of your listed languages match the user’s browser settings — one extra link tag, no language code:
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/select-language/" />x-default is optional but recommended — designed for language-selector pages and auto-redirecting homepages. Pointing it at your default language version is the other standard pattern, and what the generator expects.
Three Ways to Implement Hreflang Tags
Google treats three methods as exactly equivalent; its documentation says using all three at once brings “no benefit in Search” and is harder to manage than picking one.
1. HTML link tags in the head
For small sites: put the full set inside a well-formed <head> on every version. Two Google rules: the tags must actually be inside the head (validate rendered HTML if your CMS rewrites markup), and don’t merge hreflang with attributes like media in one tag.
2. XML sitemap annotations
At scale, keep hreflang out of the HTML: add an xhtml:link child for every version, including itself, inside each <url> entry, alongside <loc>:
<url>
<loc>https://example.com/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/" />
<xhtml:link rel="alternate" hreflang="de-DE" href="https://example.com/de/" />
</url>Declare the xmlns:xhtml="http://www.w3.org/1999/xhtml" namespace and repeat a <url> block for every version. Child order doesn’t matter, and Google confirms the xhtml:link children don’t count toward the sitemap URL limit — the protocol’s 50,000-URL cap counts <url> entries.
3. HTTP Link headers
For non-HTML files like PDFs, set a Link header where the file is served — in nginx, an add_header rule on its location:
add_header Link '<https://example.com/file.pdf>; rel="alternate"; hreflang="en",
<https://example.com/de/file.pdf>; rel="alternate"; hreflang="de"';Apache’s Header set or a CDN response-header rule does the same.
How to Generate Hreflang Tags with the Free Tool
The hreflang tag generator builds the set and validates as you type — no signup, runs in your browser.
Step 1: Build the complete set
Add one row per version — language code left, absolute URL right — including a row where the page you are annotating points at itself. The self-reference is required, and this identical set gets pasted into every version’s head (Step 4) — build it once, complete. Codes are validated live against the language-script-region pattern — en, pt-BR and zh-Hans pass, gb-en is flagged — and case is normalized (en-gb becomes en-GB).
Step 2: Set the x-default URL
Enter the fallback URL — your default language version or selector page — or leave it empty to skip x-default. A warning fires when the URL falls outside the set: normal and correct for a selector page, which sits outside the language cluster by design; without one, it usually means a typo.
Step 3: Generate and review the checks
Click Generate hreflang tags. The checklist flags duplicate language codes as errors, rejects non-absolute URLs, and warns about self-references and single-entry sets. A single entry usually means the other versions are missing — add them, since hreflang pays off only when two or more versions reference each other; a page with no equivalents needs no hreflang at all. Fix anything red, regenerate.
Step 4: Copy the output in the format you need
Two tabs hold the output. HTML link tags is ready for your <head> — paste the identical block into every version. XML sitemap emits a <url> block, not a complete sitemap: paste it inside a full sitemap’s <urlset> element (namespaces above), for instance the base file from the XML sitemap generator. Copy code and Download file move the output; the meta tag generator covers the rest of a multilingual head.
Common Hreflang Mistakes (and How to Fix Them)
Mistake 1: Omitting the self-referencing entry
The most common error: every version listed except the page itself. Google’s rule is the opposite — every version must list itself plus all others. Fix: add a row for the current page.
Mistake 2: One-way annotations (missing return tags)
Your German page lists the English page, but the reverse was never added — Google ignores one-way pairs. Fix: the identical set on every version; re-check both sides after any launch or URL change.
Mistake 3: Invalid or misordered codes
en-UK, es-419, gb-en or a region alone — Google ignores the invalid region or malformed code, quietly disabling that part of the cluster. Fix: language first (ISO 639-1), region second (ISO 3166-1 Alpha 2); the generator validates codes live.
Mistake 4: Hreflang fighting your canonical
Each version should carry a self-referencing canonical. If the German page canonicals to the English one, you call it a duplicate at the exact moment hreflang calls it an equal alternate — conflicting signals that can stop the set working. Fix: self-canonicals everywhere; let hreflang group.
Mistake 5: Redirecting or relative URLs in the set
Alternate URLs must be fully qualified — https://example.com/de/, never /de/ or //example.com/de/ — and should return a 200, not a redirect chain: a de-DE entry that 301s elsewhere forces Google to resolve the chain first. Run URLs through the redirect chain checker at audit time; confirm the tags sit inside a well-formed head in rendered source.
Frequently Asked Questions
Do hreflang tags improve rankings?
Not directly — hreflang is a routing signal that helps Google serve the right version, not a ranking boost. The gain is indirect but real: fewer duplicate versions competing, and users landing in their own language.
Do hreflang tags have to go in the head?
Only with the HTML method — there they must sit inside a well-formed head; sitemap and HTTP header methods are equivalent alternatives when you cannot control head markup.
Is x-default mandatory?
No. It is optional and works best on language-selector pages and auto-redirecting homepages. Most other sites point it at the default language version, a safe pattern.
Can hreflang URLs live on different domains?
Yes — alternate URLs need not share a domain, which is why hreflang is standard for ccTLDs like example.de and example.co.jp. A ccTLD or country subdomain gives Google geo hints, but not which URLs are alternates of each other: map every version explicitly.
How do I check my hreflang tags, and how long do fixes take?
View the rendered source of each version and confirm the full set, including the self-reference, sits inside the head. Third-party hreflang testers validate live pages (Google names Aleyda Solis’s generator and the Merkle hreflang tester), and crawlers scale the check site-wide; Search Console’s International Targeting report was retired in 2022, so there is no dedicated hreflang error report there. Fixes land as every URL in the cluster is recrawled — typically days to weeks.
Can I use hreflang for same-language pages like en-US and en-GB?
Yes — Google’s own use cases include regional variation in one language: English content targeted at the US, GB and Ireland. Translation is not required; the tags tell Google which regional variant to serve — the difference can be currency or shipping details alone.
What happens if one version in the set is noindexed or blocked?
Every URL in a cluster should be crawlable and indexable: a noindexed or blocked page cannot be shown as an alternate, and the dead entry weakens the pairing for the rest. Lift the block, or drop that version from every page’s set.
Must the hreflang URL match the canonical URL exactly?
It should: each entry names the URL that version’s canonical points to — same protocol, host and trailing slash. Entries must be fully-qualified URLs, and a non-canonical target (tracking parameter, stray trailing slash) forces Google to resolve duplicates before pairing. Exact-match URLs plus self-canonicals keep the cluster clean.