Translating content for online stores

This page was printed on Oct 16, 2019. For the current version, visit https://help.shopify.com/en/api/tutorials/translating-content-for-online-store?itcat=partner_blog&itterm=shopify_unite_2019_announcements.

Shopify natively supports selling in multiple languages. The following tutorial describes how to use the Shopify Admin GraphQL API to create a multi-language shopping experience for your users.

Requirements

To follow this tutorial, you need the following:

Step 1: Install the Shopify GraphiQL App

Install the Shopify GraphiQL app on your development store with developer preview enabled. We’ll use the Shopify GraphiQL app to build and execute GraphQL queries and mutations on your development store. When installing the GraphiQL app, make sure that you enable the write_translations and write_locales access scopes.

The install screen for Shopify GraphiQL App with write translations and locales toggled.

Step 2: Retrieve a translatable resource

In this tutorial, you'll retrieve a product from your store and then translate it’s title. If you don’t have at least one product created, then you can follow this guide to add a new product.

Use the following query to retrieve the first product available for translation. The translatableContent field returns all the fields on the product resource that can be translated.

Run in GraphiQL

Query

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

If you have at least one product on your development store, then you’ll receive a response with all the available translatable fields on the product, including title.

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"
                            }
                        ]
                    }
                }
            ]
        }
    }
}

Step 3: Enable a locale

Use the shopLocaleEnable mutation to enable the es locale and translate the product's title into Spanish. In the response, include the locale, name, and published fields to verify that the locale has been successfully enabled, but not published to the online store.

By default, newly enabled locales are not published to the online store. Shops are limited to 5 enabled locales.

Run in GraphiQL

Variables

{
  "locale": "es"
}

Mutation

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

Response

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

Step 4: Write a translation

Now that the Spanish locale is enabled on your development store, you can translate the product’s title in Spanish. You can use the translationsRegister mutation to create a new translation for any translatable resource. When you create a translation, you need to include the the digest of the original content in the translatableContentDigest field. The digest is returned in translatableContent of the product that you queried in Step 2.

For example, to create a translation for a product titled “Great shirt” with digest dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9, you need to include the mutation variable "translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9". The translation is specified in the value field. In this case, we're translating "Great shirt" to "Camiseta buena".

Run in GraphiQL

Variables

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

Mutation

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

Response

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

Step 5: Publish the locale

So far, we’ve added a new Spanish locale to your development store and translated the title of a product. Next, we'll publish the es locale so that the translated title is viewable by anyone shopping on your online store.

You can publish a locale from the Shopify admin or by using the GraphQL Admin API. To learn more about publishing locales with the API, refer to Managing shop locales. Shops are limited to 5 published locales.

  1. In your development store's Shopify admin, go to Settings > Store Languages.
  2. In the Translated Languages section, click Publish next to the Spanish locale.

The admin showing the unpublished Spanish locale.

Step 6: Visit the online store to see your translation

To view your translation, navigate to the product page on your online store. Make sure you add an es to the path in your URL (e.g "example.com/es/products/great-shirt")

What’s next?

We are working on enhancing this feature by adding support for a language switcher, SEO tags & more. Keep an eye on our developer changelog for updates.

Additional information

Sign up for a Partner account to get started.

Sign up