# What Is hreflang and How to Use It on an Online Store

> What hreflang is, how to declare it in HTML, an HTTP header or the sitemap, what Shopify does for you and how to check that your versions link to each other.

URL: https://clione.ai/glossary/hreflang/
Lang: en

hreflang only matters if your store has more than one version of its pages: in English and Spanish, or in English for the United States and for the United Kingdom. If that is you, the problem it solves is concrete: **that someone searching in Spanish lands on the Spanish [product page](/glossary/product-page/)** and not the English one, and that near-identical regional versions do not compete with each other as [duplicate content](/glossary/duplicate-content/). It is not a translation tag or a redirect: it is a list of equivalents that the search engine can use or ignore, depending on how well it is done.

## How it works

Google accepts three ways to declare the versions of a page and treats them as equivalent: `<link>` elements in the HTML `<head>`, HTTP headers (useful for files that are not HTML, such as a PDF) or entries in the [XML sitemap](/glossary/xml-sitemap/). You can use all three at once, but **you gain nothing in Search** and maintaining three implementations is harder than maintaining one.[^google-localized]

The rules that make it work are few and strict:[^google-localized]

- **Each version lists itself and all the others.** If two pages do not point at each other, Google ignores the tags. The reason is security: it stops anyone on another site from declaring themselves an alternate version of one of your pages.
- **The code starts with the language**, in ISO 639-1 format, and can add the region in ISO 3166-1 alpha-2 format: `es`, `es-ES`, `en-GB`. A country code on its own is not valid, because Google does not infer the language from the country.
- **`x-default` is the version for everyone else**: the one offered to people searching in a language that is not on the list. Google designed it for language selector pages.
- **URLs are fully qualified**, with `https://`, not relative. They can be on different domains.

There are two things hreflang does not do, and it helps to keep them in mind. The first: **Google uses neither hreflang nor the HTML `lang` attribute to work out what language a page is in**; it detects that with its own algorithms, by reading the text.[^google-localized] The second: hreflang does not move anyone from one page to another. Google asks for a separate URL for each language, instead of cookies or browser settings, and for no automatic redirects from one language to another. Remember too that [Googlebot](/glossary/googlebot/) usually crawls from the United States: a store that redirects by IP address may never let it see the Spanish version.[^google-multiregional] What Google does recommend is visible links to the other versions, so people can switch.[^google-multiregional]

It crosses with the [canonical](/glossary/canonical-url/) in two ways. Google prefers as canonicals the URLs that belong to a hreflang group, and asks that, if you use hreflang, **each page declares a canonical in its own language**, or in the best substitute if there is none in that language.[^google-consolidate] That makes sense: to Google, translated versions are only duplicates if the main content is still untranslated.[^google-localized]

Bing also recommends hreflang to signal language and region, and adds a warning that matters to stores: **near-identical regional pages create duplicate content**. Its advice is to localize with real changes, such as terminology, examples, regulations or product data, and not to create several pages in the same language that serve the same purpose.[^bing-duplicate]

## On a store

A **fictional example**: a mountain gear store sells in the United States and in Spanish-speaking markets, with one folder per version. This is the `<head>` of a backpack's product page in its US version:

```html
<head>
  <link rel="canonical" href="https://store.example/us/trek-25-backpack" />
  <link rel="alternate" hreflang="en-US" href="https://store.example/us/trek-25-backpack" />
  <link rel="alternate" hreflang="es" href="https://store.example/es/mochila-trek-25" />
  <link
    rel="alternate"
    hreflang="x-default"
    href="https://store.example/us/trek-25-backpack"
  />
</head>
```

The Spanish version repeats the three `alternate` lines exactly the same and changes only its canonical, which points to itself. That is the pair that has to line up: **the same alternates on every version, and a canonical of its own on each**.

If your store is on Shopify, you do not have to write any of this by hand. Shopify adds the hreflang tags automatically through `content_for_header`, which the theme prints in the `<head>` of `layout/theme.liquid`. A single-country market produces a code with a region, such as `en-us`, and a broader one produces just the language, such as `fr`; the tags update when you change a market's domains or languages. If your theme or an app already writes its own tags, Shopify recommends **turning the automatic ones off** under Online Store, Preferences, so there is only one source.[^shopify-hreflang]


That hreflang tells Google what language the page is in. It does not: Google detects the language by reading the content and uses neither hreflang nor the `lang` attribute for that.[^google-localized] A product page marked `es` with its description still in English remains, for Google, an English page. hreflang only relates versions that already exist, so **translate first and link after**.


## How to check it

1. **Open the page source of a product page** (Ctrl+U in Chrome) in each language and search for `hreflang`. Each version has to list itself and all the others, with the same URLs.[^google-localized]
2. **Review the codes**: language first, region after it if there is one, and never a country alone. The most common errors Google cites are missing return links and misspelled language or region codes.[^google-localized]
3. **Open every URL on the list** and confirm it loads the version it says it does, without redirecting you to another one based on your location.[^google-multiregional]
4. **Look for `rel="canonical"` on each version**: it has to point to a page in its own language, normally itself.[^google-consolidate]
5. **On Shopify, count the sources.** If you see the tags repeated, the theme or an app is writing them in addition to Shopify, and one of the two has to be turned off.[^shopify-hreflang]

## Related concept: canonical

The canonical and hreflang get confused because both go in a `<link>` in the `<head>` and both talk about several URLs. They solve opposite problems. **The canonical picks one URL among copies of the same content**, for example the same product page opened with a campaign parameter. **hreflang relates different pages that say the same thing in another language**, and asks the search engine to keep them all, each for its own audience. That is why an English version with a canonical pointing to the Spanish one is a mistake: it tells Google the English page is a copy and not to index it separately, exactly the opposite of what hreflang asks for.[^google-consolidate]

To keep going, the [reading path for this topic](/learn/crawling-and-indexing/) puts the rest of the terms in order, from how a URL is discovered to its [indexing](/glossary/indexing/), and [internal linking](/glossary/internal-linking/) explains how crawlers reach each version.