A Shopify store can look perfectly translated while its search signals remain tangled. You've enabled several languages in Shopify Markets, an app has added alternate links, and your theme may already contain its own snippet. A crawl then reveals duplicate hreflang tags, missing return links, or localized URLs that don't match the market configuration. The difficult question isn't whether Shopify supports hreflang. It's whether Shopify Markets, your theme, and your apps are producing one consistent set of signals.

Table of Contents

Understanding hreflang Shopify

Hreflang connects equivalent pages written for different languages or regional audiences. For example, a product page in English can reference its French equivalent, while the French page references both itself and the English version. Search engines can then interpret the relationship between those URLs instead of treating localized pages as unrelated or duplicate content.

Shopify Markets handles much of this natively. Shopify's official hreflang documentation says tags are generated automatically when a store uses Shopify Markets. Assigning a domain, subfolder, or subdomain to a market with a specific language causes the appropriate tags to be added to every page. Shopify's examples include structures such as /fr/ and separate domains such as example.fr.

Before inspecting theme code, configure the platform layer:

  • Create the relevant markets: Define the countries or regions your store serves in Shopify Markets.
  • Publish the languages: Make sure each language is active and connected to the intended market.
  • Choose the URL structure: Assign a domain, subfolder, or subdomain consistently for each market.
  • Review translations: Confirm that products, collections, pages, and blog content have equivalent localized versions where you expect alternate URLs.
  • Check the admin preference: Shopify says automatic hreflang can be turned on or off under Online Store > Preferences.

A visual guide explaining how Shopify Markets automatically handles hreflang tags for global e-commerce SEO optimization.

The key operational principle is simple: Shopify Markets should be your first source of truth when one store manages the markets. Manual code should fill a clearly defined gap, not duplicate what the platform already emits. If you inherit a store with custom snippets or SEO apps, inspect the rendered HTML before changing the setting. Turning native tags on without removing custom output can leave multiple competing annotations on every localized page.

Implementing hreflang Tags in Shopify

Start with the least fragile strategy. If Shopify Markets controls your international storefront, verify the market-language mapping and inspect the page source for the expected alternates. Shopify's automatic output is tied to the domains, subfolders, or subdomains assigned to markets, so changing those assignments changes the hreflang relationships Shopify generates.

Google's international SEO guidance requires hreflang annotations to connect equivalent language or regional URLs. Alternate URLs must be fully qualified, and every cluster should include a self-referencing page. A page that only points outward, without pointing to itself and receiving reciprocal references, is incomplete.

A flowchart explaining two strategies for implementing hreflang tags on Shopify: automatic and manual tag injection.

Use manual injection only when your architecture requires it, such as a setup spanning separate Shopify stores or a theme that must reference localized URLs not represented by Markets.

A controlled Liquid implementation

Create a small snippet rather than scattering tags across several templates. In theme.liquid, place the snippet inside the <head> element:

{% render 'hreflang-links' %}

A basic snippet can follow this pattern:

<link rel="alternate" hreflang="en" href="https://www.example.com{{ request.path }}">
<link rel="alternate" hreflang="fr" href="https://www.example.fr{{ request.path }}">
<link rel="alternate" hreflang="x-default" href="https://www.example.com{{ request.path }}">

This example assumes the same path exists on both domains. That assumption must be tested. Product handles, collection paths, translated slugs, and unavailable products can differ, so a simple path substitution may point search engines to the wrong page.

If you use a loop with stored alternate URLs, output one tag per valid equivalent page and include the current page in its own set. Don't place a manual snippet in theme.liquid, a product template, and an app at the same time unless each source has a documented, non-overlapping role.

The embedded walkthrough can help developers visualize the implementation choices:

After publishing, view the source of a product, collection, page, and blog URL in each locale. Search for rel="alternate" and confirm that the output is complete, unique, fully qualified, and reciprocal.

Adding hreflang to Your Sitemap

HTML annotations aren't the only supported delivery method. You can also place hreflang relationships in an XML sitemap using xhtml:link elements. This approach is useful when a separate sitemap process owns international URL mappings, especially when the storefront spans domains or when localized equivalents aren't easy to derive inside Liquid.

A sitemap entry follows this general structure:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://www.example.com/products/example</loc>
    <xhtml:link rel="alternate" hreflang="en"
      href="https://www.example.com/products/example"/>
    <xhtml:link rel="alternate" hreflang="fr"
      href="https://www.example.fr/products/example"/>
    <xhtml:link rel="alternate" hreflang="x-default"
      href="https://www.example.com/products/example"/>
  </url>
</urlset>

The <loc> URL and each alternate should be fully qualified. Every localized URL should include the equivalent set, not just the English URL. Exclude targets that redirect, return an error, are blocked from crawling, or don't represent the same page. A translated product with no French equivalent shouldn't receive a fabricated French alternate.

Shopify's native sitemap output may not provide the exact cross-domain structure your organization needs. In that situation, generate a separate international sitemap through your deployment process or a specialist SEO workflow. Keep the ownership clear. If your sitemap and page source describe different relationships, troubleshooting becomes much harder.

For Shopify-specific sitemap considerations, use this Shopify sitemap guide alongside Google's documentation and your own crawl results.

Submit the sitemap in Google Search Console by opening the relevant property, selecting Sitemaps, entering the sitemap path, and submitting it. Then inspect the sitemap status and indexed URL behavior. Submission doesn't guarantee that Google will accept every alternate. It gives Google another discovery and relationship signal, so the URLs still need to be accessible, canonicalized correctly, and internally consistent.

Managing hreflang with Metafields and Theme Edits

Large catalogs often expose the limits of hard-coded mappings. A theme edit can be quick to deploy, but it becomes difficult to maintain when translated handles differ, products vary by market, or several teams update localized content. Metafields offer a structured place to store alternate URLs or locale-specific references, while Liquid controls how those values reach the page source.

Shopify's Markets SEO guidance makes the platform shift clear: automatic hreflang is generated from market-language configuration, and merchants can toggle it in the admin. That means custom metafields should extend a deliberate architecture, not supersede native output. Audit the live source first, then decide whether the custom layer is necessary.

Metafields for structured mappings

Create a URL or JSON metafield for the resource that needs a cross-locale reference. A JSON value might hold locale codes and URLs:

{
  "en": "https://www.example.com/products/example",
  "fr": "https://www.example.fr/products/exemple"
}

A Liquid loop can then render the stored values:

{% for alternate in product.metafields.seo.alternates.value %}
  <link rel="alternate"
        hreflang="{{ alternate.locale }}"
        href="{{ alternate.url }}">
{% endfor %}

The exact namespace and object depend on your data model. Validate that the metafield exists before rendering it, and don't output empty URLs. Metafields work well when content teams need to update mappings without editing theme files, or when translated URLs don't follow a predictable pattern.

Theme edits for stable structures

Direct Liquid edits are usually simpler when every market uses a predictable domain or subfolder and the same resource handle works across locales. A single snippet makes the logic visible and easier to review. The trade-off is maintenance risk. A theme update can overwrite custom code, and a hard-coded pattern can fail when the catalog or URL structure changes.

Method Pros Cons
Metafields Flexible mappings, useful for translated handles, editable data layer Requires disciplined data entry, validation, and fallback handling
Theme edits Fast for stable URL patterns, logic stays close to the storefront Theme updates can affect code, and hard-coded assumptions can become stale

For background on using structured Shopify fields, see this Shopify metafields resource. Whichever method you choose, document whether it owns the full hreflang set or only supplemental alternates. One clean owner is safer than several partial owners.

Common Mistakes to Avoid hreflang Shopify

Hreflang failures usually come from relationships that are almost correct. An industry review reported that 75% of hreflang implementations contained errors. The same review identified 34% missing reciprocal links, 18% invalid language codes, 26% inconsistent page coverage, 12% broken URL targets, and 42% missing x-default. These figures are reported in the Digital Applied multilingual hreflang review.

Missing reciprocal links

A product page can reference its French version, but the French page must reference the English page as part of the same cluster. Crawl a sample from each locale, extract all alternate links, and compare the sets. If page A names page B but page B doesn't name page A, correct the source that generated the incomplete output.

Invalid language and region codes

Use valid language codes and, when targeting a region, valid language-region combinations. Don't invent variants based on internal market names. A label such as French Market isn't an hreflang value. Store the actual code in your configuration and validate it before publishing.

Duplicate output from apps and themes

This is the Shopify-specific conflict many implementations miss. Shopify Markets can generate tags automatically, while a theme snippet or SEO app may inject another set. The browser may show repeated alternates with different URLs, or two complete clusters that disagree.

Practical rule: before adding code, inspect the rendered source and identify every generator, Shopify Markets, the theme, app embeds, and any external rendering layer.

Disable or remove the unnecessary source. Shopify's documentation warns that custom tags should be removed before reactivating automatic hreflang, so restoration should follow that order rather than turning native output on first.

Inconsistent coverage

If product templates emit alternates but collection, page, or article templates don't, search engines receive an uneven map of your site. Build a page-type inventory and crawl at least one representative URL for every template. Then expand the crawl to detect localized pages where the expected set is absent.

Broken or unsuitable targets

An alternate that redirects, returns an error, or points to a non-equivalent page weakens the cluster. Check HTTP responses, canonical targets, indexability, and language content for every referenced URL. A localized page that isn't published in a market shouldn't be inserted merely to complete a row in a spreadsheet.

Missing x-default

Use x-default for the fallback URL when your setup has a general version or language selector destination. It isn't a replacement for language-specific annotations. Add it consistently wherever your architecture has a genuine default, then verify that the target is accessible and relevant.

A practical audit record should include the source URL, locale code, alternate URL, response status, canonical target, and reciprocal result. That turns a vague SEO warning into a fixable data problem.

Verifying and Monitoring hreflang Shopify Setup

A launch-day check isn't enough. Localized catalogs change when products are unpublished, domains are reassigned, translations are updated, or an app changes its output. Verification should combine rendered HTML, crawl data, and Google's own reports.

Start with the page source, not only the visual storefront. Check a product, collection, content page, and blog article in every active locale. Confirm the page references itself, lists the intended equivalents, uses fully qualified URLs, and doesn't emit duplicate tags.

Then run a crawl with a tool such as Screaming Frog. Export hreflang details and test:

  • Self-reference: Each page appears in its own alternate set.
  • Reciprocity: Referenced pages point back to the source.
  • Code validity: Language and regional values follow accepted formats.
  • Target health: Alternate URLs resolve and remain indexable.
  • Coverage: Comparable templates emit comparable relationships.
  • Fallback logic: x-default exists where the architecture needs it.

Google Search Console adds another layer. Use the Google Search Console Shopify workflow to connect search data with the affected URLs, then investigate patterns rather than isolated warnings. A warning on one removed product may be expected. The same warning across every French collection points to a template or configuration problem.

A guide on verifying and monitoring hreflang tags to ensure a healthy international website setup.

For ongoing work, schedule recurring crawls after theme deployments, translation releases, and Markets changes. RankEngine can audit Shopify SEO and multi-language hreflang signals, write supported fixes through Shopify's Admin API, and verify the live store before marking a change complete. Treat monitoring as a release check, not a one-time cleanup.

Use RankEngine to audit localized Shopify URLs, detect conflicts between Markets, themes, and apps, and monitor hreflang health after changes. Connect it to your existing Search Console and crawl workflow so your team can find missing reciprocity, invalid targets, and duplicate output before they spread across the catalog.