Skip to main content

Translations

You can create and retrieve translated content for Shopify resources, as well as metaobjects and metafields. For example, you might add translations of product information and email notification templates using the GraphQL Admin API so a merchant can send email notifications to their customers in multiple languages. Those translations can then be retrieved by either the GraphQL Admin API or the Storefront API.

This guide shows you how to use the GraphQL Admin API to enable the es (Spanish) locale on your store, retrieve a product, translate the product's title, publish the new locale, and view the translated content on your store.

Anchor to RequirementsRequirements

Anchor to LimitationsLimitations

  • If you need to change a store's primary locale, then you need to make the change in the Shopify admin. You can't change the primary locale using the GraphQL Admin API.
  • A resource's tags field can't be translated. For example, you can't translate a product's tags.
  • The translation response that's returned for menu links and email and SMS notification templates doesn't include the handle field.
  • If the merchant changes a product's handle, then URL redirects for that product won't be supported for language-specific URLs.
  • You can translate metafields only if they are publicly accessible.
  • App proxies don't support translations.

Anchor to Step 1: Enable a localeStep 1: Enable a locale

The ShopLocale object provides the list of primary and alternate locales that have been enabled on a Shopify store. Each locale has the following attributes:

  • Primary: Whether the locale is the default locale for the store. You can only have one primary locale.
  • Published: Whether the locale is visible to buyers. A store can have multiple locales in published or unpublished states.

You can use the shopLocaleEnable mutation to enable a locale on your store. Shopify accepts locales in the following formats:

  • Language subtag only: For example, en (English).
  • Language subtag + region subtag: For example, en-UK (English as spoken in the United Kingdom).

In the shopLocale response, include the locale, name, and published fields to verify that the locale has been successfully enabled.

Note

By default, newly enabled locales aren't published. Shops are limited to 20 enabled locales.

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

GraphQL mutation

mutation enableLocale($locale: String!) {
shopLocaleEnable(locale: $locale) {
shopLocale {
locale
name
published
}
}
}

Variables

{
"locale": "es"
}

JSON response

{
"data": {
"shopLocaleEnable": {
"shopLocale": {
"locale": "es",
"name": "Spanish",
"published": false
}
}
}
}

Anchor to Step 2: Retrieve a translatable productStep 2: Retrieve a translatable product

To retrieve the first product eligible for translation, use the translatableResources query with the parameters first: 1 and resourceType: PRODUCT.

In the translatableContent response, include the key, value, digest, and locale fields. You need their response values to write the translation in the next step.

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

GraphQL query

{
translatableResources(first: 1, resourceType: PRODUCT) {
edges {
node {
resourceId
translatableContent {
key
value
digest
locale
}
}
}
}
}

JSON response

{
"data": {
"translatableResources": {
"edges": [
{
"node": {
"resourceId": "gid:\/\/shopify\/Product\/1973887860758",
"translatableContent": [
{
"key": "title",
"value": "Great shirt",
"digest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9",
"locale": "en"
},
{
"key": "body_html",
"value": "This is one fine shirt.",
"digest": "8e48350042b4ca04a7a4568774af71f921e7c9b561d9fac7860041e566218d25",
"locale": "en"
}
]
}
}
]
}
}
}

Anchor to Step 3: Write a translationStep 3: Write a translation

You can use the translationsRegister mutation to create a new translation for a translatable resource.

When you create a translation, you need to include the translatable content's digest value in the translatableContentDigest field. A unique digest is returned from the translatableResources query for each translatableContent entry.

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

GraphQL mutation

mutation CreateTranslation($id: ID!, $translations: [TranslationInput!]!) {
translationsRegister(resourceId: $id, translations: $translations) {
userErrors {
message
field
}
translations {
locale
key
value
}
}
}

Variables

{
"id": "gid://shopify/Product/GID",
"translations": [
{
"key": "title",
"value": "Camiseta buena",
"locale": "es",
"translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9"
}
]
}

JSON response

{
"data": {
"translationsRegister": {
"userErrors": [],
"translations": [
{
"locale": "es",
"key": "title",
"value": "Camiseta buena"
}
]
}
}
}

Anchor to Step 4: Publish the localeStep 4: Publish the locale

You can use the shopLocaleUpdate mutation to publish a locale to a Shopify store. Publishing a locale makes it available for translation. Shops are limited to 20 published locales.

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

GraphQL mutation

mutation updateLocale {
shopLocaleUpdate(locale: "es", shopLocale: {published: true}) {
userErrors {
message
field
}
shopLocale {
name
locale
primary
published
}
}
}

JSON response

{
"data": {
"shopLocaleUpdate": {
"userErrors": [],
"shopLocale": {
"name": "Spanish",
"locale": "en",
"primary": false,
"published": true
}
}
}
}

Anchor to Step 5: Visit your online storeStep 5: Visit your online store

To view the translation on your online store, complete the following steps:

  1. Navigate to the product's page on your online store.

  2. Add an es to your URL. For example, myshopifystore.com/es/products/great-shirt.

Anchor to WebhooksWebhooks

Your app can subscribe to webhooks for event notifications related to locales. The following examples show the JSON responses from each of the available webhooks.

To learn how to set up and consume webhooks, refer to Webhooks configuration overview.

Example webhook responses

{
"locale": "fr-CA",
"published": true
}
{
"locale": "fr-CA",
"published": true
}

Anchor to Next stepsNext steps

Was this page helpful?