Hreflang is an HTML attribute that tells search engines which language and regional version of a page to show to which users. It appears as a rel="alternate" hreflang="xx-YY" link element inside the head of every page that belongs to a multilingual or multinational content cluster. Search engines such as Google read these tags to understand the relationships between equivalent pages in different languages or targeted regions, which helps them serve the right URL to the right audience. Hreflang is not a translation tool, it does not change the actual language on a page, and it does not by itself guarantee any particular search result. The attribute describes a relationship among substantially equivalent pages so the engine can pick the most appropriate version based on the user's language settings, location, and other signals. Used correctly, hreflang reduces the chance that a Spanish-speaking visitor lands on the English page or that users in Canada see the US storefront when a dedicated Canadian version exists.
For SEO purposes, hreflang matters because search engines must otherwise guess the right URL to show. Without explicit tags, an English page about winter tires may outrank a Canadian-specific French page even when the user is searching from Montreal. The tags remove that guesswork and keep international traffic on the page that was actually written for them, which improves click-through, reduces bounce, and signals content quality across regions.
What Hreflang Tags Tell Search Engines
Each hreflang link element carries three pieces of information: a language value, an optional region or script modifier, and the fully qualified URL of an equivalent page. Search engines cross-reference the hreflang values across all the pages that share the same set, so every page in the cluster must list every other page, including a link back to itself. Google's documentation describes self references and return links as essential signals, and a one-way declaration may be ignored because another site must not be able to claim your page as its alternate unilaterally.
The hreflang attribute does not override the user's language preference entirely. Search engines treat hreflang as one signal among many and may still surface a different version if the user's settings, query, or browsing history point that way. What the tag does guarantee is that the engine is informed about the cluster, so it can make that choice deliberately rather than by accident.
The Anatomy of a Locale Value
A hreflang value follows the structure defined by the IETF language tag specification used by browsers and search engines. The first subtag is always a two-letter language code drawn from the ISO 639-1 list, and it cannot stand alone as a country code. After the language, an optional four-letter script subtag can distinguish writing systems, and an optional two-letter region subtag can target a country. Case is canonicalized during processing, so en-us is treated as en-US and zh-hant as zh-Hant, which means the canonical form below is what readers and engines will see in the rendered markup.
| Locale Form | Structure | Typical Use |
|---|---|---|
| en | Language only | Generic English page used as a fallback for several country-specific English pages |
| en-US | Language plus region | US-targeted English content; canonical casing requires the region in uppercase |
| fr-CA | Language plus region | Canadian French content, distinct from European French |
| zh-Hans | Language plus script | Simplified Chinese content in mainland China and Singapore |
| zh-Hant | Language plus script | Traditional Chinese content in Taiwan, Hong Kong, and Macau |
| x-default | Special token | Generic landing page or country selector for users whose settings match no listed alternate |
The x-default value is not a language at all; it identifies a fallback page intended for users whose language or region does not match any other alternate in the set, which is often a country selector or a generic global landing page. Only one x-default row should appear in any cluster, because two competing fallbacks would defeat the purpose of pointing users to a single catch-all destination.
Where Hreflang Tags Belong in Your HTML
Search engines accept hreflang in three places: inside the HTML head as link elements, inside HTTP response headers for non-HTML files such as PDFs, and inside XML sitemaps. Google treats these methods as equivalent for international targeting, which means you should pick the single method your publishing system can keep complete and synchronized. Maintaining three copies across HTML, headers, and sitemaps creates drift, and drift is one of the fastest ways to break an otherwise clean hreflang cluster.
| Implementation Method | Best For | Caveats |
|---|---|---|
| HTML head link elements | Regular web pages in a CMS or hand-edited templates | Must appear on every page in the cluster with the full set including a self-reference |
| HTTP response headers | PDFs, images, and other non-HTML files that have no head section | Headers must be added by the web server or CDN, and self-references still apply |
| XML sitemap | Large sites where editing every head section is impractical | One sitemap entry per locale per URL; the file becomes the single source of truth |
For most content-driven websites, the HTML head is the easiest place to manage hreflang because the markup travels with the template and is visible in the rendered page. For sites that ship large libraries of localized PDFs or product images, HTTP headers prevent forcing every binary into an HTML wrapper. Sitemaps shine when the locale set changes often or when the publishing system makes per-page edits painful, but they require careful validation because a single missing entry silently removes an alternate from the cluster.
How to Build a Complete Hreflang Set With the Hreflang Generator
The Hreflang Generator produces a head-ready block of escaped rel="alternate" link elements from one list of locale-and-URL rows. Each row is a language or locale followed by a fully qualified URL of the equivalent page, separated by a vertical bar. The tool returns one link element per row, HTML-escapes attribute-sensitive characters, canonicalizes locale casing, and rejects malformed inputs so the entire set fails rather than producing a partial block that silently omits a language.
- Inventory every equivalent localized page and write one row per locale using the format locale | fully qualified URL. Include the page currently being edited and add an x-default row only when a genuine fallback page exists for users whose language or region does not match any other alternate.
- Paste the rows into the Hreflang Generator and generate the complete escaped link block. Verify that the locale column matches current supported language and region guidance for your audience, because the tool checks language-tag shape rather than the complete ISO registry supported by a particular search engine.
- Install the identical block in the head of every alternate page, including the current page itself. Each localized version must publish the same complete set so that self and return links line up across the cluster.
- Crawl the live pages and confirm that every page lists itself, lists every other page, and resolves to a useful 200 response. Treat any missing reciprocal link as a defect, because search engines ignore one-way declarations.
The generator supports up to 100 rows and requires at least two, including the current page. URLs must be fully qualified with http or https, including the host. Relative references, scheme-relative references, fragments, and embedded credentials are rejected, which keeps the cluster addressable and avoids ambiguity between versions served from different hosts or subdomains. When a locale is added, removed, redirected, or moved to a new canonical URL, the set must be regenerated and reinstalled on every member so the cluster stays synchronized.
Common Hreflang Pitfalls and How to Prevent Them
The most common hreflang failure is a one-way declaration, where page A points to page B but page B does not point back. Because search engines require reciprocal references to confirm the relationship, a missing return link causes the entire cluster to be ignored. The next most common problem is mixing implementation methods: a page that lists its alternates in the HTML head while the sitemap declares a different set creates two competing signals that engines cannot reconcile.
Another frequent pitfall is using a region code where a language is required, such as hreflang="US" on its own. The first subtag must identify the language, so the correct form is hreflang="en-US". Generic language pages such as en or fr are useful as fallback rows when several country-specific versions exist, but they should sit alongside the regional rows rather than replace them. Confusing x-default with a real language is also common; x-default is a fallback token, not a translation target, and only one x-default row should appear in a set.
Duplicate locale values are rejected case-insensitively after normalization, which prevents accidentally listing the same language twice under different casing. Locale casing mistakes like en-us instead of en-US are normalized to en-US during input processing, so they do not break the cluster, but writing them in canonical form from the start makes the markup easier to audit.
Verifying Hreflang After Deployment
After the identical block is installed on every page in the cluster, crawl a sample from each language and compare the link sets mechanically. Each page must list itself, list every other page, and resolve to a 200 response with the expected localized content. When a row points to a redirect, expired URL, or soft 404, search engines will quietly drop that alternate from the cluster and may surface an unrelated page instead. For a structured walkthrough of the post-deployment checks, the guide on how to check hreflang tags for multilingual SEO accuracy covers the audit steps in more detail.
Ongoing quality depends on updating all members when a locale is added, removed, redirected, or moved to a new canonical URL. Google's internationalization documentation treats hreflang as a relationship rather than a guarantee, so combining clean markup with coherent content architecture and verified server responses produces the strongest signal. For the underlying markup rules, Google's localized versions documentation and the WHATWG HTML alternate links specification are the authoritative references for implementation details and edge cases.