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

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the read_products, write_translations, and write_locales access scopes. Learn how to configure your access scopes using Shopify CLI.
• You've created at least one product in your Shopify store.

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.

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.

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.

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.

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.

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

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

Anchor to Next stepsNext steps

• 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.