SEO Tools·4 min read

Hreflang Explained: Pairs, Return Tags, and x-default

Get hreflang explained properly before you launch a second language, because it's the markup SEOs get wrong more than any other. The idea is simple: annotations that tell Google which URL serves which language and region, so a searcher in Madrid gets your Spanish page instead of the English one. The execution is where sites stumble, since every annotation must exist in pairs that point at each other. One missing return tag and Google may ignore the relationship. This guide covers the codes, a worked set with x-default, and the errors that break the arrangement.

Open the free Hreflang Tag Generator All insights

One catalog, three markets: the job hreflang was built for

Same content, different audiences.

A SaaS company runs example.com in English, example.com/es/ in Spanish and example.com/fr/ in French. Without annotations, Google treats these as three loosely related sets of pages. Spanish users sometimes land on English pages, and the French pricing page competes with the English one in Canadian results. Nobody is penalized; users are just routed badly, and conversion rates show it.

Hreflang fixes the routing. Each page announces its own language and lists its siblings, so the search engine can show the right version to each searcher. It matters just as much when the language is the same but the market isn't: en-GB and en-US pages showing different currencies would otherwise look like duplicates competing for the same searches.

Hreflang explained at the tag level

Codes first, everything follows.

Each annotation is a link element: rel="alternate", an hreflang attribute holding the code, and an href holding the URL. The code is an ISO 639-1 language, optionally followed by a hyphen and an ISO 3166-1 country: es is Spanish anywhere, es-MX is Spanish for Mexico. A country alone is invalid, and the classic trap is en-UK, which means nothing; the United Kingdom's code is GB.

The rule that governs everything else: the complete set of annotations must appear on every page in the group, including a reference to the page itself. Hreflang is reciprocal by design, which is what stops another site from claiming to be the French version of yours.

A worked hreflang set with x-default, four lines total

Copy the shape, swap the URLs.

In the Hreflang Tag Generator, the sample rows produce exactly this block: <link rel="alternate" hreflang="en" href="https://example.com/" />, then <link rel="alternate" hreflang="es" href="https://example.com/es/" />, then <link rel="alternate" hreflang="fr" href="https://example.com/fr/" />, and finally <link rel="alternate" hreflang="x-default" href="https://example.com/" />.

These four lines go into the head of all three pages, unchanged. The English homepage carries the block, and so do /es/ and /fr/, each one listing itself and its siblings. That sameness is the point: paste one block everywhere in the group and the return tag requirement is met automatically. Add a market with + Add language, say en-GB pointing at https://example.com/uk/, and the new five-line block replaces the old one on every page at once.

X-default: the row for everyone else

Your international fallback.

The x-default value isn't a language. It marks the URL to show when no listed language matches the searcher, such as a visitor from Japan in the example above. You'll usually point it at your global homepage or a language picker. It can share an href with a real language row, as it does with en in the sample set; that's normal and correct.

Skipping x-default doesn't invalidate the rest, but it leaves unmatched visitors to Google's guesswork. Google recommends it, and the generator shows a warning when the set has no x-default row.

The code errors the generator catches as you type

Small typos that drop a version silently.

Google ignores an annotation it can't read, so one bad code can quietly drop a version from the set with no error on the page. The generator checks every row as you edit and lists the problems under the table.

Invalid country codes like en-UK, with the fix suggested: en-GB.
A country code used as a language, such as jp where Japanese is ja.
Underscores instead of hyphens, like en_US.
Numeric regions such as es-419, which Google doesn't accept; list each country instead.
Relative URLs like /es/, duplicate codes, and two language codes sharing one URL.

Return tag errors and the other pair breakers

How annotation sets fall apart on the live site.

The builder checks the codes and URLs you type. Whether each version on the live site really lists the others is a separate question, which the Check a live page tab answers by opening the alternates. That's where return tag errors come from: page A lists page B, page B forgets to list page A, and Google may drop the link between them. The recurring causes:

A new language shipped with its own annotations while the existing pages' blocks were never updated to include it.
URLs in annotations that redirect or differ from the page's canonical, so the pairing never resolves.
Templates that output annotations on the English site but not on the translated ones.
One version edited by hand while the others kept the old block.

Keeping a growing hreflang set maintainable

Two locales are easy. Twelve aren't.

First tip: generate the full block once per page group and paste it everywhere unchanged, rather than letting each page build its own list. Identical blocks can't disagree, and disagreement is the root of return tag errors. The HTML output option is labeled head of every version for exactly this reason.

Second, re-check after every locale launch, because that's the moment existing pages fall out of sync. Third, once you pass roughly a dozen locales, consider moving annotations into your XML sitemap, where one file defines every pairing instead of hundreds of templates. The generator's XML sitemap output writes that file from the same rows, or from a CSV with one row per page set.

The Hreflang Tag Generator next to the rest of the international kit

Which tool for which half.

The Hreflang Tag Generator handles language targeting; it doesn't decide which URL variant of each page is the real one. That's canonical territory, so pair it with the Canonical Tag Generator and make sure every hreflang href matches that page's canonical exactly, since mismatches there are a common reason annotations get ignored. If you move annotations into a sitemap later, the XML Sitemap Generator builds the URL list. The Meta Tag Analyzer confirms each language version has its canonical and html lang attribute in place.

Try it now

Open Hreflang Tag Generator

The tool is one click away. No sign up, no upload, no payment.

Open Hreflang Tag Generator

Write a review