Building a Custom Shopify Translation Management App with AI
A purpose-built multilingual product editor for Shopify merchants scaling across markets
The Opportunity
Managing a multilingual Shopify store is deceptively complex. On the surface, translating product content sounds straightforward — but when you factor in multiple content types (plain text, HTML descriptions, rich text metafields, JSON), dozens of languages, team workflows, and Shopify's own API constraints, the complexity compounds fast.
The client needed a scalable, in-store translation tool that gave their team full control over product content across all their active markets — without leaving the Shopify admin, and without relying on expensive third-party translation apps that don't fit every workflow.
We built it from scratch.
The Solution
We developed a custom Shopify app embedded directly in the merchant's admin, built on the Shopify App Bridge and Shopify's official Translations API. The app gives editors a clean, side-by-side interface to translate all product fields — including metafields — for every active language in the store.
Rather than a generic one-size-fits-all tool, this app was designed around real editorial workflows: who is working on what, how progress is tracked, and how to move quickly through a large catalog without losing work.
Key Features
AI-Powered Translation Each field has a one-click AI translate button powered by OpenAI's GPT-4o-mini model, tuned specifically for e-commerce product copy. It handles plain text, HTML, and rich text fields correctly — respecting formatting and tone. Translations are drafted for review before saving, never applied blindly.
Full Content Type Support Product fields vary in their content type — titles are plain strings, descriptions are HTML, and metafields can be rich text JSON or multi-line text. The app correctly detects and renders each type: HTML fields get a WYSIWYG editor with formatting controls, rich text fields are validated against Shopify's JSON structure, and plain text fields use simple inputs. This eliminates data corruption that commonly occurs when these types are treated interchangeably.
Metafield Translation Beyond standard product fields, the app fetches and translates all translatable metafields linked to each product — including custom metafield definitions. Keys are disambiguated at the resource level to avoid collisions between product fields and metafield values with the same key name (a common silent failure in naive implementations).
Team Collaboration & Claiming Editors can claim batches of products, signaling to teammates which products they are actively working on. This prevents duplicated effort in larger teams and is stored per-shop in the database.
Bulk Apply A specific field value (e.g. a delivery notice or a legal disclaimer) can be pushed to all products in the catalog at once for a given language — saving hours of repetitive editing.
Progress Tracking Each product shows a real-time translation progress indicator per language, with visual status (not started / in progress / complete), making it easy to prioritize work and report on catalog readiness.
Auto-Save & Navigation An optional auto-save mode saves translations automatically when navigating between products, so editors can move fast without worrying about losing changes.
Technical Challenges Resolved
Shopify GraphQL 250-Item Limit Shopify's API caps aliased queries at 250 items per request. For stores with many products and many languages, this limit is hit easily when fetching all translations in a single query. We solved this with a batching layer that splits translation queries into chunks of 200 and merges the results transparently.
Reliable Content Type Detection Shopify's translatableContent endpoint returns a type field, but it is unreliable for metafields — where it often returns JSON regardless of the actual content structure. We implemented a multi-signal type resolver: field key name, raw API type, metafield definition type, and heuristic JSON inspection. This ensures the right editor (HTML, rich text, or plain text) is always shown.
Metafield Key Disambiguation When a product and one of its metafields both have a translatable field with the key value, a naive implementation merges them and loses data. We prefix metafield translation keys with the metafield's resource GID, keeping all keys unique across the translation store.
Sequential Save Queue Saving all languages at once risks race conditions and partial writes. We implemented a sequential save queue: each locale is saved one at a time, with the next save only starting after the previous one confirms success or failure — including error surfacing per locale without blocking the rest of the queue.
GraphQL Mutation Variable Injection Shopify's translationsRegister mutation requires proper GraphQL typed variables — not inline JSON literals. We dynamically construct aliased mutation queries with correctly-typed variable declarations, which avoids a common GraphQL parse error ({} vs {key: "v"}) and handles any number of resource types in a single round-trip.
Tech Stack
- React Router v7 (Shopify app framework)
- Shopify Admin API + Translations API (GraphQL)
- OpenAI GPT-4o-mini for AI-assisted translation
- Prisma + SQLite/PostgreSQL for session and collaboration state
- Shopify App Bridge for embedded admin UI
- TypeScript throughout
The Result
A fully embedded, production-ready Shopify translation app tailored to the client's catalog and team — with AI acceleration, full metafield support, team coordination features, and robust handling of Shopify's API constraints. The client's team can now manage multilingual content at scale directly inside their Shopify admin, without third-party subscriptions or manual workarounds.