Hreflang codes on Shopify: en, en-US, en-CA and x-default explained
Each hreflang tag carries a short code that says who the page is for. Get the codes right and search engines can match each shopper to the right version of your store. Here is what the codes mean, which ones a store with several markets needs, and the mistakes Google quietly ignores.
What a code is made of
A hreflang code is a language, optionally followed by a country, and occasionally a script in between:
- The language is a two-letter code from ISO 639-1:
enfor English,frfor French,defor German. - The country, if you add one, is a two-letter code from ISO 3166-1, after a hyphen:
en-CAis English for Canada,fr-CAis French for Canada. - The script is optional and rarely needed: a four-letter code from ISO 15924, between the language and the country. It matters for languages written in more than one script, such as Chinese:
zh-Hantis Traditional Chinese,zh-Hans-USis Simplified Chinese for the United States. Without one, search engines work the script out from the country (zh-TWreads as Traditional).
Capital letters don't matter (en-ca and en-CA mean the same thing). A country on its own is not a valid code: US by itself tells search engines nothing. (Be careful with examples like CA: on its own it reads as ca, the language code for Catalan.)
There is also one special value, x-default. It names the page for everyone the other codes don't cover.
Language only, or language and country?
The two kinds of code do different jobs.
A language-only code like en means "English, for anyone, anywhere". Google describes it as a catch-all for speakers of that language whose country isn't otherwise listed. A language-and-country code like en-CA means "English, for shoppers in Canada", so it only does something when you have a version meant for that country, with its own currency, prices or availability.
On Shopify, those country versions usually come from Markets. Each market can have its own subfolder (such as /en-ca) or its own domain, and each language you publish appears in every market. That is where most of a store's codes come from.
A worked example
Take a store with two markets, the United States (its primary market) and Canada, and two published languages, English (its primary language) and French. Our own test store is set up this way, and its home page carries these tags (with its domain swapped for yourstore.com):
<link rel="alternate" hreflang="en" href="https://yourstore.com/"> <link rel="alternate" hreflang="en-US" href="https://yourstore.com/"> <link rel="alternate" hreflang="fr" href="https://yourstore.com/fr"> <link rel="alternate" hreflang="fr-US" href="https://yourstore.com/fr"> <link rel="alternate" hreflang="en-CA" href="https://yourstore.com/en-ca"> <link rel="alternate" hreflang="fr-CA" href="https://yourstore.com/fr-ca"> <link rel="alternate" hreflang="x-default" href="https://yourstore.com/">
| Code | Who it's for |
|---|---|
en-US, fr-US | Shoppers in the United States, in English or French. |
en-CA, fr-CA | Shoppers in Canada, in English or French. Their pages live under /en-ca and /fr-ca, with Canadian prices. |
en, fr | English or French speakers anywhere else, say in the United Kingdom or Belgium. They point at the primary market's version, because that is the store those shoppers would reach. |
x-default | Everyone else: a German speaker, for example. It points at the primary market in the primary language. |
Notice that some addresses appear under more than one code. That is fine and expected: one page can be the right answer for several audiences. What matters is that every page in the set lists the same codes, and lists itself.
Mistakes Google ignores
Google doesn't warn you about a bad code. It just ignores the part it can't use, so these mistakes are easy to miss:
en-UKinstead ofen-GB.UKis a reserved code, not the United Kingdom's country code. Google's documentation names this one specifically.- A country without a language, such as
hreflang="US". Google says specifying the region alone is not valid. - Codes that aren't two-letter language codes, such as
hreflang="english"or a three-letter code likeeng. Only ISO 639-1's two-letter codes are supported. - Two different pages for the same code, such as two
fr-CAtags pointing at different addresses. This almost always means two sources are printing tags; see duplicate hreflang tags on Shopify. - More than one
x-defaultin a set, or pages in the same set naming different x-default pages.
The free hreflang checker checks every code on a page against the ISO language and country lists and flags each of these.
Do you need every code?
No single code is required, but the set has to be consistent. A store with one market and two languages needs only en, fr and, if you like, x-default. Country codes earn their place once you sell to a country with its own version of the store. If your tags list countries you don't have a separate version for, they add noise without helping anyone.
If you'd rather not work out the set by hand, Hreflang Manager builds it from your markets and languages (the example above is its output on our test store) and checks that every page lists the same set. It has a free plan. For checking the rest of your tags, see how to check the hreflang tags on your Shopify store.
Sources
- Google Search Central: Tell Google about localized versions of your page (supported codes, x-default, the "region alone" and reserved-code mistakes).