How to Do International SEO with Hreflang

Hreflang works pair by pair. Google’s documentation on localized versions of a page says that if two pages don’t both point to each other, the tags will be ignored, and that Google will still process the ones that do point to each other. A broken return tag costs you that pair, not the whole set. That makes hreflang more forgiving than its reputation and harder to debug, because a cluster can be half-working without an obvious error.

What hreflang does, and what it doesn’t

Hreflang tells Google which language or regional version of a page to show a given searcher. It does not translate anything, and Google does not use it to work out a page’s language: Google says it doesn’t use hreflang or the HTML lang attribute to detect language, and uses algorithms instead. Google’s localized-versions documentation doesn’t present it as a ranking factor, and annotations don’t make an uncompetitive page competitive in a new market. If a perfectly annotated French page doesn’t rank in France, look at the page and its competition, not the tags.

The codes

An hreflang value is a language code, optionally followed by a region code. Google supports only language codes from ISO 639-1 (de, fr, ja) and region codes from ISO 3166-1 Alpha 2 (gb, mx, ch). Codes outside those standards, such as es-419 for Latin America, are not supported. A region code alone is not valid.

Two details from Google’s list of common mistakes:

• Reserved region codes. The ISO code for the United Kingdom is GB. Google says that if you use codes reserved for something else, such as EU, UN or UK, Google Search ignores that part of the annotation. en-uk does not do what its author intended.
• Language only, or language and region. Use a language code alone when one version serves every speaker of that language. Add a region only when the versions differ by market: price, currency, spelling, stock or legal terms. Identical en-gb, en-au and en-ca pages give each market nothing different, only three versions to maintain.

Pick one granularity per language and use it everywhere. If one template emits fr and another emits fr-FR for the same content, the references no longer match, and the pairs break at the seam.

The rules every cluster follows

Google’s guidelines for all three methods come down to five rules:

1. Every version lists itself and every other version. A page that leaves itself out of its own set leaves the cluster incomplete.
2. Every reference is returned. If page X links to page Y, page Y must link back to page X. Where that fails, Google says, the annotations may be ignored or not interpreted correctly.
3. URLs are fully qualified, including the protocol. Google’s guide to consolidating duplicate URLs adds that the HTTPS version belongs in hreflang annotations, not the HTTP one.
4. x-default names the fallback for users whose language settings match none of your versions. Google says it can be used for any page but was designed for language selector pages, and works best with those.
5. Hreflang stays in its own link element. Don’t combine it with other attributes, such as media, in a single <link> tag.

Google also allows a practical shortcut. If a complete set of bidirectional links for every language becomes hard to maintain, you can omit some languages on some pages. Google will still process the pairs that point to each other.

Canonicals and hreflang

A canonical that points away from a localized page contradicts the hreflang that calls it a distinct version. Google’s consolidation guide gives the rule: when you use hreflang, specify a canonical page in the same language, or the best possible substitute language if a canonical page doesn’t exist for the same language. For a localized page that exists in its own language, that means a canonical to itself. The same guide notes that for canonicalization, Google prefers URLs that are part of hreflang clusters.

Choose a method by what you can maintain

Google names three ways to annotate alternates: HTML <link> elements in the head, HTTP headers, and the XML sitemap. It says the three are equivalent from its perspective, so choose the one your team can keep correct.

• HTML head elements are the simplest to read for a small set. At scale they are a maintenance load, because every new locale means editing the head of every page in every cluster.
• Sitemap annotations put the whole map in one generated file. On a large site, that makes them easier to keep consistent.
• HTTP headers cover files without a head, such as PDFs.

A root cause of large-scale breakage: fragmented templates

Breakage at scale can come later than the first tag, when separate teams maintain separate country templates. The German site sits on one template, the French site on another, the Japanese site on a third, and each team keeps its own copy of the list of alternates. A team adds a market and forgets the others’ return tags. A team changes its URL structure, and the alternates elsewhere now point at redirects.

The structural fix is a single source of truth. Generate the annotations from one shared component that every locale renders the same way, or move them out of the page head into a sitemap generated from one data source. Either way, no person should be reconciling pairs across teams by hand.

Declare only the versions that exist

A partially translated site invites a quiet mistake: declaring alternates that don’t exist. If the French version of a page is missing, or is a thin stub that falls back to English, don’t list it. An alternate that returns a 404 or redirects breaks the pair at that link. Scope the annotations to versions that exist and serve translated content.

A page that serves a single market and has no alternates needs no hreflang at all.

Debug in this order

The International Targeting report in Search Console is deprecated, and Google says country targeting through Search Console is no longer supported. Search Console no longer lists hreflang errors site-wide, so debugging combines single-page checks with a crawl.

1. Read one affected page’s annotations as served: in the HTML, the response headers or the sitemap entry. Confirm the page lists itself, every alternate and x-default, with valid codes and fully qualified HTTPS URLs.
2. Walk to each alternate and confirm it points back. A single page cannot show a missing return tag; only the page on the other side of the pair can.
3. Crawl the whole site with a tool that parses hreflang and reports pairs that aren’t returned, missing self-references, invalid codes and alternates that don’t return a 200. Google’s documentation points to third-party tools for debugging hreflang and notes that Google does not maintain or check them.
4. Standardize URL forms. Protocol, host and trailing slash have to match exactly across every annotation.
5. Check canonicals on the affected pages against the same-language rule.
6. Re-run the crawl on a schedule. Pairs can break as the site changes, and a one-time check does not catch the next break.

For a single URL, the URL Inspection tool shows the HTML Google fetched, which tells you whether the annotations you expect are in the page Google sees.

Frequently asked questions

Does one missing return tag break my whole hreflang set?

No. Google says that if two pages don’t both point to each other, those tags are ignored, and it still processes the pairs that do. The loss is the unreturned pair, which is why a crawl that checks every pair matters.

Is en-uk a valid hreflang code?

No. The ISO 3166-1 code for the United Kingdom is GB, so the value is en-gb. Google says that when a code reserved for something else is used, such as UK, it ignores that part of the annotation.

Should every page use language and region codes?

Only where versions differ by market. One English page for all English speakers should use en. Add region codes when prices, spelling, stock or legal terms differ between versions.

Which implementation method is best?

Google says HTML, HTTP headers and sitemaps are equivalent from its perspective. Pick the one your team can keep complete. On a large site, a sitemap generated from a single source of data is the easier one to maintain.