All Tutorials

Manage shop locales with the GraphQL Admin API

All Tutorials

Manage shop locales with the GraphQL Admin API

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:

Tag format Example tag Description
Language subtag only en English
Language subtag + region subtag en-UK English as spoken in the UK.

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.