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.