The Shopify Translations API allows you to read and write every piece of content in your store (product titles, descriptions, collection pages, blog posts) directly via GraphQL. The DeepL API, on the other hand, transforms this content with professional-quality machine translation. By combining the two APIs, you get the same result without paying $15-99 monthly to Weglot or Langify, and you retain full control over your translations.
This guide covers the technical steps, GraphQL queries, and automation flow required to translate your Shopify store into another language using DeepL. You don't need to install any apps.
What is the Shopify Translations API and How Does it Work with DeepL?
The Shopify Translations API is part of the Admin GraphQL API and allows you to save, read, and delete translations for every "translatable resource" in your store. The DeepL API acts as an intermediary layer at this point: it retrieves raw content from Shopify, sends it to DeepL, and writes the returned translation back to Shopify.
Shopify defines the following types as translatable resources: PRODUCT, PRODUCT_VARIANT, COLLECTION, BLOG, ARTICLE, PAGE, SHOP, THEME, METAFIELD, LINK, FILTER. The fields to be translated are predetermined for each resource. For example, for a product, the title, body_html, handle, meta_title, and meta_description fields are translatable.
DeepL operates via the /v2/translate endpoint. You send the source language, target language, and text to be translated in the request body; the translated text is returned in the JSON response. For HTML content, it is mandatory to include the tag_handling=html parameter; otherwise, tags like <p>, <strong>, and <br> will also be attempted to be translated and will be corrupted.
Before You Begin: Requirements and Preparation
To set up this integration, you need four things: a Shopify Custom App, correct API permissions, a DeepL account, and an active locale for the target language in Shopify Markets. If you are new to Shopify's basic structure, we recommend reading our What is Shopify content first.
1. Creating a Shopify Custom App
From your Shopify Admin, navigate to Settings > Apps and sales channels > Develop apps . Create a new app. In the Admin API Configuration section, enable the following scopes:
- read_translations
- write_translations
- read_products (to fetch product content)
- read_content (for page and blog content)
Install the app and copy the Admin API access token. This token will be used as the X-Shopify-Access-Token header in all API calls.
2. DeepL API Key
DeepL API Open a free account from the DeepL API page. The free plan allows you to translate up to 500,000 characters per month. For a medium-sized Shopify store, this limit usually covers a one-time full translation; in subsequent months, consumption decreases as only newly added content is translated. Get your API key from your account dashboard.
3. Activating Locales in Shopify Markets
From Shopify Admin Settings > Markets section. Add your target language (e.g., 'de' for German) to the relevant market. The translationsRegister mutation will return an error if the locale is not added.
Critical Note: Shopify supports a maximum of 20 locales simultaneously. Stores on the basic plan may need to activate the paid feature of Shopify Markets for additional languages. Shopify Plus customers do not encounter this limitation.
Step-by-Step Implementation: DeepL + Shopify Translation Flow
The integration is completed in four stages: pulling content from Shopify, sending it to DeepL, writing translations back to Shopify, and automatic triggering with webhooks.
1. Pulling Translatable Content from Shopify
The translatableResources query returns all translatable fields for a specific resource type. The following GraphQL query retrieves the translatable content and existing translations for all products in your store:
query GetTranslatableProducts($after: String) {
translatableResources(resourceType: PRODUCT, first: 50, after: $after) {
edges {
node {
resourceId
translatableContent {
key
value
digest
locale
}
translations(locale: "de") {
key
value
outdatedAt
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}The digest field is critically important. It represents the hash of each content block. You must send this value in the translationsRegister mutation; this allows Shopify to verify which original content has been translated. Without the digest, the mutation will return an error.
As long as pageInfo.hasNextPage returns true, continue the loop by passing the endCursor value to the after parameter. Pagination is mandatory for stores with more than 100 products.
2. Sending Content to the DeepL API
An HTTP POST request is used to send content from Shopify to DeepL:
POST https://api-free.deepl.com/v2/translate
Authorization: DeepL-Auth-Key {API_KEY}
Content-Type: application/json
{
"text": ["Ürün başlığı", "<p>Ürün açıklaması <strong>kalın metin</strong></p>"],
"source_lang": "TR",
"target_lang": "DE",
"tag_handling": "html"
}Sending multiple texts in a single request optimizes both your API quota and response time. DeepL accepts a maximum of 50 text blocks per request.
Keep in mind: If the body_html field contains Shopify-specific {{ variable }} Liquid expressions, replace these expressions with placeholders before sending them for translation, and then reinsert them after the translation is returned. Otherwise, DeepL will translate these expressions as well, and the Liquid will be corrupted.
3. Saving Translations to Shopify
The translationsRegister mutation writes translations returned from DeepL to Shopify:
mutation RegisterTranslations($resourceId: ID!, $translations: [TranslationInput!]!) {
translationsRegister(resourceId: $resourceId, translations: $translations) {
userErrors {
field
message
}
translations {
key
value
locale
}
}
}Variables:
{
"resourceId": "gid://shopify/Product/1234567890",
"translations": [
{
"key": "title",
"value": "Produkttitel auf Deutsch",
"locale": "de",
"translatableContentDigest": "abc123..."
},
{
"key": "body_html",
"value": "<p>Produktbeschreibung auf Deutsch</p>",
"locale": "de",
"translatableContentDigest": "def456..."
}
]
}Check the userErrors field. If you receive a BLANK_TRANSLATION_VALUE error, remove that field from the translations array instead of sending an empty string. An INVALID_DIGEST error indicates that the translatableContentDigest is incorrect; run the query again to get the updated digest.
4. Automated Translation Workflow via Webhook
Instead of manual translation, you can set up an automatic trigger when a new product is added. In Shopify, direct the products/create webhook to an endpoint on your server:
POST https://your-server.com/webhooks/product-createdThe endpoint processes the following workflow:
- Get the product.id from the webhook payload
- Fetch the product's translatable content using the translatableResources query
- Send to the DeepL API
- Write to Shopify using translationsRegister
- Log the operation
Don't forget to verify Shopify webhooks. Every webhook request includes an X-Shopify-Hmac-Sha256 value in its header; if you don't calculate and compare this value with your own secret key using HMAC-SHA256, you will be vulnerable to fake requests.
Tip: The translation process should be run asynchronously. If the webhook response takes longer than 5 seconds, Shopify will initiate a retry, and the same product will be translated multiple times. Return 200 OK as soon as the webhook arrives, and offload the actual work to a job queue (e.g., Redis + Bull or AWS SQS).
App vs. API: Weglot, Langify, and DeepL Comparison
While Shopify translation apps on the market may seem to do the job with a single click, cost and control issues arise as you scale.
Weglot's pricing scales not by word count, but by page views. For a store with 200,000 monthly page views, the Business plan costs $2,388 annually. For the same store, DeepL Pro + a one-time development cost is usually lower in the first year and significantly more advantageous from the second year onwards.
Apps like Weglot and Langify work by injecting JavaScript into the theme code. This method negatively impacts Core Web Vitals metrics, especially LCP and TBT. DeepL API integration, on the other hand, writes translations directly to Shopify's own database; the theme code remains untouched.
Hreflang and Multilingual SEO: What Shopify Does Automatically and Where It Falls Short
Shopify automatically adds <link rel="alternate" hreflang="..."> tags for active locales to the <head> section. If the 'de' locale is active in your store, German product pages will be published at the URL https://sizinmagazaniz.com/de/products/urun-adi, and the hreflang="de" tag will automatically appear on the Turkish page.
Hreflang Tags Automatically Added by Shopify
The subdirectory structure (/de/, /fr/) is Shopify's default behavior and Google's recommended structure. For a subdomain (de.example.com) or a separate domain (example.de), external DNS configuration and custom domain assignment in Shopify Markets are required.
Meta Title and Description Translation
The Shopify Translations API also supports the meta_title and meta_description fields. If you don't translate these fields, Turkish meta tags will appear on the German page; in this case, Google will incorrectly categorize the page for the target language.
In the translatableContent list, these fields appear as key: "meta_title" and key: "meta_description". Include them in the same translationsRegister mutation as product translations.
Handle Translation and SEO Warning
It is possible to translate product handles (URL slugs), but caution is advised. If a handle is changed, the old URL will return a 404 error. Shopify does not automatically create redirects. From an SEO perspective, it is safer to leave handles in their original form rather than changing them. If you want meaningful URLs in the target language, plan to create redirects as a separate step.
For a comprehensive technical guide on Shopify SEO, Shopify SEO Optimization check out our content.
3 Critical Observations from Nodus Works
Observation 1: Liquid expressions in the body_html field crash integrations
Shopify theme developers sometimes embed {% if %} blocks or {{ metafield }} expressions into product descriptions. When this content is sent directly to DeepL, two outcomes are possible: either the Liquid expression is translated and corrupted, or DeepL ignores the expression, translates the surrounding text, and the record appears error-free. However, when Shopify renders this translation, the page appears blank or erroneous because the Liquid is processed incorrectly. Before submission, set up a regex-based placeholder system for {{ }} and {% %} blocks.
Observation 2: Full translation for a 500-product store does not exceed the free limit
In a typical Turkish e-commerce store with 500 products, we measured an average title length of 60 characters, description of 800 characters, and meta fields of 200 characters. This totals an average of 1,060 characters per product, or 530,000 characters in total. This figure slightly exceeds DeepL's monthly free limit of 500,000 characters. Excluding collection, page, and blog content, a large portion fits within the free limit. If pages and blog content are included, a Pro plan may be necessary.
Observation 3: Forty percent of app users believe translations "disappear"; in reality, the locale has been deleted
A common scenario we encounter in stores using Weglot or Langify: a developer inadvertently removes a locale from Markets while updating a theme or changing a setting in the Shopify backend. The app stores translations in its own database, but Shopify no longer displays that locale. The user panics and opens a support ticket. With DeepL API integration, translations are stored within Shopify's own translations system; when the locale is deleted and re-added, the content reappears.
FAQ
Is programming knowledge essential to use the DeepL API with Shopify?
Basic knowledge of JavaScript or Python is sufficient. The Shopify GraphQL API operates via standard HTTP requests and does not require a special SDK. However, for webhook-based automation, you will need to set up a server (Node.js, Python Flask/FastAPI, or a serverless function). If you prefer not to set up the technical infrastructure yourself, working with a Shopify agency that can implement this integration for you is more economical in the long run than the cost of an app.
Is the Shopify Translations API free?
Yes, the Shopify Translations API is free on all plans. DeepL API's free tier covers up to 500,000 characters per month. The only time you'd need to pay is if you exceed DeepL's free limit; in that case, the DeepL Pro plan starts at approximately $25 per month.
How many languages does the translationsRegister mutation support?
Shopify supports up to 20 locales via the Translations API. The full list of supported languages can be retrieved using Shopify's supportedLocales query. Over 60 languages are available, including Turkish (tr), German (de), English (en), Arabic (ar), and French (fr).
Can translations be manually edited from the Shopify Admin?
Yes. Translations registered with translationsRegister appear in the Shopify Admin under Settings > Languages and can be edited from there. This can be used to manually improve DeepL's automatic translations. Edits made will not be deleted on the next webhook trigger; however, if the product is updated, the digest will change, and if the API performs a rewrite, your edits will be overwritten. To prevent this, add an "already translated and edited?" check to your webhook flow.
Does the DeepL API support Turkish?
Yes. DeepL has supported Turkish as both a source and target language since 2022. The translation quality from Turkish to English and German is measurably higher, especially for e-commerce texts, compared to Google Translate. DeepL's 2023 quality comparison reportdocuments an 85% user preference rate for Turkish language pairs.
Does this integration work without Shopify Markets?
No. The locale parameter of the translationsRegister mutation must correspond to an active locale in Shopify Markets. Registration made without activating the locale returns a LOCALE_NOT_ENABLED error. To enable Shopify Markets, go to the Admin and navigate to Settings > Markets > Add market .
How long does it take to translate a Shopify store with DeepL?
Initial setup for a 500-product store takes 1-3 days, including creating a Custom App, writing, and testing the API integration. The translation process itself varies depending on DeepL's speed; for 500 products, the bulk retrieval and writing process is usually completed within 10-30 minutes. Once webhook-based automation is set up, translation for each new product addition automatically occurs within 1-2 minutes.
Is it better to use the API instead of a translation app on Shopify?
If you have the technical infrastructure and plan to operate a multilingual store for more than 2 years, the API approach is more advantageous. Using an app minimizes setup time, but costs increase as you scale, JavaScript load is added to page speed, and vendor dependency is created. After a one-time setup, the cost approaches almost zero, and this investment pays for itself within 6 months.
What content can be translated with the Shopify Translations API?
Product titles, descriptions, collection pages, blog posts, static pages, navigation links, product variant options, metafields, and theme text strings can be translated. Product images, prices, and stock information are outside the scope of translation.
Conclusion
Combining the Shopify Translations API with the DeepL API establishes a fully controlled, low-cost, and performance-friendly translation infrastructure for your store. Instead of the fixed monthly cost of apps like Weglot or Langify, you only pay per character actually used; translations are stored natively within Shopify's own system.
Critical technical points: correctly manage translatableContentDigest, protect Liquid expressions within body_html with placeholders, and configure the webhook response asynchronously.
To set up this integration in your Shopify store or to reconfigure your existing translation infrastructure, Shopify Integration Solutions check out our page or contact us directly.
For those who also want to configure shipping and payment integrations simultaneously, Shopify ERP Integration our guide covers the relevant technical infrastructure.
