Manage translations of merchant-provided content
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.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_localesaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
- You've created at least one product in your Shopify store.
LimitationsAnchor link to section titled "Limitations"
- 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
tagsfield 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
- 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.
Step 1: Enable a localeAnchor link to section titled "Step 1: Enable a locale"
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,
- Language subtag + region subtag: For example,
en-UK(English as spoken in the United Kingdom).
shopLocale response, include the
published fields to verify that the locale has been successfully enabled.
Step 2: Retrieve a translatable productAnchor link to section titled "Step 2: Retrieve a translatable product"
To retrieve the first product eligible for translation, use the
translatableResources query with the parameters
first: 1 and
translatableContent response, include the
locale fields. You need their response values to write the translation in the next step.
Step 3: Write a translationAnchor link to section titled "Step 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
Step 4: Publish the localeAnchor link to section titled "Step 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.
Step 5: Visit your online storeAnchor link to section titled "Step 5: Visit your online store"
To view the translation on your online store, complete the following steps:
Navigate to the product's page on your online store.
esto your URL. For example,
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.
- Use the Storefront API to retrieve translated content.
- Explore an example for retrieving a list of shop locales with the GraphQL Admin API.
- Explore examples for retrieving translatable resources with the GraphQL Admin API.
- Learn how to support multiple currencies and languages in your theme.