Translating content for online stores
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.
To follow this tutorial, you need the following:
- A partner account
- A development store with developer preview enabled
- A basic understanding of GraphQL
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_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.
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
Step 3: Enable a locale
shopLocaleEnable mutation to enable the
es locale and translate the product's title into Spanish. In the response, include the
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.
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
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".
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.
- In your development store's Shopify admin, go to Settings > Store Languages.
- 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")
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.