← Other blogs

Hreflang examples for HTML, HTTP headers and sitemaps

Copyable patterns for each method Google accepts, the codes that look right but are not, and a way to test the result.

By ClaudeGPT Si Newsroom · Editorial team

· 3 min read

Here are working hreflang examples for all three methods Google accepts: link tags in the HTML head, an HTTP Link header, and an XML sitemap. Pick one method per site, copy the pattern below, and test a live page with the seogeoaeo.ai Hreflang Checker before you call it done.

A travel blog publishes each post in English, French and Canadian French. Every version carries the same block in its head:

<head>
  <link rel="alternate" hreflang="en" href="https://blog.example.org/en/lisbon/" />
  <link rel="alternate" hreflang="fr" href="https://blog.example.org/fr/lisbonne/" />
  <link rel="alternate" hreflang="fr-CA" href="https://blog.example.org/ca/lisbonne/" />
  <link rel="alternate" hreflang="x-default" href="https://blog.example.org/en/lisbon/" />
</head>

Three things to notice. Each page lists itself as well as the others. Every href is a full URL with https. And the slug can differ per language; hreflang maps the pages, not the paths.

The x-default line here points at the English post, which is a fair choice when there is no language picker. Readers in Quebec searching in French get the fr-CA page, readers in Belgium searching in French get the generic fr page, and everyone else gets English. Google also says the folder names (en, fr, ca) mean nothing to it on their own; only the hreflang values set the audience.

If you add a Portuguese version next month, all four existing pages need a new line too. That is the step teams forget most often.

Headers are the way to annotate files that have no HTML head, such as a PDF. A price list in English and German would be served with this header on both files:

Link: <https://files.example.org/prices-en.pdf>; rel="alternate"; hreflang="en",
      <https://files.example.org/prices-de.pdf>; rel="alternate"; hreflang="de"

The URL sits inside angle brackets, entries are separated by commas, and the header is identical on every version.

Example 3: XML sitemap

In a sitemap, each URL gets its own entry, and each entry repeats the full list of alternates as xhtml:link children. Declare the xhtml namespace on the urlset first:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://shop.example.org/it/borsa/</loc>
    <xhtml:link rel="alternate" hreflang="it" href="https://shop.example.org/it/borsa/"/>
    <xhtml:link rel="alternate" hreflang="pt-BR" href="https://shop.example.org/br/bolsa/"/>
  </url>
  <url>
    <loc>https://shop.example.org/br/bolsa/</loc>
    <xhtml:link rel="alternate" hreflang="it" href="https://shop.example.org/it/borsa/"/>
    <xhtml:link rel="alternate" hreflang="pt-BR" href="https://shop.example.org/br/bolsa/"/>
  </url>
</urlset>

Two versions means two url entries with two identical children each. Google notes the child links don't count toward the sitemap URL limit.

Which method to pick

Method Best for Watch out for
HTML link tags Most websites Tags outside a valid head are missed
HTTP header PDFs and other non-HTML files Header must list every version, itself included
XML sitemap Large sites with many languages Each entry repeats the whole set

Google treats the three as equal. Using more than one adds no benefit and gives you more places for the lists to drift apart.

Codes that look right but are wrong

  • en-UK: UK is a reserved code that Google ignores. Use en-GB.
  • be for Belgium: "be" is the Belarusian language. Use nl-BE, fr-BE or de-BE.
  • es-419: Latin American Spanish as a region number is not supported by Google.
  • zh-Hant: valid. Scripts can be set with ISO 15924 codes.

Test the example on your own page

Copying a pattern is the easy part. Keeping every version in step is where sites slip. Run one URL from the set through seogeoaeo.ai's checker and it validates the codes, looks for a self-reference and an x-default, then loads each alternate to confirm it is indexable and links back. A run costs 10 credits.

One limit to know: the tool reads the hreflang annotations on the page and does not parse sitemaps, so for Example 3 you would check the sitemap with a crawler or a sitemap-specific tool.