Where to Declare Hreflang: HTML, XML Sitemap, or HTTP Header (and Why You Should Never Use Two)
- February 6, 2024
- International SEO
Google accepts hreflang annotations from three sources: HTML link elements, HTTP headers, or your XML sitemap, and any one of them works exactly as well as the others. Pick a single method and never run two at once, because duplicate declarations are how conflicting signals creep in and get your hreflang ignored entirely.
Hreflang is one of the few SEO signals where Google hands you a menu. You can declare your localized page versions in the HTML head, in an HTTP response header, or inside your XML sitemap, and Google treats all three as equivalent. That flexibility is genuinely useful, because different sites have different constraints. It is also a trap, because teams routinely read "three options" as "three layers of insurance" and implement more than one.
This article covers each method in detail, with working syntax, then explains why doubling up is the single most reliable way to manufacture hreflang conflicts, and finishes with a decision framework so you can commit to the right method for your site and move on. If you are new to hreflang as a concept, start with our complete hreflang implementation guide and come back here when you need to choose where the annotations should live.
The three official methods
Google's documentation, "Tell Google about localized versions of your page," lists exactly three supported delivery mechanisms for hreflang. There is no fourth. JavaScript-injected link elements technically end up in the rendered HTML and can be picked up, but they depend on rendering and are not a separate method; meta tags, robots.txt, and structured data are not valid carriers at all. Here is each method, what it looks like, and where it shines.
Method 1: HTML link elements in the head
The classic approach. Every localized page carries a set of link rel="alternate" elements in its <head>, one for each language or regional version, plus one for itself and one for x-default. A three locale setup looks like this:
<head>
<link rel="alternate" hreflang="en-us"
href="https://example.com/en-us/pricing/" />
<link rel="alternate" hreflang="de-de"
href="https://example.com/de-de/preise/" />
<link rel="alternate" hreflang="fr-fr"
href="https://example.com/fr-fr/tarifs/" />
<link rel="alternate" hreflang="x-default"
href="https://example.com/" />
</head>Strengths: it is visible, debuggable with view-source, and supported by every SEO plugin and crawler on the market. Weaknesses: the full cluster must appear on every page in the cluster, so the markup grows quadratically with your locale count. Ten locales means eleven link elements (including x-default) on every one of those ten pages. Forty locales means forty-one link elements on every page, repeated across your entire template. That is real HTML weight on every single response, and it has to stay perfectly synchronized across all versions.
Method 2: The HTTP Link header (the forgotten one)
The least used and least known method, and the only one that works for content with no HTML head to put tags in. If you publish localized PDFs, Word documents, or other non-HTML assets, the HTTP header is not just an option, it is the only on-response option you have. The server returns a Link header alongside the file:
HTTP/1.1 200 OK
Content-Type: application/pdf
Link: <https://example.com/whitepaper-en.pdf>; rel="alternate"; hreflang="en",
<https://example.com/whitepaper-de.pdf>; rel="alternate"; hreflang="de",
<https://example.com/whitepaper-fr.pdf>; rel="alternate"; hreflang="fr"Note the structure: each entry is a URL in angle brackets, followed by rel="alternate" and the hreflang attribute, with entries separated by commas. The same reciprocity rules apply, so each PDF's response must list itself and all of its siblings. Implementation usually lives in server config, a CDN edge rule, or application middleware, which means your SEO team needs cooperation from whoever owns the infrastructure. That dependency is the main reason this method stays niche for HTML pages, but for non-HTML content it is mandatory knowledge.
Method 3: XML sitemap with xhtml:link entries
The sitemap method moves all hreflang data out of your pages and into one centralized file. Each <url> entry lists every alternate version of that URL, including itself, using the xhtml namespace:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/en-us/pricing/</loc>
<xhtml:link rel="alternate" hreflang="en-us"
href="https://example.com/en-us/pricing/" />
<xhtml:link rel="alternate" hreflang="de-de"
href="https://example.com/de-de/preise/" />
<xhtml:link rel="alternate" hreflang="x-default"
href="https://example.com/" />
</url>
<url>
<loc>https://example.com/de-de/preise/</loc>
<xhtml:link rel="alternate" hreflang="en-us"
href="https://example.com/en-us/pricing/" />
<xhtml:link rel="alternate" hreflang="de-de"
href="https://example.com/de-de/preise/" />
<xhtml:link rel="alternate" hreflang="x-default"
href="https://example.com/" />
</url>
</urlset>Yes, the full alternate set is repeated under every URL entry, so sitemap files for large international sites get big. That is fine. Sitemaps are fetched by crawlers, not shipped to users, so the weight costs you nothing on page delivery. The single biggest advantage is operational: one generated file is one source of truth, typically produced by a script or your platform's export job, which makes it auditable, diffable, and fixable in one place when a locale launches or retires.
Can you use two methods at once?
Technically, Google will parse hreflang from all three sources, and its documentation acknowledges you can use them simultaneously. It then immediately tells you not to bother: the methods are equivalent from Google's perspective, there is no benefit in Search to stacking them, and maintaining multiple implementations is much harder than just picking one. Read that as the polite version of "please do not."
Here is the failure mode. Hreflang annotations are not static. Locales launch, URLs migrate, pages get retired, slugs get translated. With one method, every change touches one system. With two, every change must land identically in both, forever, usually maintained by different teams on different release cycles. The day your sitemap says the German alternate is /de-de/preise/ while the HTML head still says /de/pricing/, Google sees two contradictory claims about the same relationship. Conflicting signals do not average out; when alternates disagree or reciprocity breaks, Google simply ignores the hreflang for those pages, and your carefully localized URLs start cannibalizing each other in the wrong markets. We cover the diagnosis side in our check for conflicting hreflang entries, and it is one of the checks that fires most often on sites running a plugin and a sitemap generator in parallel.
If this sounds like a hypothetical risk, the data says otherwise. Patrick Stox's hreflang study at Ahrefs, the largest analysis of its kind, examined 374,756 domains using hreflang and found that 67% of them have at least one hreflang issue. Two thirds of all sites that even attempt hreflang get something wrong with a single implementation. Adding a second source of truth does not hedge against that failure rate, it multiplies the surface area where those failures happen. Maintaining two parallel hreflang implementations is the SEO equivalent of wearing two watches: you are never quite sure what time it is, you have simply guaranteed a disagreement.
There is one legitimate hybrid: HTML link elements (or sitemap entries) for your pages, plus HTTP headers for your non-HTML assets. That is not two methods for the same content, it is one method per content type, and the clusters do not overlap. The rule is never two declarations for the same URL.
Decision framework: which method fits your site
The right answer depends on four factors: how many locale and URL combinations you manage, what level of access you have, whether you serve non-HTML content, and which team owns the implementation long term.
| Situation | Best method | Why |
|---|---|---|
| Small site, 2 to 5 locales, CMS with an SEO plugin | HTML link elements | Simplest to set up and verify; plugin handles reciprocity; cluster size is small enough that page weight is negligible |
| Large site, many locales, thousands of URLs | XML sitemap | No page bloat (dozens of locales would mean dozens of link tags on every single page); one generated file; easy to audit and regenerate |
| Localized PDFs or other non-HTML files | HTTP Link header | The only on-response option when there is no HTML head |
| No template or server access, but you control sitemap generation | XML sitemap | Decouples hreflang from the page templates and from engineering release cycles |
| SEO team owns templates, dev team owns sitemaps | Whichever the maintaining team controls | The method that the responsible team can change without filing tickets is the method that stays accurate |
A useful tiebreaker: ask who will fix it at 4pm on a Friday when a locale migration breaks reciprocity. If the answer is "the SEO team, via the sitemap pipeline," use the sitemap. If the answer is "whoever edits the theme," use HTML. Ownership beats elegance every time.
Rules that apply no matter which method you choose
Switching delivery mechanisms changes where the annotations live, not what they must say. These five rules are universal:
1. Self-referencing entry. Every page (or sitemap entry, or header) must include an hreflang annotation pointing to itself. In the Ahrefs dataset, 18% of sites were missing self-referencing hreflang, which can invalidate the whole cluster.
2. Return tags (reciprocity). Hreflang is a handshake. If page A lists page B as its German alternate, page B must list page A back, or Google ignores the relationship. Missing reciprocal tags affected 15.3% of studied sites. Our guide to return tags and x-default errors walks through finding and fixing broken handshakes at scale.
3. Absolute URLs. Alternates must be fully qualified, protocol included: https://example.com/foo, never /foo or //example.com/foo. Relative URLs are not valid hreflang targets in any of the three methods.
4. Canonical agreement. Hreflang must point at canonical, indexable, 200-status URLs. Pointing at redirected, noindexed, or non-canonical URLs (8% of sites in the study pointed at non-canonical URLs) sends Google contradictory instructions: hreflang says "index this version for this audience" while the canonical says "this is not the real page."
5. x-default. Declare a fallback for users who match none of your specified locales, typically your global homepage or language selector. A majority of sites skip this: 56.3% in the Ahrefs study lacked x-default annotations. It is technically optional and practically essential; see our check for missing x-default for how we flag it.
Common mistakes
Running a plugin and a sitemap generator in parallel. The most common path to dual implementation is accidental: an SEO plugin writes HTML tags while a separate sitemap tool independently emits xhtml:link entries. They agree on day one and drift apart by month three. Audit which systems on your stack emit hreflang and switch all but one off.
Forgetting the sitemap exists. Teams migrate URLs, update the HTML tags, and leave a stale sitemap declaring the old URLs for months. If you choose the sitemap method, wire its regeneration into your deployment process, not into someone's memory.
Header method without reciprocity. HTTP Link headers are easy to add for one file and easy to forget for its siblings. Every localized PDF in a cluster needs the full set in its own response headers.
Treating hreflang as set-and-forget. Whatever method you pick, recrawl your clusters after every locale launch, migration, or CMS change. Hreflang fails silently; nothing visibly breaks, your rankings just quietly mismatch their markets.
How to verify whichever method you picked
Verification differs slightly by method, so build the right check into your routine. For HTML link elements, crawl the site with any crawler that extracts hreflang and validates reciprocity; spot-check a few pages per locale with view-source to confirm the cluster is complete and self-referencing. For the sitemap method, validate the XML against the sitemap schema, confirm the xhtml namespace is declared, and diff the generated file after every locale change; Search Console's sitemap report will surface parse errors but not logical hreflang errors, so you still need a crawler that reads sitemap hreflang. For HTTP headers, browsers will not show you anything useful on the page itself; use curl -I against each file and inspect the Link header directly, and remember to test every sibling in the cluster, not just the one you changed.
Whatever the method, the test that matters most is the handshake test: pick any alternate URL your page declares, fetch that URL's own annotations from the same source, and confirm it points back. If you automate one thing, automate that.
FAQ
A: Google will parse both, but you should not. There is no ranking or indexing benefit to declaring hreflang twice, and Google's own documentation recommends picking the single most convenient method. The moment the two sources disagree, which they eventually will, you have conflicting hreflang signals, and Google responds to conflicts by ignoring the annotations. Choose one, remove the other, and recrawl to confirm only one source remains.
A: None. Google states the three methods are equivalent from its perspective. The preference question is really an operations question: sitemaps scale best for large sites, HTML link elements are simplest for small sites, and HTTP headers are required for non-HTML content like PDFs. Choose based on who maintains it and what content you serve.
A: No. For HTML pages, link elements or sitemap entries are easier to implement and audit. The HTTP Link header earns its keep for non-HTML files, where it is the only way to attach hreflang to the response itself. Using headers for pages and tags for the same pages would put you back in the two-methods trap.
🌍 The International SEO series
- Hreflang and International SEO: The Complete Implementation Guide
- Hreflang Best Practices: 7 Real-World Scenarios
- Localization vs Internationalization vs Translation vs Transcreation
- Hreflang Implementation Without the Errors: Return Tags and x-default
- Hreflang and International SEO FAQ
- Hreflang issue fix-guides (audit library)
Running a multi-language site?
SEO ProCheck audits international setups, hreflang included, end to end.
Claude Vincent is a technical SEO consultant focused on crawlability, rendering, and AI-search visibility. He writes the field guides and case studies at SEO ProCheck, with a bias toward the durable, unglamorous work that decides whether search engines and AI answer engines can actually read and cite a site.
About SEO ProCheck
Technical SEO consulting and GEO strategy with 20 years of enterprise experience. Case studies, resources, and tools for search and AI visibility.
Work With Me
Technical SEO audits, GEO strategy, site migrations, and international SEO. Hourly consulting for teams who need hands-on support, not just reports.
Subscribe to our newsletter!
