We use cookies to improve your experience, analyze site traffic, and personalize content. You can accept all cookies or choose which categories to allow. Learn more
Hreflang for Multi-Region Stores: A 2026 Implementation Guide | Ordiko
Guide
Hreflang for Multi-Region Stores: A 2026 Implementation Guide
Detailed implementation guide for hreflang on multi-region ecommerce: cluster correctness, x-default, per-entity gating, sitemap vs. HTML approaches, validation, and common pitfalls.
PT1H
TL;DR. Hreflang tells search engines which locale variant to serve to each user. Get four things right: (1) complete reciprocal clusters with self-references, (2) correct ISO language codes, (3) x-default fallback, (4) per-entity gating so you don't advertise non-existent translations. Anything else is implementation detail.
What hreflang does
Hreflang is an HTML attribute (and equivalent sitemap annotation) that signals to Google which language and region a page targets. Properly implemented hreflang:
Serves Spanish users your Spanish URL, not your English one.
Prevents your French URL from outranking your German URL in Germany.
Consolidates link equity across locale variants instead of treating them as duplicate content.
Hreflang does not boost rankings. It controls which locale variant ranks where.
Step 1: Decide where to emit hreflang
Three options:
Method
Pros
Cons
HTML head
Easy to debug; one source per page
Adds bytes to every HTML response
HTTP Link header
FAQ
HTML head or sitemap — which is better?
HTML head is easier to debug because you can verify with View Source. Sitemap is more compact for stores with 50k+ URLs because hreflang is emitted once per URL pair, not in every page's head. Pick HTML for stores under 50k URLs; sitemap above that. Ordiko emits HTML head by default.
What language code do I use for Latin American Spanish vs Spain Spanish?
es-MX for Mexico, es-AR for Argentina, es-CO for Colombia, es-ES for Spain. The language-region combination is supported. For a single Latin American locale serving multiple countries, es-419 (the UN code for Latin America and Caribbean) is valid but less widely supported.
Can I have multiple x-default URLs?
No. One x-default per cluster. If your business serves English globally, the .com (or your default-locale URL) is the x-default. The same URL can be both hreflang='en' and hreflang='x-default'.
How does Ordiko handle hreflang correctness?
Ordiko's storefront SEO library (src/lib/seo/storefront.ts) intersects each entity's availableLocales with the store's supported locales when emitting alternates.languages. A product translated only to en + de will only advertise those two locales, regardless of the store's wider locale set.
Related reading
Works for non-HTML resources (PDFs, etc.)
Hard to debug; rarely needed
XML sitemap
Most compact for huge catalogs
Less visible to humans; needs sitemap discipline
The 2026 default for most ecommerce sites is HTML head. Switch to sitemap-only above 50,000 URLs.
Step 2: Emit a complete cluster
For every translated URL, output hreflang for itself and every other variant.
A 4-locale cluster (en, de, fr, es) for a product:
This cluster appears in the head of every locale variant of this product. The German URL emits the same cluster, the French URL emits the same cluster, etc.
The cluster must be reciprocal — A points to B, B points to A. Non-reciprocal clusters get silently ignored by Google.
Step 3: x-default
x-default is the fallback for users whose browser language doesn't match any of your variants. Typically your English (or default-locale) URL.
The same URL can be both hreflang="en" and hreflang="x-default". Only one URL in the cluster gets x-default.
Step 4: Filter to actually-translated entities
The biggest practical mistake: emitting a 9-locale cluster on a product that's only translated to 3 locales. The advertised URLs return 404; Google sees the broken cluster and may ignore the entire site's hreflang.
Single-page apps: emit hreflang server-side in the document head. Don't rely on client-side injection — Google's crawler may not execute your JS.
ccTLDs: hreflang still applies. example.de can specify hreflang="de-DE" for itself and link to example.com/en/... for en.
Region without language difference: if you serve en-US and en-GB with identical content, hreflang differentiates them. Don't share the URL — give each its own URL even if content is identical.
Common pitfalls
Mistake
Effect
Non-reciprocal cluster
Google ignores hreflang entirely
Variant URL returns 404
Google ignores the URL; may demote cluster
Wrong language code
Variant treated as untargeted
Multiple x-default URLs
One is ignored arbitrarily
Hreflang only on canonical URL
Sub-pages have no hreflang signal
Mixing absolute and relative URLs
Use absolute URLs always
Different domain per locale without consistent hreflang
Cluster breaks
How Ordiko emits hreflang
src/lib/seo/storefront.ts computes alternates.languages for every Next.js page metadata object. The function takes:
store.supportedLocales
entity.availableLocales (optional, defaults to store.supportedLocales)
store.defaultLocale (used for x-default)
And emits the intersection cluster in HTML head. Self-reference, reciprocity, and x-default are guaranteed by the implementation. Per-entity gating is opt-in via the availableLocales field on the entity loader.
FAQ
HTML head or sitemap — which is better? HTML head is easier to debug because you can verify with View Source. Sitemap is more compact for stores with 50k+ URLs because hreflang is emitted once per URL pair, not in every page's head. Pick HTML for stores under 50k URLs; sitemap above that. Ordiko emits HTML head by default.
What language code do I use for Latin American Spanish vs Spain Spanish? es-MX for Mexico, es-AR for Argentina, es-CO for Colombia, es-ES for Spain. The language-region combination is supported. For a single Latin American locale serving multiple countries, es-419 (the UN code for Latin America and Caribbean) is valid but less widely supported.
Can I have multiple x-default URLs? No. One x-default per cluster. If your business serves English globally, the .com (or your default-locale URL) is the x-default. The same URL can be both hreflang='en' and hreflang='x-default'.
How does Ordiko handle hreflang correctness? Ordiko's storefront SEO library (src/lib/seo/storefront.ts) intersects each entity's availableLocales with the store's supported locales when emitting alternates.languages. A product translated only to en + de will only advertise those two locales, regardless of the store's wider locale set.