Translate content, also per market
Read a resource’s translatable content and digests with translatableResource, then save translations, optionally for one market, with translationsRegister.
- API
- Admin GraphQL API
- Operations
- translatableResource, translationsRegister
- Access scopes
- read_translations, write_translations
- API version
- 2026-10
- Last checked
In short
To translate a product, collection or other resource, query translatableResource for its translatable content: each key, its value and a digest. Then call translationsRegister with the locale, key, translated value and translatableContentDigest for each field. Add marketId to a translation to show it only in that market, for example Swiss German wording. The locale must be added to the store.
How to use it
- Send TranslatableProduct with the resource ID and keep the digest of each key you translate.
- Send TranslateProduct with one entry per locale and key, each with that key’s digest.
- Add marketId to entries that should apply only in one market; entries without it apply in every market.
- When the original text changes, its digest changes and the translation is marked outdated; register it again with the new digest.
Code
translatable-resource.graphqlquery TranslatableProduct($resourceId: ID!) {
translatableResource(resourceId: $resourceId) {
resourceId
translatableContent {
key
value
digest
locale
}
}
}
translatable-resource.variables.json{
"resourceId": "gid://shopify/Product/1234567890"
}
translatable-resource.response.json{
"data": {
"translatableResource": {
"resourceId": "gid://shopify/Product/1234567890",
"translatableContent": [
{"key": "title", "value": "Linen shirt", "digest": "<digest of title>", "locale": "en"},
{"key": "body_html", "value": "<p>Relaxed fit, washed linen.</p>", "digest": "<digest of body_html>", "locale": "en"}
]
}
}
}
translations-register.graphqlmutation TranslateProduct($resourceId: ID!, $translations: [TranslationInput!]!) {
translationsRegister(resourceId: $resourceId, translations: $translations) {
translations {
key
locale
value
market {
id
}
}
userErrors {
code
field
message
}
}
}
translations-register.variables.json{
"resourceId": "gid://shopify/Product/1234567890",
"translations": [
{
"locale": "tr",
"key": "title",
"value": "Keten gömlek",
"translatableContentDigest": "<digest of title>"
},
{
"locale": "de",
"key": "title",
"value": "Leinenhemd für die Schweiz",
"translatableContentDigest": "<digest of title>",
"marketId": "gid://shopify/Market/1234567890"
}
]
}
translations-register.response.json{
"data": {
"translationsRegister": {
"translations": [
{"key": "title", "locale": "tr", "value": "Keten gömlek", "market": null},
{"key": "title", "locale": "de", "value": "Leinenhemd für die Schweiz", "market": {"id": "gid://shopify/Market/1234567890"}}
],
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- A translation shows to buyers right away when its locale is published.
- Keys depend on the resource type: title, body_html, handle and meta_title for products, for example.
- Use translatableResources with a resourceType to page through all products, collections or other types.
- To remove translations, use translationsRemove.
Questions
- How do I add translations to Shopify with the API?
- Read the digests with translatableResource, then send translationsRegister with locale, key, value and translatableContentDigest for each field.
- What is the translatable content digest?
- A hash of the original text. It ties a translation to the version of the text it translates, so Shopify can mark it outdated when the original changes.
- Can I use different translations per market?
- Yes. Add marketId to the translation input. Buyers in that market see it; other markets keep the general translation.
Shopify documentation
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
