Translating content for an online store
This tutorial explains how to use the GraphQL Admin API to create and retrieve translated content for Shopify resources. If you are unfamiliar with GraphQL, then you should review the Shopify and GraphQL guide before starting this tutorial.
For this tutorial, you'll use the GraphQL Admin API to enable the es
locale on your store, retrieve a product, and then translate the product's title. Finally, you'll publish the new locale and view the translated content on your store.
Requirements
This tutorial has the following requirements:
- a Shopify store or development store
- at least one product in your store
Step 1: Install the Shopify GraphiQL App
Install the Shopify GraphiQL app on your store. You can use the Shopify GraphiQL app to build and execute GraphQL queries and mutations on your store. When installing the GraphiQL app, make sure that you enable the translations and locales write
access scope.
Step 2: Enable a locale
Use the shopLocaleEnable
mutation to enable the es
locale on your store. In the shopLocale
response, include the locale
, name
, and published
fields to verify that the locale has been successfully enabled.
By default, newly enabled locales are not published.
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 3: 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.
Query
{
translatableResources(first: 1, resourceType: PRODUCT) {
edges {
node {
resourceId
translatableContent {
key
value
digest
locale
}
}
}
}
}
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 4: Write a translation
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.
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
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.
Step 6: Visit the online store to see your translation
To view the translation, navigate to the product's page on your online store. Make sure you add an es
to your URL, for example, myshopifystore.com/es/products/great-shirt
.