Skip to main content

Support multiple languages on storefronts

You can use the Storefront API to support multiple languages on a storefront. This guide explains how to retrieve translated content and create a cart in the customer's language with the Storefront API.

Anchor to RequirementsRequirements

Anchor to Step 1: Retrieve available languagesStep 1: Retrieve available languages

For each country context, the languages available are configured within the shop's Markets settings. The following example shows how to access the list of available languages with the Localization object.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query Localization @inContext(country: US, language: ES) {
localization {
# for the current country
availableLanguages {
isoCode
endonymName
}

# and for non-current countries
availableCountries {
isoCode
name
availableLanguages {
isoCode
endonymName
}
}
}
}

JSON response

{
"data": {
"localization": {
"availableLanguages": [
{
"isoCode": "EN",
"endonymName": "English"
},
{
"isoCode": "ES",
"endonymName": "Español"
}
],
"availableCountries": [
{
"isoCode": "CA",
"name": "Canadá",
"availableLanguages": [
{
"isoCode": "EN",
"endonymName": "English"
},
{
"isoCode": "FR",
"endonymName": "français"
}
]
},
{
"isoCode": "US",
"name": "Estados Unidos",
"availableLanguages": [
{
"isoCode": "EN",
"endonymName": "English"
},
{
"isoCode": "ES",
"endonymName": "Español"
}
]
}
]
}
},
"extensions": {
"context": {
"country": "US",
"language": "ES"
}
}
}

Anchor to Step 2: Retrieve translationsStep 2: Retrieve translations

To query translatable resources and return translated content, use the @inContext directive to contextualize any query in one of the shop's available languages.

The following example returns the Spanish translations for a product's title, description, and options.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query productDetails @inContext(language: ES) {
product(handle: "white-t-shirt") {
title
description
descriptionHtml
options {
name
values
}
}
}

JSON response

{
"data": {
"product": {
"title": "Camiseta blanca",
"description": "Hecho de algodón fino",
"descriptionHtml": "<p>Hecho de algodón fino<\/p>",
"options": [
{
"name": "Talla",
"values": [
"Pequeña",
"Mediana",
"Grande"
]
}
]
}
},
"extensions": {
"context": {
"country": "US",
"language": "ES"
}
}
}

Anchor to Step 3: Create a cart in the customer's languageStep 3: Create a cart in the customer's language

The @inContext directive can also be used with the cartCreate mutation to set the cart locale.

The following example creates a cart that will load in Spanish when you redirect the customer to its checkoutUrl.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation createCart @inContext(language: ES) {
cartCreate(
input: {
lines: [
{ quantity: 1, merchandiseId: "gid://shopify/ProductVariant/38615086082" }
]
}
) {
cart {
checkoutUrl # loads in Spanish
}
}
}

Anchor to Next stepsNext steps

  • Learn how to query international prices for products and orders, and explicitly set the context of a cart.
  • Learn how to create and update a cart in Shopify with the Storefront API.
  • Retrieve metafields with the Storefront API to access additional information from different types of resources.
  • Learn how to manage customer accounts with the Storefront API.
  • Learn about the different tools that you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.
Was this page helpful?