Guides

HTML head, HTTP header or sitemap: choosing one hreflang method

Google reads hreflang from three places: link elements in the HTML head, an HTTP Link header, and xhtml:link elements in an XML sitemap. All three carry the same information, and Google treats them as equal. Mixing methods adds a second source to keep in sync, and the two drift apart over time.

HTML head

The most common method, and the easiest to inspect. The full set sits on every page, so a large cluster adds weight to every response.

<link rel="alternate" hreflang="de" href="https://example.com/de/" />

HTTP Link header

The only option for PDFs and other non-HTML files, and the method next-intl uses by default. Headers are invisible in the page source, which makes mistakes harder to spot.

Link: <https://example.com/de/>; rel="alternate"; hreflang="de"

XML sitemap

Keeps markup out of the pages and suits large sites. Google picks up changes when it recrawls the sitemap. The sitemap needs the xhtml namespace declared on the urlset element.

<url>
  <loc>https://example.com/en/</loc>
  <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/"/>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/"/>
</url>