Manage shop locales with the GraphQL Admin API

The ShopLocale type provides the list of primary and alternate locales on a shop. Each locale has two attributes: primary and published. Only one locale can be the primary locale at a time, but you can't change the primary locale using the API. A shop can have multiple locales in the published or unpublished states.

Merchants can also enable or publish a locale from the Shopify admin.

Shop locale access scopes

To use the shop locale GraphQL mutations, your app needs to request the write_locales access scope for a Shopify store. For more information on requesting access scopes when your app is installed, see OAuth. You can also enable or publish a locale from the Shopify admin.

Locale formats

Shopify accepts locales in the following formats:

Retrieve a list of available locales

The following query retrieves a list of locales that you can enable for a shop, including their ISO country code and name.

Query

{
  availableLocales {
    isoCode
    name
  }
}

Response

{
  "data": {
    "availableLocales": [
      {
        "isoCode": "af",
        "name": "Afrikaans"
      },
      {
        "isoCode": "sq",
        "name": "Albanian"
      },
      {
        "isoCode": "am",
        "name": "Amharic"
      },
      {
        "isoCode": "ar",
        "name": "Arabic"
      },
      {
        "isoCode": "an",
        "name": "Aragonese"
      },
      ...
    ]
  }
}

Retrieve a shop's locales

The following query retrieves a list of the shop's enabled locales, including the locale tag, the published state, and whether it is the primary tag.

Query

{
  shopLocales {
    locale
    primary
    published
  }
}

Response

{
  "data": {
    "shopLocales": [
      {
        "locale": "fr",
        "primary": true,
        "published": true
      },
      {
        "locale": "ja",
        "primary": false,
        "published": true
      }
    ]
  }
}

Enable a locale

A locale must be enabled before it can be published. The shopLocaleEnable mutation takes a locale tag. We request the shop locale in the response to verify that the locale was enabled correctly. Shops are limited to 5 enabled locales.

Variables

{
  "locale": "pt-BR"
}

Mutation

mutation enableLocale($locale: String!) {
  shopLocaleEnable(locale: $locale) {
    userErrors {
      message
      field
    }
    shopLocale {
      locale
      name
      primary
      published
    }
  }
}

Response

{
  "data": {
    "shopLocaleEnable": {
      "userErrors": [],
      "shopLocale": {
        "locale": "pt-BR",
        "name": "Portuguese (Brazil)",
        "primary": false,
        "published": false
      }
    }
  }
}

Publish a locale

Publishing a locale makes it available for translation. Make sure that you enable the locale before publishing it. Shops are limited to 5 alternate published locales.

Variables

{
  "locale": "pt-Br",
  "published": {
    "published": true
  }
}

Mutation

mutation updateLocale($locale: String!, $published: ShopLocaleInput!) {
  shopLocaleUpdate(locale: $locale, shopLocale: $published) {
    userErrors {
      message
      field
    }
    shopLocale {
      name
      locale
      primary
      published
    }
  }
}

Response

{
  "data": {
    "shopLocaleUpdate": {
      "userErrors": [],
      "shopLocale": {
        "name": "Portuguese (Brazil)",
        "locale": "pt-BR",
        "primary": false,
        "published": true
      }
    }
  }
}

Shop locale webooks

You can subscribe to the following Shop locale webhooks:

• locale/update fires when a locale is changed or published.
• locale/create fires when a locale is enabled.