Skip to content

Misc

Hreflang on Shopify: what the theme does and what you fill in

Published

What hreflang does on a Shopify store

Hreflang tags tell Google and Bing which URL serves which language and region. On a multi-region or multilingual Shopify store, hreflang prevents duplicate-content issues (the English and German PDPs aren't the same page; they're alternates) and routes search-result clicks to the user's correct locale. Shopify's dev docs document hreflang as one of three SEO theme topics. On stores using Shopify Markets, Shopify adds the tags automatically through the theme's content_for_header output; the theme itself doesn't need hreflang code.

Shopify's dev docs SEO overview1 lists 'Hreflang Tags' as one of three documented theme SEO topics (alongside SEO Metadata and Robots.txt Customization). The hreflang page in those docs is specific: "Shopify adds hreflang tags to your theme automatically through the content_for_header object, which your theme renders in the <head> of layout/theme.liquid"5. Shopify reads the store's Markets and languages configuration and outputs the <link rel="alternate" hreflang="..."> tags; the theme only has to render content_for_header, which every theme does.

What the theme does for you automatically

Shopify itself adds the hreflang tags, through the content_for_header object that every theme renders in the head of layout/theme.liquid, based on the store's Markets configuration. For each page it outputs one <link rel='alternate' hreflang='...' href='...alternate URL...'> tag per market and language that has its own domain, subdomain, or subfolder, including one for the current page, plus an x-default tag pointing at the primary domain. A country-specific market gets a region-qualified code like en-ca; a broader market gets a language-only code like fr. You don't write any code — you configure Markets, and Shopify handles the rest. The setting is Automatic hreflang tags in Online Store > Preferences, on by default.

html Auto-emitted hreflang tags in head, multi-market store 
<link rel="alternate" hreflang="en" href="https://yourbrand.com/products/handle" />
<link rel="alternate" hreflang="de-de" href="https://yourbrand.de/products/handle" />
<link rel="alternate" hreflang="fr-fr" href="https://yourbrand.fr/products/handle" />
<link rel="alternate" hreflang="x-default" href="https://yourbrand.com/products/handle" />

The primary market's tag is often language-only. On rothys.com and glossier.com, both US-primary, we found hreflang="en" plus x-default on the primary URL on 16 September 2026, with no en-us tag, and region-qualified codes such as en-ca and en-gb on the other markets. So don't treat a missing en-us on your home market as a bug. The auto-emitted set covers the common cases5. Sub-folder Markets stores (yourbrand.com/de) get the same pattern with sub-folder paths in the href. Multi-domain stores get fully-qualified URLs per domain. Shopify reads the Markets settings to know which locales exist and what their URLs are.

What you fill in — the Markets configuration

The hreflang configuration on Shopify happens upstream of the tags — in Markets. Settings > Markets is where you define the regions you sell to, the languages active per region, and the URL routing (multi-domain or sub-folder). Shopify reads this config to emit hreflang automatically. If a hreflang tag is missing or wrong, the fix is almost always in Markets, not in theme code. Shopify only generates tags for markets that have their own domain, subdomain, or subfolder.

Three Markets settings that drive hreflang correctness. (1) The region's countries — hreflang's region component (en-US, de-DE) maps to the Markets region. (2) The language per region — hreflang's language component (en, de, fr) maps to active Markets languages. (3) The URL routing — multi-domain (yourbrand.de) vs sub-folder (yourbrand.com/de) sets what URL Shopify emits in the hreflang href.

The x-default tag — Shopify's default behaviour

x-default is a special hreflang value that tells Google which URL to show when no other hreflang matches the user's locale. Per Google's hreflang documentation, x-default is recommended on every internationalised page. Shopify adds x-default pointing to the primary domain's version of the page — typically the .com URL on multi-domain stores, or the bare path on sub-folder stores. You don't configure this manually; Shopify reads the primary domain from your domain settings.

What x-default solves: a buyer whose language and region match no tag still gets a URL. A buyer from Switzerland searching in English matches the language-only en tag on the primary market6. A buyer from Singapore browsing in Mandarin gets the x-default page if there's no zh-SG-specific URL. The fallback prevents the worst case (no result shown for an unmapped locale) at the cost of the buyer landing on a non-localised page. Shopify's default behaviour — x-default to the primary domain — is right for most stores.

Validation and common errors

Three common hreflang errors on Shopify stores. (1) Missing return tags — every alternate must point back to itself. Shopify's automatic tags include these; manual additions sometimes don't. (2) Wrong region code — using 'uk' when Google expects 'gb' (the ISO 3166-1 code). (3) Hreflang on pages that don't have localised equivalents — pointing en-US/products/handle hreflang to de-DE/products/handle when the de-DE store doesn't have that product.

Validation tools: Google Search Console no longer reports hreflang errors; Google deprecated the International Targeting report that used to7. Third-party tools (Merkle's hreflang validator, Sitebulb) crawl your domains and surface missing return tags or mismatched alternates. Shopify's automatic tags handle most of these correctly — errors usually mean Markets is misconfigured, or a theme or app is adding its own hreflang tags on top of Shopify's. Shopify warns that doubling up "can produce duplicate or conflicting annotations"; if your theme or an app outputs hreflang, turn off Automatic hreflang tags in Online Store > Preferences so only one source emits them5.

One Shopify-specific gotcha: the multilingual sitemap auto-add behaviour from Shopify's find-site-map doc2 — "these languages are added automatically to the sitemap files" — means your sitemap should already include the alternate URLs. If the sitemap doesn't list them, Markets isn't fully configured for storefront publication. Verify Markets before assuming the sitemap is broken.

Keep reading