Manage app translations with the GraphQL Admin API

This guide explains how to use the GraphQL Admin API to create and retrieve translated content for Shopify resources. It also covers how to retrieve translated content using the Storefront API. For example, you might add translations of product information and email notification templates using the GraphQL Admin API so a merchant can send customers email notifications in multiple languages. Those translations can then be retrieved by either the GraphQL Admin API or the Storefront API.

GraphQL Admin API translation access scopes

To use the GraphQL Admin API to create or retrieve translated content, your app needs to request the read_translations and write_translations access scopes for a Shopify store. For more information on requesting access scopes when your app is installed, see OAuth.

Storefront API translation header

To use the Storefront API to retrieve translated content, your app needs to use the Accept-Language HTTP request header when sending queries. The following example header enables Spanish translations to be returned using the Storefront API: Accept-Language: es

GraphQL Admin API translatable resource types

The following resource types and fields are translatable:

Type Fields
Collection title, body_html, meta_title, meta_description
Email template title, body_html
Link title
Metafields (non-private) value
Online store article title, body_html, summary_html, meta_title, meta_description
Online store blog title, meta_title, meta_description
Online store page title, body_html, meta_title, meta_description
Online store theme dynamic keys based on theme data
Payment gateway name
Product title, body_html, meta_title, meta_description
Product option name
Product variant title, option 1, option 2, option 3
Shop meta_title, meta_description
Shop policy body
SMS template body

Retrieve a list of translatable resource types

TranslatableResourceType contains a list of the resource types that are translatable. You can use the following query to list each of those types:

Storefront API translation resources

The following resources include properties that can be retrieved using the Storefront API:

Type Fields
Collection title, descriptionHtml, description
Metafield value
Article title, content, contentHtml, excerpt, excerptHtml
Blog title
Page title, body
Product title, descriptionHtml, description
ProductOption name, values
ProductVariant title, selectedOptions
ShopPolicy body

Retrieving translations

You can use the translateableResources connection to retrieve a list of translatable resources, their translatable content, and their existing translations in various languages. You can also retrieve all translations for a locale, regardless of resource type.

Retrieve a list of translatable resources by their type

The following query retrieves a list of translatable resources that are products. For each product, the query retrieves the content that can be translated in the translatableContent field.

The response shows that the White T-Shirt product with the ID "gid://shopify/Product/1" has content that can be translated, including its title and body HTML.

The key field associates translatable content with its translations. The value field shows the translatable content itself. The digest field is the translatable content's unique identifier. When you create a translation, the mutation needs to include the translatable content's digest value in the translatableContentDigest field.

Retrieve translations for a resource type and locale

Like the example above, this query retrieves a list of products and their translatable content. This query also includes the translations field for each product, which retrieves any existing translations.

The field takes the argument locale, which spec