🌍 Hreflang Tag Builder
Generate valid hreflang <link> tags for multi-language & multi-region websites.
Page Entries
Add each language/region version of your page with its URL. Use ISO 639-1 language codes and ISO 3166-1 country codes.
Options
🌍 Hreflang Tag Builder
Why Hreflang Is Harder Than It Looks
The hreflang attribute was introduced by Google in 2011 to solve a specific problem: when a website publishes multiple versions of the same page for different languages or regions, search engines need explicit signals to understand which version to serve to which audience. Without it, Google guesses — and its guess is often wrong.
The concept seems simple enough. You add a <link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/"> tag in your page's <head>, and Google knows that page is the English version for the United Kingdom. But the implementation has three requirements that catch most sites out.
First, the relationship must be bidirectional and complete. Every language version of a page must reference every other language version, including itself. If your English page references the French page but the French page doesn't reference the English page back, Google may ignore the entire signal for both pages. This means a site with 12 language variants needs each of those 12 pages to carry 12 hreflang tags — 144 tag instances total, all pointing to exactly the right URLs. A single broken link invalidates the chain.
Second, the language and region codes must follow the right standards. Language codes come from ISO 639-1 (two-letter codes like en, fr, de), while region codes come from ISO 3166-1 Alpha-2 (also two letters, but uppercase: US, GB, AU). The format is always language first, then an optional hyphen-separated region: en, en-US, en-GB. A common mistake is using en-uk (lowercase) or EN-GB (uppercase language), or reaching for locale codes like en_US with an underscore — none of these work.
Third, the x-default tag is not optional for most real sites. When no language/region combination matches the user's browser settings, Google needs somewhere to send them. The x-default tag designates that fallback URL — usually a language selector page or the most widely used version. Without it, Google picks arbitrarily, and that arbitrary choice is often wrong for users who speak a language you do not have a dedicated page for.
The Practical Architecture Choices
Before generating any tags, you need to decide on your URL structure. There are three common approaches: country-code top-level domains (example.de, example.fr), subdomain separation (de.example.com, fr.example.com), and subdirectory paths (example.com/de/, example.com/fr/). All three work with hreflang.
The hreflang strategy differs slightly depending on your structure. With ccTLDs, you would typically use the language-region combination like de-DE for your German domain, but you might also add a region-free de tag if you want to catch German speakers from Austria and Switzerland without dedicated country domains. With subdirectories on a single domain, the path itself communicates less to Google, making the hreflang signal even more critical for correct targeting.
A frequent source of confusion is the difference between language targeting and country targeting. hreflang="en" targets English speakers regardless of country — useful if your content is identical for all English-speaking markets and you do not want to maintain separate US and UK pages. hreflang="en-US" targets specifically users Google believes are in the United States who prefer English. You can use both: a generic en tag alongside specific en-US and en-GB tags, giving Google a clear hierarchy of preferences.
Where to Place Hreflang Tags
There are three valid places to implement hreflang: in the HTML <head>, in the HTTP response headers, or in an XML sitemap. The HTML method is the most straightforward and the one most tools and tutorials focus on. You place the <link> elements inside <head>, and they apply to that page.
The HTTP header method suits non-HTML files like PDFs — you cannot embed HTML in a PDF, but you can send hreflang annotations in the response headers your server sends when that file is requested. This is genuinely useful for international document libraries but rarely needed for standard web pages.
The XML sitemap method is worth understanding even if you implement hreflang in your HTML. Instead of placing tags on every page, you define all the alternate relationships centrally in your sitemap using the xhtml:link element inside each <url> block. This requires adding the xmlns:xhtml namespace declaration to your <urlset> tag. For large sites with thousands of pages, the sitemap approach can be easier to maintain programmatically — but if you use it, you should be consistent and not mix it with HTML hreflang on the same pages.
The Self-Reference Rule and Why It Matters
One of the less intuitive requirements is that every page must include a hreflang tag pointing to itself. The English page must include hreflang="en-US" pointing to the English page's own URL. This is not redundant — it is part of what Google uses to build the complete set of canonical alternatives for each page group. A page that lists all the other language variants but omits itself from the annotation is technically incomplete, and Google's documentation explicitly requires self-referencing.
Missing self-references are one of the most common errors caught in technical SEO audits, precisely because they feel unnecessary. Why would a page need to point to itself? The answer is that Google assembles these tags across all the pages it crawls, and a page that does not declare its own membership in a language group creates ambiguity about whether it truly belongs in that group.
Validating Your Implementation
After deploying hreflang tags, validation is not optional. The Google Search Console International Targeting report shows detected hreflang errors, including mismatched return tags, invalid language codes, and URLs that returned errors when Googlebot crawled them. Hreflang errors in Search Console are not always critical — some are warnings — but missing return tags are genuine problems that prevent the signal from working.
Third-party crawlers like Screaming Frog can audit hreflang across your entire site by crawling all language versions and cross-referencing the tag sets. This kind of site-wide audit is essential for large multilingual sites where a CMS template bug might have corrupted hreflang tags on thousands of pages simultaneously.
The most common real-world hreflang failures are: tags added to only some pages but not others (partial implementation); URLs in hreflang tags that redirect rather than pointing directly to the canonical URL; and CMS deployments where the template generates hreflang tags but hard-codes the domain, so every language version generates tags pointing to the same domain rather than the correct regional URL.
Getting hreflang right is worth the effort. Sites that implement it correctly see measurably better geographic targeting in Search Console, fewer instances of the wrong language variant ranking in a given country, and — for e-commerce sites especially — improved conversion rates because users land on pages that match their language and show appropriate currency and pricing.
]]>