Hreflang Examples: Tag Sets for Spanish, Regions, and Scripts

Q: How do I write hreflang for Spanish in Spain and Mexico?

Use hreflang="es-ES" for the Spain page and hreflang="es-MX" for the Mexico page, with both tags appearing on both pages. If you also have a page aimed at Spanish speakers outside those two countries, add a third tag with plain hreflang="es" as the catch-all; avoid es-419 and es-LA, since neither is a code Google's hreflang implementation actually supports.

Q: How do I target a script like Traditional Chinese?

Add the ISO 15924 script code after the language: hreflang="zh-Hant" for Traditional Chinese generally, or hreflang="zh-Hant-TW" if you're targeting Taiwan specifically. Simplified Chinese follows the same pattern with Hans instead of Hant. If you give a region without a script, such as zh-TW, Google infers the correct script from the region on its own.

If you searched for hreflang examples, you've probably already read a handful of pages that explain what the attribute does and never actually show you the tags for your situation. That's the gap this article closes. Below you'll find complete, working hreflang example code for the language and country combinations that small sites actually run: Spanish for Spain and Mexico, one Spanish page for everyone else, English across three markets, Chinese split by script, and a few more. Find the one that matches your site, swap in your own URLs, and you're done.

One quick definition first, since I never assume you've already met the jargon. Hreflang is an HTML attribute (and a matching sitemap element) that tells search engines "this page and that page are different language or regional versions of the same content." Get it right and Google can show a Portuguese visitor your Portuguese page instead of your English one. Get it wrong and it quietly does nothing, which is the annoying part: there's no error message on the page itself, just a search result that never improves.

You don't need any special software for this. You need access to edit the <head> section of your pages, or your sitemap file if that's where your tags live, and a clear idea of which languages and countries your site actually serves. If you want the full rule set behind hreflang, meaning when to use it and why search engines rely on it, the hreflang explainer covers that in depth. This article sticks to worked examples.

Hreflang Example Code for Common Language Setups

How to read a hreflang code (language, script, region)

Every hreflang value follows the same shape: language, optionally a script, optionally a region, separated by hyphens rather than underscores. Written out, that's language[-Script][-REGION]. Take zh-Hant-TW apart and you get three pieces: zh is the language (Chinese), Hant is the script (Traditional Han characters), and TW is the region (Taiwan).

Each piece comes from its own official list. Languages come from ISO 639-1, scripts come from ISO 15924, and regions come from ISO 3166-1 alpha-2 country codes. Once you understand how hreflang language codes get built from those three registries, every example in this article is just a variation on the same pattern: pick a language, add a script if the language is written more than one way, add a region if you're targeting a specific country.

Casing is a convention, not a rule Google enforces: language lowercase, script capitalized, region uppercase, like es-ES. Google's own documentation even shows a lowercase example (de-ch) in one place, so mixed casing won't break your tags. It will, however, get flagged as inconsistent by most checkers, hreflang.tools included, under a code called code_case, so keep it tidy anyway. Underscores instead of hyphens (zh_CN) and made-up two-letter codes both fall into a separate bucket called bad_code, which is a hard failure, not a style note.

Spanish for Spain and Mexico

This is the most common real-world Spanish setup: a shop with one page written for Spain and one written for Mexico, nothing else yet. The same block of tags goes on both pages.

<link rel="alternate" hreflang="es-ES" href="https://example.com/es/" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/es-mx/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/es/" />

Here's what each line is doing. The first tag points to the Spain page, including on the Spain page itself, because Google's documentation is explicit that each language version must list itself as well as every other version. The second points to the Mexico page the same way. The third is the x-default fallback, the page Google shows a visitor whose language and region don't match either option; I've picked the Spain page here, but which page deserves that job is genuinely a judgment call, and the x-default guide walks through how to decide.

Spanish for Spain, Mexico, and everyone else

Add a third audience, "Spanish speakers anywhere else," and this is where most html hreflang Spanish guides quietly get it wrong. The instinct is to reach for es-419, a real code in the wider internet standard, reserved for Latin American Spanish under the United Nations' M.49 numbering system. It looks official, and it shows up on Android developer docs and Google Play pages.

And Google's own hreflang documentation excludes it by name: "Only language codes listed in ISO 639-1 and region codes listed in ISO 3166-1 Alpha 2 are supported; other codes that aren't listed in those standards, such as es-419, aren't supported." That's about as direct as an official source gets.

The second wrong guess is es-LA, which looks like shorthand for "Latin America" but isn't. LA is the ISO 3166-1 code for Laos, so es-LA technically means Spanish for Laos, a page you almost certainly don't have.

What actually works is a plain language code with no region attached, used as the catch-all:

<link rel="alternate" hreflang="es-ES" href="https://example.com/es/" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/es-mx/" />
<link rel="alternate" hreflang="es" href="https://example.com/es-latam/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/es-latam/" />

Plain es means "Spanish, no specific country," which is precisely the catch-all you're after. It's valid, it's supported, and every one of these four pages carries all four tags, itself included. If someone pushes back that "Google uses es-419 on its own sites, so it must be fine," that's true and also beside the point: Google's technical documentation is not a description of Google's marketing pages, and following what a large company does on android.com tells you nothing about what its own search documentation asks smaller sites to do.

One country, two languages: US Spanish and US English

Sometimes the split isn't Spain versus Mexico, it's two languages inside the same country. The United States is the clearest case: Spanish was the most common non-English language spoken in US homes, accounting for 62 percent of non-English speakers as of 2019, according to the US Census Bureau, which is a real reason to run a dedicated US Spanish page rather than folding those visitors into a generic Spanish one.

<link rel="alternate" hreflang="en-US" href="https://example.com/" />
<link rel="alternate" hreflang="es-US" href="https://example.com/es-us/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Notice the region stays the same (US) while the language changes. That's allowed and it's exactly what hreflang is for: matching content to a language and region pair, not just a country.

English for the US, UK, and Australia

Hreflang wasn't originally built for translated content at all. When Google introduced the attribute back in December 2011, its own example was three English pages for Australia, Canada, and the United States that differed only in price. Same words, different currency and shipping, still worth telling Google apart. A US, UK, and Australia version works the same way:

<link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
<link rel="alternate" hreflang="en-AU" href="https://example.com/au/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/us/" />

Two traps hide in this set. First, the United Kingdom's country code is GB, not UK; "UK" is reserved and never assigned as an ISO 3166-1 country code, so en-UK fails validation outright. Second, if you drop the language entirely and just write uk on its own hoping it means "United Kingdom," you've actually written the language code for Ukrainian. Neither typo throws a visible error on your page; a checker is the only way to catch them before Google does.

If your tags live in an XML sitemap instead of the page's <head>, the same three-way set looks like this, with every URL still listing all three versions of itself:

<url>
  <loc>https://example.com/us/</loc>
  <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
  <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
  <xhtml:link rel="alternate" hreflang="en-AU" href="https://example.com/au/" />
</url>

That block needs the xmlns:xhtml="http://www.w3.org/1999/xhtml" namespace declared on the sitemap's opening <urlset> tag or none of the xhtml:link lines will parse. If sitemap syntax is new territory for you, our sister site's explainer on what an XML sitemap is covers the basics before you add hreflang lines to it.

Traditional and Simplified Chinese by script

Chinese is where the optional script piece of the code earns its place. Traditional and Simplified are different writing systems for the same language, so hreflang uses ISO 15924 script codes to tell them apart: Hant for Traditional, Hans for Simplified.

<link rel="alternate" hreflang="zh-Hant" href="https://example.com/zh-hant/" />
<link rel="alternate" hreflang="zh-Hans" href="https://example.com/zh-hans/" />

Add a region if you're targeting a specific place rather than a script generally, say Taiwan and Hong Kong for Traditional, mainland China for Simplified:

<link rel="alternate" hreflang="zh-Hant-TW" href="https://example.com/zh-tw/" />
<link rel="alternate" hreflang="zh-Hant-HK" href="https://example.com/zh-hk/" />
<link rel="alternate" hreflang="zh-Hans-CN" href="https://example.com/zh-cn/" />

Worth knowing: if you give a region without a script, Google derives the script for you. zh-TW alone is read as Traditional Chinese automatically, because that's the script Taiwan actually uses. But don't shorten it further to just tw on its own; that's not a region code doing the work of a language, it's the ISO 639-1 code for Twi, a language spoken in Ghana, and it will not mean what you think it means to anyone parsing it correctly.

One language, two scripts: Serbian Latin and Cyrillic

Chinese isn't the only language split across writing systems. Serbian is commonly written in both Latin and Cyrillic script depending on the region and the publication, so the same pattern applies:

<link rel="alternate" hreflang="sr-Latn" href="https://example.com/sr-latn/" />
<link rel="alternate" hreflang="sr-Cyrl" href="https://example.com/sr-cyrl/" />

Uzbek works the same way with uz-Latn and uz-Cyrl. The rule generalizes: whenever a language has more than one script in genuine everyday use, add the script code, don't try to fake the distinction with the language code alone.

Portuguese for Brazil and Portugal

Brazilian and European Portuguese differ enough in vocabulary and spelling that most sites split them, and the set is refreshingly simple:

<link rel="alternate" hreflang="pt-BR" href="https://example.com/pt-br/" />
<link rel="alternate" hreflang="pt-PT" href="https://example.com/pt-pt/" />

Resist the urge to shorten "Brazil" to just br on its own without the language in front of it. On its own, br is the language code for Breton, a Celtic language spoken in parts of France, not a stand-in for Brazil. It's a small typo with a genuinely strange result, and it's one of the more common entries on any list of hreflang mistakes worth reading if you want the full catalogue.

Can you target a region without a language?

No, and this trips up more beginners than any other rule here. Google's documentation states it plainly: "You can't specify the country code by itself," and Google "doesn't automatically derive the language from a country code." A region code always needs a language in front of it.

The frustrating part is that writing a country code alone doesn't fail loudly. It just gets read as something else entirely, because two-letter country codes and two-letter language codes overlap by coincidence. Write be hoping for Belgium and you've written Belarusian.

Write se hoping for Sweden and you've written Northern Sami. Write uk hoping for the United Kingdom and you've written Ukrainian.

None of these throw a visible error; they just quietly point search engines at the wrong audience for months.

Checking your own hreflang example code

Once you've built a set from the examples above, verify it before you trust it. Here's how:

Paste your page URLs (or your sitemap URL) into the checker at hreflang.tools. You should land on a report page listing each URL with its hreflang tags and a pass or fail state per tag. If the page just sits there loading, double check the URLs are publicly reachable and not blocked behind a login.
Look for bad_code in the results. This means a tag uses a code that doesn't exist in any of the three registries, like an underscore where a hyphen belongs. If you see it, compare the flagged value against the format section above and fix the punctuation or spelling.
Look for suspect_code. This is a warning, not a hard failure: it means the tag is a real, valid code, just one that's almost always a mistake, like br or uk used alone. If you see it and you genuinely meant Breton or Ukrainian, ignore it; otherwise, add the language you actually meant.
Look for duplicate_lang or cluster_incomplete. The first means the same code appears twice on one page; the second means one page in your set doesn't list all the others. Either one means going back to your tag block and making sure every page mentions every page, itself included.

Frequently Asked Questions

What does a complete hreflang set look like?

A complete set is reciprocal: every page in the group lists every other page's hreflang tag, including a tag pointing back to itself. If your site has a Spain page and a Mexico page, both pages carry both tags, not just one pointing outward. Miss the self-reference or leave one page off another's list and the set is incomplete, which is exactly what the cluster_incomplete and no_self_reference flags in a checker report are telling you.

How do I write hreflang for Spanish in Spain and Mexico?

Use hreflang="es-ES" for the Spain page and hreflang="es-MX" for the Mexico page, with both tags appearing on both pages. If you also have a page aimed at Spanish speakers outside those two countries, add a third tag with plain hreflang="es" as the catch-all; avoid es-419 and es-LA, since neither is a code Google's hreflang implementation actually supports.

How do I target a script like Traditional Chinese?

Add the ISO 15924 script code after the language: hreflang="zh-Hant" for Traditional Chinese generally, or hreflang="zh-Hant-TW" if you're targeting Taiwan specifically. Simplified Chinese follows the same pattern with Hans instead of Hant. If you give a region without a script, such as zh-TW, Google infers the correct script from the region on its own.

Can I use hreflang for a region without a language?

No. Every hreflang value needs a language code; a country or region code can never stand alone. Trying to shortcut it, writing just br for Brazil or uk for the United Kingdom, doesn't produce an error message, it silently resolves to a different real language (Breton and Ukrainian, respectively) that almost certainly isn't the one you meant.