All Tutorials

Update your app to support localization

All Tutorials

Update your app to support localization

Update your app to support localization

As part of Shopify’s internationalization roadmap, Shopify now includes a merchant’s locale in certain responses that are accessible to partner applications. This lets apps localize their responses and provide a better experience for merchants worldwide.

This locale impacts how merchants and staff accounts interact with Shopify, but doesn’t change how their customers interact with their online store and other channels.

You should provide customer support for all the languages that your app supports.

This doc includes information on using the locale param as well as best practices, tools, and resources for optimizing your localization efforts.

1. How users select their locale

Store staff accounts will be able to select their preferred language under their account information. This will determine which locale is passed through the API. Since each staff can choose their preferred language, each staff member may use an app for the same store in a different language.

Note also that languages aren’t tied to specific countries.

2. How Shopify sends the locale to apps

OAuth response

When using online access mode, Shopify will return the locale during the authentication callback. The associated_user now has a locale param.

Example access token response:

  "access_token": "5259f11a2ad451186ed0a24719254b23",
  "scope": "write_products,write_inventory",
  "expires_in": 86398,
  "associated_user_scope": "write_products,write_inventory",
  "associated_user": {
    "id": 8750858282,
    "first_name": "John",
    "last_name": "Smith",
    "email": ""
    "account_owner": true,
    "locale": "en"

Embedded apps

The way to find the locale for an embedded app depends on what you're using to build it.

App Bridge

When you use App Bridge, Shopify includes the locale as a URL parameter in the request to your embedded app. For example:×tamp=1563811785

The locale is also provided in the staffMember app state. For example:

app.getstate().then((state) => {
  const locale = state.staffMember.locale;


When using the Embedded App SDK, Shopify will return the locale in the request coming from admin. This allows apps to respond to requests in the proper language without requiring an online session.

Example request URL: https://{shop}

3. Regionalities

Some languages, such as Portuguese, require a region (pt-PR, pt-BR) to be meaningful. Other languages, such as English (en-US, en-UK), could very well use regionalities as well to better capture specific words or contexts that are unique to certain regions of the world. We encourage you to build your language functionalities with a resilient support mechanism given the potential future addition of regionalities.

4. Shopify App Store

The Shopify App Store is currently available in the following languages:

  • Brazilian Portuguese (pt-BR)
  • Danish (da)
  • Dutch (nl)
  • English (en)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Hindi (hi)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Norwegian Bokmål (nb)
  • Simplified Chinese (zh_CN)
  • Spanish (es)
  • Swedish (sv)
  • Thai (th)
  • Traditional Chinese (zh_TW)

You can also create localized app listings for your app.

5. Additional resources

Pseudolocalization tool

Pseudolocalization is a software testing method used for testing internationalization aspects of software. Instead of translating the text of the software into a foreign language, as in the process of localization, the textual elements of an application are replaced with an altered version of the original language, allowing you to preview the potential varying lengths of strings.

Shopify has published a rubygem that allows for easy pseudolocalization of your strings. Please see the following resources for details: Github: Rubygems:

Additional Resources

W3C internationalization best practices