Shopify Product Translation API Full Implementation Guide (GraphQL + AI)

    Summary

    • Shopify translation apps are often expensive (costing over €700/month) and fail to deliver high-quality, brand-aware translations for niche products.

    • You can bypass these apps by using Shopify's GraphQL Admin API to manage where translations are stored, while plugging in your own AI engine (like GPT-4) to control translation quality.

    • This four-step, API-first approach gives you full control over cost and quality, keeping all translated content natively within Shopify's infrastructure.

    • For business documents beyond the storefront (like PDFs and contracts), Bluente's Translation API extends this programmatic control, translating complex files while perfectly preserving their original formatting.

    You've finally decided to go multilingual on Shopify. You've done the market research, you know Spanish-speaking or French-speaking customers are ready to buy — and then reality hits. The off-the-shelf translation apps are either astronomically expensive (with some costing over €700 per month), riddled with bugs that break checkout, or produce outputs that, as one Shopify developer put it, simply "miss the mark" — especially for niche products where generic translation just doesn't cut it.

    The good news? You don't need an expensive app to run a professional multilingual Shopify store. Shopify's GraphQL Admin API gives you everything you need to manage where translations live. You just need to wire in your own AI engine to control how good they are.

    The Two-Layer Translation Problem

    Here's the architectural reality of the Shopify product translation API:

    • Layer 1 — The "Where" (Shopify's GraphQL Admin API): Shopify provides a robust, native framework for storing and organizing translated content. It knows which product a translation belongs to, which locale it maps to, and which field it corresponds to (title, body_html, metafields, etc.). This is the structural backbone.

    • Layer 2 — The "How Good" (Your External AI Engine): Shopify doesn't perform the translation itself. The quality, tone, and accuracy of every translated string depend entirely on the external service you feed your content into — whether that's DeepL, Google Translate, or an LLM like OpenAI's GPT-4.

    Most translation apps bundle these two layers together and charge a premium for the privilege. Build your own pipeline, and you control both — choosing the best AI for your niche, managing costs at scale, and keeping your translations natively inside Shopify's infrastructure (no third-party CDN hosting your storefront data).

    Here's the complete four-step workflow to make it happen.

    Step 1: Enable a New Locale in Your Store

    Before Shopify can store translations, it needs to know which languages your store supports. You do this with the shopLocaleEnable mutation.

    A locale can be a simple language subtag ("es" for Spanish) or a language-region combination ("es-MX" for Mexican Spanish). Using a region-specific locale is useful when your product copy needs to reflect local terminology or currency context.

    # Enable Spanish as a supported locale
mutation enableLocale($locale: String!) {
  shopLocaleEnable(locale: $locale) {
    shopLocale {
      locale
      name
      published # false by default — we'll publish it in the final step
    }
    userErrors {
      field
      message
    }
  }
}

# Variables:
# {
#   "locale": "es"
# }

    Note: Always check userErrors in your mutation responses. Common issues here include passing an unsupported locale code. You can find the full list of supported locales in Shopify's developer documentation.

    Step 2: Query and Extract Translatable Product Content

    With your locale enabled, the next step is pulling out the content that needs translating. The translatableResources query is specifically designed for this — it returns only the fields Shopify considers translatable, along with metadata your pipeline will need later.

    # Fetch translatable content for one product
{
  translatableResources(first: 1, resourceType: PRODUCT) {
    edges {
      node {
        resourceId  # e.g., "gid://shopify/Product/1234567890"
        translatableContent {
          key     # "title", "body_html", "metafield.custom.specifications", etc.
          value   # The original text string to be translated
          digest  # A hash of the current content version
          locale  # The source language, e.g., "en"
        }
      }
    }
  }
}

    Pay close attention to the digest field. It's a hash of the current content version, and it's your best friend for handling partial updates. Store the digest alongside your translations in your database. When a product is updated, re-query and compare digests — only re-translate fields whose digest has changed. This prevents the expensive "full retranslation on every minor edit" problem that plagues most translation apps.

    The key field tells you exactly what you're dealing with. Standard product fields include title and body_html, but metafields follow a pattern like metafield.{namespace}.{key} — so a custom spec field might come back as metafield.custom.specifications. This matters when you're constructing your write-back payload in Step 4.

    Step 3: Send Extracted Strings to Your AI Translation Engine

    This is where Layer 2 comes in — and where the quality difference between a custom pipeline and a generic app becomes obvious.

    Take the value strings from Step 2 and POST them to your chosen AI translation engine. Different services offer distinct advantages:

    • Specialized Translation APIs — Often deliver high accuracy for specific language pairs or technical content.

    • General-Purpose Cloud Services — Offer broad language coverage and are built for high-volume batch processing.

    • Large Language Models (LLMs) like OpenAI's GPT-4/4o — Best-in-class for nuanced, brand-aware copy, and the only option that lets you pass a custom prompt with context.

    Using an LLM gives you capabilities no off-the-shelf app can match. You can prepend a system prompt with brand-specific instructions like:

    "You are a luxury fashion copywriter. Translate the following product description into Spanish. Ensure 'canvas' is rendered as 'lona', not 'lienzo'. Maintain an elevated, aspirational tone throughout."

    This directly solves what many Shopify merchants describe as their biggest frustration: "we've hit a limit when it comes to translation quality, especially for our niche."

    Translation Apps Too Pricey?

    Handling HTML in body_html

    The body_html field is where things get tricky. As developers have noted, "preserving inline code (HTML, liquid, custom app snippets) during translation is hard to do reliably." The fix is to pre-process the value before sending it to your AI:

    1. Use a regex or an HTML parser to identify and extract all HTML tags, {{ }} Liquid variables, and {% %} Liquid blocks

    2. Replace them with numbered placeholders: [TAG_1], [TAG_2], etc.

    3. Send the cleaned text to your translation API

    4. After receiving the translation, substitute the placeholders back with the original markup

    This gives you clean, translatable text without ever risking a broken storefront template.

    Step 4: Write Translations Back to Shopify

    With translated strings in hand, you're ready to write them back using the translationsRegister mutation. This mutation associates each translated value with a specific product, field key, and locale.

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

# Variables:
# {
#   "id": "gid://shopify/Product/1234567890",
#   "translations": [
#     {
#       "locale": "es",
#       "key": "title",
#       "value": "La Gran Camisa"
#     },
#     {
#       "locale": "es",
#       "key": "body_html",
#       "value": "<p>Esta es una descripción traducida del producto.</p>"
#     },
#     {
#       "locale": "es",
#       "key": "metafield.custom.specifications",
#       "value": "100% algodón, fabricado en Portugal"
#     }
#   ]
# }

    A few things to keep in mind:

    • You can batch multiple field translations in a single translationsRegister call for the same resourceId. Do this — it's more efficient than firing one mutation per field.

    • If you need to update a translation later, calling translationsRegister again with the same resourceId, locale, and key will overwrite the existing value.

    • Because Shopify stores these translations natively, there's no third-party CDN involved — your translated content is delivered as part of Shopify's standard storefront infrastructure.

    Going Live: Publishing and Verifying Your Translations

    Enabling a locale in Step 1 doesn't make it visible to customers. You need to explicitly publish it using the shopLocaleUpdate mutation:

    mutation publishLocale {
  shopLocaleUpdate(locale: "es", shopLocale: { published: true }) {
    userErrors {
      message
      field
    }
    shopLocale {
      locale
      published
    }
  }
}

    Once published, verify your work by navigating directly to the localized URL on your storefront: your-store.myshopify.com/es/products/your-product-handle. The translated title, description, and any translated metafields should render immediately.

    If you're using Shopify Markets, make sure the locale is also assigned to the correct market in your Markets settings — a locale can be enabled globally but still need to be mapped to a market to be served to the right customers.

    Beyond the Storefront: Translating Your Entire Business Ecosystem

    Once your product translation pipeline is running, you'll quickly realize that your Shopify storefront is only part of the picture. A growing e-commerce brand runs on a much wider ecosystem of documents: technical spec sheets in PDF, supplier contracts in DOCX, marketing brochures in PPTX, compliance documents, invoices — the list goes on.

    This highlights a common challenge: the need for document translation capabilities that offer the same high accuracy as leading AI engines, but with API access and robust format preservation. The Shopify API workflow we've built handles strings perfectly — but it's not designed to ingest a 40-page PDF supplier agreement and return a formatted, translated document your procurement team can actually use.

    This is where file-based translation pipelines come in. Bluente's Translation API is purpose-built for exactly this use case — a RESTful JSON API that accepts 22 document formats (PDF, DOCX, XLSX, PPTX, HTML, XML, DITA, and more) and returns translated files with pixel-perfect layout preservation.

    The key differentiators that matter for e-commerce and operations teams:

    • Layout preservation at the document level: Tables, charts, numbering, headers, and footers stay exactly where they are. There's no need to "deconstruct the content and rebuild" after translation — a common pain point for anyone who has tried passing a product spec sheet through a generic translation API.

    • Advanced OCR for scanned files: If your supplier sends over a scanned PDF invoice or a photographed spec sheet, Bluente's OCR layer makes the text selectable, editable, and translatable — without any manual transcription.

    • Batch processing and webhooks: Submit multiple documents in a single API call and receive webhook notifications when jobs complete, making it straightforward to build automated pipelines for high-volume workflows.

    • Enterprise-grade security: With SOC 2, ISO 27001:2022, and GDPR compliance, Bluente is built to handle the sensitive contracts and financial documents that your legal and finance teams need to keep secure.

    The result is a unified, end-to-end translation strategy: Shopify's GraphQL API handles your storefront strings (product titles, descriptions, metafields), while Bluente's Translation API handles your structured business documents — both programmatically, both at scale, and both without requiring a developer to manually reformat anything after the fact.

    Docs Beyond Your Storefront?

    Taking Full Control of Your Global E-commerce Strategy

    The four-step GraphQL workflow covered in this guide — shopLocaleEnable → translatableResources → AI translation → translationsRegister — gives you something no off-the-shelf app can: complete control over both layers of the translation problem.

    You own the translation quality (because you chose the AI). You own the storage (because it lives natively in Shopify, not on a third-party CDN). And you own the economics — no more paying 300–700€/month for a black-box SaaS platform when your content volume makes that math impossible to justify.

    For teams ready to extend that same level of control to the rest of their business documents, Bluente's Translation API brings the same API-first philosophy to file-based translation — preserving layouts, supporting OCR, and scaling with your operation.

    Global e-commerce is a two-front challenge. Now you have the tools to tackle both.

    Published by
    Back to Blog
    Share this post: Twitter•LinkedIn