---
title: Support multiple languages on storefronts
description: Learn how to support multiple languages on a storefront with the Storefront API.
source_url:
  html: https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages
  md: https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages.md
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#requirements)
* [Step 1: Retrieve available languages](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-1-retrieve-available-languages)
* [Step 2: Retrieve translations](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-2-retrieve-translations)
* [Step 3: Create a cart in the customer's language](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-3-create-a-cart-in-the-customers-language)
* [Next steps](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#next-steps)

# Support multiple languages on storefronts

You can use the [Storefront API](https://shopify.dev/docs/api/storefront) 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.

***

## Requirements

* You've completed the [Getting started with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/getting-started) guide.
* You're familiar with [querying products and collections](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/getting-started).

- You've created [resources that can be translated](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets#translatable-resources) in your store.
- You've created translated content using the [GraphQL Admin API](https://shopify.dev/docs/apps/build/markets/manage-translated-content).
- You're using API version 2022-04 or higher.

***

## Step 1: Retrieve available languages

For each country context, the languages available are configured [within the shop's Markets settings](https://help.shopify.com/manual/markets/languages/manage-languages#manage-languages-for-markets). The following example shows how to access the list of available languages with the [`Localization`](https://shopify.dev/docs/api/storefront/latest/objects/localization) object.

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
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

```json
{
  "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"
    }
  }
}
```

***

## Step 2: Retrieve translations

To query [translatable resources](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets#translatable-resources) and return translated content, use the `@inContext` directive to contextualize any query in one of the shop's [available languages](#step-1-retrieve-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

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

## JSON response

```json
{
  "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"
    }
  }
}
```

***

## Step 3: Create a cart in the customer's language

The `@inContext` directive can also be used with the [`cartCreate`](https://shopify.dev/docs/api/storefront/latest/mutations/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

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

***

## Next steps

* Learn how to query [international prices](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing) for products and orders, and explicitly set the context of a cart.
* Learn how to [create and update a cart](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage) in Shopify with the Storefront API.
* [Retrieve metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields) with the Storefront API to access additional information from different types of resources.
* Learn how to [manage customer accounts](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/customer-accounts) with the Storefront API.
* Learn about the [different tools](https://shopify.dev/docs/storefronts/headless/additional-sdks) that you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.

***

* [Requirements](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#requirements)
* [Step 1: Retrieve available languages](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-1-retrieve-available-languages)
* [Step 2: Retrieve translations](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-2-retrieve-translations)
* [Step 3: Create a cart in the customer's language](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#step-3-create-a-cart-in-the-customers-language)
* [Next steps](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages#next-steps)