Fixing Hreflang in Shopify

What Shopify generates, and where

When you sell to several countries or publish more than one language, Shopify adds hreflang link tags to the head of storefront pages automatically. They are injected through the {{ content_for_header }} object in your theme's layout/theme.liquid, which is why you will not find them written anywhere in the theme files. Each tag pairs a language, and usually a country, with the address where that version of the page is served.

What appears depends on three admin areas:

• Settings, Markets. Each market groups one or more countries. How its storefront is reached, a subfolder such as /en-ie, a separate domain such as example.ie or a subdomain, decides the addresses in the tags.
• Settings, Languages. Only published languages appear. A language that exists but is unpublished, or not added to a market, produces no tags.
• Settings, Domains. The primary domain and any market domains decide which host each tag uses.

For a fictional homeware store, Linen and Loom, selling in the UK and Ireland in English and in France in French, with subfolders, the output on a product page looks broadly like this:

<link rel="alternate" hreflang="en-GB" href="https://example.com/products/oak-tray">
<link rel="alternate" hreflang="en-IE" href="https://example.com/en-ie/products/oak-tray">
<link rel="alternate" hreflang="fr-FR" href="https://example.com/fr-fr/products/plateau-chene">
<link rel="alternate" hreflang="x-default" href="https://example.com/products/oak-tray">

The exact set varies by configuration, so treat that as a shape to compare against, not a guaranteed format. The point is that every page should carry one complete set, and every address in it should load directly.

The errors the checker usually finds on Shopify

Duplicate tags from themes and apps

Duplicates are the Shopify problem to rule out first. They happen when something other than Shopify writes hreflang into the head: a translation or currency app that predates Shopify's built-in support, a snippet an agency added to theme.liquid years ago, or an SEO app with its own international settings. The page then carries two clusters that may disagree about codes or addresses, and Google has to guess which one you meant.

To find the source, open a product page, view the source and search for hreflang. Then in the theme code editor, search the whole theme for the same word:

{%- comment -%} Example of an old hard-coded block to remove from layout/theme.liquid {%- endcomment -%}
<link rel="alternate" hreflang="en" href="{{ shop.url }}{{ request.path }}">
<link rel="alternate" hreflang="fr" href="https://fr.example.com{{ request.path }}">

Blocks like this assume the same path works on every locale, which fails as soon as handles are translated, and they sit alongside Shopify's own tags. Remove them, after duplicating the theme as a backup. If the extra tags come from an app, look in its settings for an option to stop adding hreflang or alternate links; if there is none, ask the developer, or consider whether Shopify's own translation features now cover what the app was installed for.

Languages that are published before they are translated

When a language is published, Shopify serves that language's addresses for the whole catalogue. Where a product or page has no translation, the storefront falls back to the default language text. The hreflang tag still says, for example, fr-FR, but the page is in English. That undermines the cluster: Google can see from the content that the page is not in French, and French searchers who do land there get English text.

Before publishing a language, or before assigning it to a new market, translate at least the products, collections and pages you want found in that language, including the handles if you want localised addresses, the titles and the meta descriptions. Shopify's Translate and Adapt app or a translation app can show which resources are still untranslated. If a large part of the catalogue will stay untranslated for months, it can be better to launch the market in a language you have fully covered and add the second language later.

Translated handles also matter for broken targets. If you change a translated handle after launch, Shopify can create a URL redirect for the old one, but any links, sitemaps or hand-written tags that used the old address now point at a redirect.

Domains, subfolders and redirects

Shopify lets each market use a subfolder on the primary domain, its own domain, or a subdomain. Any of them can work with hreflang. Errors arise when the setup is half-changed, for example a market moved from subfolder to its own domain while old links, feeds or app settings still use the subfolder, or a country domain that is connected to the store but not set as the domain for its market, so it redirects to the primary domain.

• In Settings, Domains, confirm every domain you use is connected and assigned to the market it serves.
• Open each address from the hreflang tags in a private window. It should load directly, without redirecting to another market or asking the visitor to choose a country first.
• If you use an app or setting that sends visitors to a different market based on location, prefer a suggestion banner over an automatic redirect, so crawlers and visitors can reach every version.
• After changing a market's address pattern, update internal links, marketing feeds and any hand-written tags, and let Shopify regenerate its own.

Separate country stores

Some businesses run a separate Shopify store per country, often called expansion stores, for example example.co.uk and example.de. Shopify generates hreflang only for markets within a single store, so separate stores do not reference each other. To join them you add tags yourself in each store's theme, and each store must list all the others, including itself.

This only works cleanly where the product handles match across stores, or where you keep a mapping. A simple version for matching handles, placed in the head of layout/theme.liquid in each store:

{%- assign path = request.path -%}
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk{{ path }}">
<link rel="alternate" hreflang="de-DE" href="https://example.de{{ path }}">
<link rel="alternate" hreflang="x-default" href="https://example.co.uk{{ path }}">

That snippet assumes every page exists at the same path on both stores, which is rarely true for every product, search and account page. Limit it to templates where the paths match, such as products that exist in both catalogues, and store translated handles in a metafield when they differ, so each tag can use the right address. For many stores, moving to one store with several markets removes this maintenance altogether; weigh that against the reasons you chose separate stores.

The fix, step by step

Keeping Shopify hreflang clean

• Let Shopify generate the tags for markets within one store, and avoid any second source.
• Treat publishing a language as a launch, with translated content ready first.
• Check the theme for hreflang code whenever you change or update themes, because copied snippets travel with them.
• Review app settings after installing anything that touches translation, currency or SEO.
• Keep one written map of markets, languages and domains, and check the Hreflang Checker output against it after each change.

For how clusters, codes and fallbacks work in general, see the Hreflang Guide. For choosing where visitors outside your markets should land, see the x-default guide.