Hreflang Tags: Guide, Free Checker and Generator (Self-Referencing, x-default, Canonical, Sitemap)

Updated September 2026 · Written and maintained by the Progression Agency strategy team

Hreflang is the attribute that tells Google which language or country version of a page to show to which searcher. This guide covers what it does, the exact syntax for HTML, HTTP headers and XML sitemaps, the language and region codes, the self-referencing and return-link rules, x-default, how hreflang interacts with canonical tags, platform notes for WordPress, Shopify, Webflow and Next.js, and the errors that break it. A free checker and a tag generator are on the page.

What hreflang is and what it does

Hreflang is an attribute on a link element (or an equivalent HTTP header or sitemap entry) that declares the language, and optionally the region, of an alternate version of the current page. Google uses it to show the German version to searchers in Germany and the English version elsewhere, instead of choosing by guesswork. Google’s documentation on localized versions of a page is the source of every rule on this page. Hreflang does not translate, does not redirect and does not boost rankings; it is a cross-reference between pages that already exist.

Hreflang syntax and examples

Google accepts three methods. Use one consistently; mixing them on the same site makes debugging harder. HTML link elements in the head are the most common; HTTP headers are for non-HTML files such as PDFs; the XML sitemap method is the easiest to maintain at scale because the whole set is generated from data.

Language and region codes

The language is an ISO 639-1 two-letter code (en, de, fr, es, pt, ja, zh). The optional region is an ISO 3166-1 Alpha-2 country code (us, gb, de, ca, au, br) written after a hyphen. Region alone is not valid: hreflang=”gb” is an error, hreflang=”en-gb” is correct. The one common exception is a UN M.49 region code such as es-419 for Latin American Spanish. Codes are case-insensitive but conventionally lower-case language and upper-case region (en-GB); the checker on this page normalises case. The most frequent code mistakes are en-uk (the country code is gb), using a three-letter language code where the two-letter one exists, and inventing region codes (eu is not a valid region for Europe).

The self-referencing rule and return links

Each version must include a link to itself in its hreflang set, and every page named in the set must name this page back. Google ignores a hreflang set whose links are not reciprocated, which is why a site can have hreflang on every page and still show the wrong versions. The practical consequence is that hreflang cannot be maintained page by page: it has to be generated from a single source of truth (the CMS’s language relationships or a sitemap generator) so that adding a version updates every sibling. The checker on this page fetches the alternates and reports missing return links; a missing self-reference is the most common single finding.

x-default: what it is for

x-default marks the page to show when no listed language or region matches the searcher, typically the global English page or a language-selector page. It is not required, but without it Google picks a fallback itself. Use exactly one x-default per set, point it at a real page that returns 200, and do not point it at an IP-based redirect, which Googlebot (crawling from the US) cannot follow to other versions.

Hreflang and canonical tags

Hreflang and canonical must agree. Each version should be canonical to itself; the hreflang URLs must be the canonical URLs. A country page that canonicalises to the home-market page is telling Google to treat it as a duplicate, and Google then ignores its hreflang, which produces the classic symptom of the home version ranking everywhere. Google’s guidance on consolidating duplicate URLs explains why: canonical is a consolidation signal, hreflang is a targeting signal, and consolidation wins. The checker reports a canonical that points elsewhere as a finding.

Hreflang in the XML sitemap

In the sitemap method each URL entry lists every alternate, including itself, as an xhtml:link element, and the urlset declares the xhtml namespace. The set must be repeated under each version’s own entry, which is why generating the sitemap from data is the sane approach for sites with more than a handful of pages. Google’s sitemap documentation covers the format; the generator above produces one entry’s block. Keep lastmod accurate or omit it; a lastmod that changes on every build teaches Google to ignore it.

Hreflang on WordPress, Shopify, Webflow and Next.js

On WordPress, multilingual plugins such as WPML and Polylang emit hreflang for the language relationships you define; the errors we see are pages left untranslated but still published, and x-default missing because the setting was never enabled. Shopify emits hreflang automatically for markets configured under Shopify Markets, whether on subfolders or separate domains; problems come from custom domains that were not linked as markets. Webflow’s Localization feature emits hreflang for locales you publish; check that each locale’s pages are actually published, not only created. In Next.js, the metadata API’s alternates.languages field generates the link elements per route; the frequent mistake is a static set that omits the current route’s own URL. Whatever the platform, run the checker after each change rather than trusting the setting.

Common hreflang mistakes and how to fix them

How to check hreflang

For one page, use the checker at the top of this page: it reads the HTML link elements, validates codes, tests self-reference, x-default and canonical, and fetches alternates to confirm return links. For a whole site, crawl it with a desktop crawler that reports hreflang (Screaming Frog’s hreflang report is the standard) and cross-check the sitemap. Search Console’s international targeting report was retired, so the crawl and the checker are the verification. Re-check after every deployment that touches templates or language settings.

When you do not need hreflang

A site in one language for one country does not need hreflang, and adding it does nothing. A site in one language sold in several countries with identical pages does not need it either unless the pages differ (prices, spellings, contact details); if they differ, it does. If you are deciding whether to create country versions at all, that is an international SEO question rather than a hreflang one, and it comes first.

Getting hreflang fixed

Progression Agency fixes hreflang as a scoped, fixed-price job and runs international SEO for sites that serve several countries, from New York City for clients across the United States and worldwide. Run the checker, send us the findings, and you get a written scope.

Frequently asked questions