All Tutorials

Support multiple languages in apps and themes

All Tutorials

Support multiple languages in apps and themes

Support multiple languages in apps and themes

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, then a URL is automatically created. Shops are limited to 5 published locales.

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, 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.

Liquid code embedded in .js.liquid, .scss.liquid, or .svg.liquid files execute only when the file is saved, not on page request. Liquid code that depends on the session state uses session information from when the file was generated, not the current session. For example, if your store's primary locale is English, then the code console.log(""); would display the english translation even when it's being viewed in a language that you support.


You can request locale information using the following Liquid drops:


Liquid-generated routes include the locale. For example, {{ routes.cart_url }} returns /cart on and /fr/cart on

You can use the url attribute of a Liquid object to return a URL that includes the locale. For example, {{ product.url }} returns /products/<product_handle> on and /fr/products/<product_handle> on

When a Liquid object contains a list of items, such as the pages object, you can return the URL for a specific item by referencing its handle. For example, {{ pages['about-us'].url }} returns /pages/about-us on and /fr/pages/about-us on

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


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


<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.

  <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">

Testing multi-language online stores

You can test a multi-language online store feature using any development store that you've created from your Partner Dashboard.

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.