---
title: Use hreflang tags in your theme
description: >-
  Learn how Shopify adds hreflang tags to your theme automatically, and when to
  add them manually.
source_url:
  html: 'https://shopify.dev/docs/storefronts/themes/seo/hreflang'
  md: 'https://shopify.dev/docs/storefronts/themes/seo/hreflang.md'
api_name: liquid
---

# Use hreflang tags in your theme

Search engines use `hreflang` tags to serve the right language or region version of a page to each customer. If your store uses [Shopify Markets](https://shopify.dev/docs/storefronts/themes/markets), then Shopify adds these tags to your theme automatically.

**Note:**

This page provides general guidance about `hreflang` tags. For specific SEO guidance for your store, contact an SEO expert. You can find Partners with SEO expertise in Shopify's [Partner Directory](https://www.shopify.com/partners/directory).

***

## How it works

Shopify adds `hreflang` tags to your theme automatically through the [`content_for_header`](https://shopify.dev/docs/api/liquid/objects/content_for_header) object, which your theme renders in the `<head>` of `layout/theme.liquid`. These tags:

* Reflect each market's languages and regions, so a country-specific market produces a region-qualified tag like `fr-ca` or `en-us`, while a broader market produces a language-only tag like `fr`.
* Update automatically when you add, remove, or change a market's domains or languages.
* Stay in sync with each page's canonical URL, so that search engines treat localized URLs as related versions of the same page.

**Warning:**

Adding your own tags on top of the automatic ones can produce duplicate or conflicting annotations, which can hurt your store's search ranking.

***

## When to manage `hreflang` tags manually

Shopify's automatic tags already cover most stores, including region-specific markets, but in some cases you might want to manage `hreflang` tags yourself.

If your theme or a third-party app already outputs `hreflang` tags, then turning off the automatic tags ensures that only one source outputs tags and prevents your store's search ranking from being negatively impacted.

You might also need your own tags for a setup that Shopify Markets can't coordinate for you, such as linking alternate versions of a page across separate Shopify stores on different domains.

### Turn off automatic `hreflang` tags

To turn off automatic tags, go to **Online store > Preferences** in your Shopify admin. In the **Social sharing and SEO** section, turn off **Automatic `hreflang` tags**.

If you add your own `hreflang` tags in `layout/theme.liquid`:

* Build the tags dynamically from the [`localization`](https://shopify.dev/docs/api/liquid/objects/localization) object, so that they reflect the store's active markets and languages. Don't hardcode domains or resource handles. A hardcoded collection or product handle doesn't work, because a resource's handle can differ in each language, and the `<head>` in `layout/theme.liquid` renders on every page.
* Make sure that each localized URL references itself as its own canonical URL.

For guidance on `hreflang` syntax and best practices, refer to [Google's documentation](https://developers.google.com/search/docs/advanced/crawling/localized-versions).

***

## Next steps

* Learn how Shopify handles [SEO for multiple currencies and languages](https://shopify.dev/docs/storefronts/themes/markets/multiple-currencies-languages#search-engine-optimization).
* Refer to Shopify's [international SEO guidance for markets](https://help.shopify.com/en/manual/markets/seo).

***