Supporting multi-language online stores

Shopify supports selling in multiple languages from a single online store, allowing merchants to provide the same consistent shopping experience in multiple languages.

This guide explains how you can provide the same consistent experience for your apps users and their customers in multiple languages.

Why should I support multiple languages in online stores

Supporting multi-language online stores lets your users offer localized content to their customers in multiple different languages. If your app supports only a single language, then you risk providing an inconsistent experience for your users and their customers. For example, a Free Shipping app that prompts a customer to add a few more items to their cart to be eligible for free shipping. If the buyer is shopping in German and the popup content is in English, that could be a confusing user experience for the buyer.

How can I tell if a merchant is using a multi-language online store?

You can query the ShopLocale object to retrieve a list of the locales that a store is using. If more than one locale has the published field set to true, then the merchant is likely using a multi-language online store. See the Shop locale guide for more information.

How can I support multi-language online stores?

Shopify has introduced important changes to our APIs and resources to help you make sure that your app can support multiple languages.

Translating content using the Shopify admin API

The Admin API allows you to create and retrieve translated content for Shopify resources. For example, translating product information and email notification templates so that a merchant can send customers email notifications in multiple languages. Learn how to translate content using our APIs.

Managing locales using the ShopLocale object

The admin GraphQL ShopLocale object lets you manage which languages are available on a merchants storefront at any given time. You can use the Shoplocale object to publish, enable, and retrieve a store's locales. Learn how to enable, publish, and read shop locales.

Supporting multi-language online stores using Liquid

We’ve added multi-language capabilities to our Liquid templating language to better serve you when surfacing translated content to buyers on the storefront or in email notifications. Learn how you can support multi-language online stores using Liquid.

Developing themes that support multiple languages

With the addition of translated content, there have been several changes made to the Liquid templating language.

Published locales and theme paths

When a locale is published from the API, Shopify automatically creates a URL path for the locale. For example, if you published the French (fr) locale on a shop whose primary URL is shop.com, then a shop.com/fr URL is automatically created.

When you unpublish a locale, any links to URLs with that locale return a "404 Not Found" page.

Liquid drops and translations

Liquid now accounts for the locale in URL paths. For example, if the buyer visits shop.com/fr, then the {{ product.title }} Liquid drop automatically renders the French translation if it's available. If the translation is not available, then it renders the primary shop locale.

Locales

You can request locale information using the following Liquid drops:

Routes

Liquid-generated routes include the locale. For example, {{ product.url }} returns /products/handle on shop.com and /fr/products/handle on shop.com/fr.

We recommend that you avoid hardcoding URLs in your themes. Using hardcoded URLs can result in a user being sent to the wrong locale.

Incorrect

<a href=/products/{{ product.handle }}>{{ product.title }}</a>

Correct

<a href={{ product.url }}>{{ product.title }}</a>

Search engine optimization

When you publish a locale, hreflang tags are added to the <head> of all your translated resources through the {{ content_for_header }} tag. Search engines use the hreflang tag to serve the correct language URL in search results based on the searcher's language preference.

The hreflang="x-default" URL is based on the shop's primary locale. If a searcher's language doesn't match any of the hreflang tags, then they are routed to the x-default URL.

In the following example, the hreflang tags instruct search engines to direct english speakers to the /product/abcd URL, french speakers to the /fr/product/abcd URL, and all other languages to the /product/abcd URL.

<head>
  <link rel="alternate" hreflang="x-default" href="/product/abcd">
  <link rel="alternate" hreflang="en" href="/product/abcd">
  <link rel="alternate" hreflang="fr" href="/fr/product/abcd">
</head>

Testing multi-language online stores

You can test a multi-language online store feature using any development store that has developer preview enabled. This feature is only available in developer preview stores.

Where can I get help?

If you have questions about the multi-language changes or you have trouble updating your app, then visit the Shopify Community forums to get help from the Shopify community.

Sign up for a Partner account to get started.

Sign up