How to Translate Shopify Metafields, Metaobjects and Custom Data

Most Shopify merchants translate their product titles and descriptions and call it done — then wonder why their German or French storefront still shows raw English text in size guides, ingredient lists, custom badges, and specification tables. Those fields are almost always metafields or metaobjects, and they require a different approach entirely. Knowing how to translate Shopify metafields correctly is the difference between a store that looks professionally localized and one that obviously isn't.

What Are Metafields, Metaobjects, and Custom Data?

Before touching the API, it helps to be precise about what you're dealing with, because Shopify uses these terms in overlapping ways.

Metafields attach extra structured data to a specific resource — a product, variant, collection, page, article, or even a shop-level setting. A size guide stored as product.metafields.custom.size_guide is a classic example. Metafields have a namespace, a key, and a type (single-line text, multi-line text, JSON, file reference, etc.).

Metaobjects are reusable structured content types you define yourself. Think of them as mini content models: a "Testimonial" metaobject might have fields for author name, body text, rating, and a photo. You can attach multiple instances to products or render them anywhere via the Storefront API. Shopify added full metaobject support to the Translations API in API version 2023-04.

Custom data is the umbrella term Shopify uses in the admin UI to refer to both metafields and metaobjects together. For translation purposes, the distinction matters: metafields are translated via translatableResource on their parent resource, while metaobjects have their own translatableResource type.

Out of scope: Metafields on Orders and Customers are not exposed through Shopify's storefront rendering pipeline, so they are not translatable via the Translations API and aren't relevant to multilingual storefronts. If you store data on those resources, it stays admin-only and doesn't need localization.

---

Step 1 — Identify Which Metafields and Metaobjects Are Translatable

Not every metafield type can be translated. Shopify only exposes fields with translatable content types. The ones you can translate include:

• single_line_text_field
• multi_line_text_field
• rich_text_field

The ones you cannot translate (they contain structured data, not human-readable strings):

• number_integer, number_decimal
• boolean
• date, date_time
• file_reference, product_reference, collection_reference, metaobject_reference
• url (usually)

To see exactly which fields Shopify is exposing as translatable for a given resource, query translatableResource in the GraphQL Admin API:

query {
  translatableResource(resourceId: "gid://shopify/Product/123456789") {
    resourceId
    translatableContent {
      key
      value
      digest
      locale
    }
  }
}

The translatableContent array will only include fields Shopify considers translatable — including any eligible metafield keys. If a metafield isn't in this list, it cannot be translated through the Translations API regardless of what a third-party app promises.

---

Step 2 — Translate Metafields Using the registerTranslations Mutation

Once you know which keys are available, you register translations using the translationsRegister mutation. Here is a real, working example that translates two metafields on a product — a material description (custom.material) and a care instructions field (custom.care_instructions) — into French:

mutation {
  translationsRegister(
    resourceId: "gid://shopify/Product/123456789"
    translations: [
      {
        locale: "fr"
        key: "metafield.custom.material"
        value: "100 % coton biologique"
        translatableContentDigest: "abc123digestfromquery"
      }
      {
        locale: "fr"
        key: "metafield.custom.care_instructions"
        value: "Laver à 30 °C, ne pas utiliser de sèche-linge"
        translatableContentDigest: "def456digestfromquery"
      }
    ]
  ) {
    translations {
      key
      value
      locale
    }
    userErrors {
      field
      message
    }
  }
}

Two things to get right:

1. The key format. For metafields, Shopify expects the key in the format metafield.{namespace}.{key} — exactly as it appears in the translatableContent response. Guessing the key format is the most common reason translations silently fail.
2. The translatableContentDigest. This is a hash Shopify returns from the translatableResource query. It acts as a version stamp. If the source content changes and the digest changes, any existing translation is automatically marked outdated. You must re-fetch the digest before registering a new translation — you cannot reuse a cached one.

---

Step 3 — Translate Metaobjects

Metaobjects follow the same pattern but target a different resource type. First, query the metaobject's translatable content:

query {
  translatableResource(resourceId: "gid://shopify/Metaobject/987654321") {
    resourceId
    translatableContent {
      key
      value
      digest
      locale
    }
  }
}

Then register translations field by field using translationsRegister with the metaobject GID as the resourceId. Each field in the metaobject that has a translatable type will appear as a separate key — typically just the field handle (e.g., body, author_bio).

If you have dozens or hundreds of metaobject instances (common for ingredient libraries, specification sets, or review blocks), you'll want to batch these mutations. Shopify's GraphQL Admin API enforces a cost-based rate limit: each translationsRegister mutation costs 10 points, and the default bucket is 1,000 points restored at 50 points/second. In practice, this means you can safely run roughly 5 mutations per second sustained, or burst to ~100 mutations before you need to throttle. For very large catalogs, implement a queue with exponential backoff on THROTTLED errors.

---

Step 4 — Handle JSON Metafields Carefully

JSON metafields are a special case that catches many merchants off guard. If you store structured content in a JSON metafield — for example, a product spec table as {"weight": "2kg", "dimensions": "30x20x10cm", "material": "Aluminium"} — Shopify will not expose the individual keys as translatable. It exposes the entire JSON blob as a single string.

That means if you register a French translation, you must provide the complete translated JSON value:

{
  locale: "fr"
  key: "metafield.custom.specifications"
  value: "{\"weight\": \"2 kg\", \"dimensions\": \"30 x 20 x 10 cm\", \"material\": \"Aluminium\"}"
  translatableContentDigest: "xyz789digest"
}

This creates two real risks:

• Structural drift: If a developer updates the JSON schema (adds a key, changes nesting), your translated blob becomes structurally mismatched and may break the theme component rendering it.
• Partial translation: An AI translation tool that isn't JSON-aware may translate the keys themselves ("weight" → "poids"), breaking downstream if metafield.value['weight'] logic in Liquid.

The safest approach is to parse the JSON, extract only the human-readable string values, translate those, and reconstruct the JSON before registering. Look for translation apps that explicitly handle JSON metafields as structured data rather than treating the blob as plain text.

---

Step 5 — Keep Translations in Sync When Content Changes

Metafields change. A supplier updates a material description, a care label gets rewritten, a metaobject's body text is edited. When that happens, Shopify updates the translatableContentDigest for that field, and any previously registered translation is automatically marked stale in the Translations API.

The practical implication: you need a process to detect stale translations and re-translate them. You can query translatableResource and compare the outdatedTranslations field, or monitor webhooks for products/update events and trigger re-translation automatically. For more on keeping a live catalog in sync, see How to Keep Your Shopify Translations in Sync as Your Catalog Changes.

If your catalog runs to hundreds of SKUs with rich metafield data, manual monitoring is not realistic. Automated detection is the only scalable solution. StoreLingo handles this natively — it watches for content changes and flags only the affected fields for re-translation, so you're not re-processing your entire catalog every time a single metafield value changes.

---

Step 6 — Maintain Consistency with a Glossary

Metafields often contain product-specific technical language: material names, certifications, ingredient terminology, regulatory wording. Translating these inconsistently across a catalog undermines trust, especially in regulated categories like food, cosmetics, or medical devices.

Before translating at scale, define a glossary of brand terms and domain-specific vocabulary — terms that should always be translated the same way (or not translated at all). Look for translation apps that let you upload a glossary and apply it automatically during AI translation passes, so "certified organic" always becomes "certifié biologique" in French rather than varying phrase by phrase.

For a broader look at how AI handles this kind of specialized vocabulary versus human translators, see AI Translation vs Human Translation for E-commerce: What Actually Works.

---

Bringing It Together

Translating metafields and metaobjects correctly requires:

1. Querying translatableResource to confirm which fields Shopify exposes
2. Using exact key formatting (metafield.{namespace}.{key}) in translationsRegister
3. Always fetching a fresh digest before registering — never caching it
4. Handling JSON metafields as structured data, not plain strings
5. Automating stale-translation detection for a live catalog
6. Applying a glossary to keep technical terms consistent

If you'd rather not build and maintain this pipeline yourself, StoreLingo handles all of it — including metafield and metaobject translation, change detection, and glossary enforcement — directly inside Shopify's native multilingual framework, with no theme modifications required.

For the broader picture of building a multilingual store, the Complete Shopify Translation Checklist for Going Multilingual covers every content type you'll need to address, and How to Bulk-Translate Hundreds of Shopify Products in Minutes is worth reading once your metafield strategy is in place.

Add StoreLingo on the Shopify App Store →

---

FAQ

Which metafield types can be translated through Shopify's Translations API? Only text-based types are translatable: single_line_text_field, multi_line_text_field, and rich_text_field. Numeric, boolean, date, file reference, and relational metafield types are not exposed as translatable content and cannot be registered via translationsRegister.

Does the Translations API have rate limits that affect bulk metafield translation, and what are the real costs? Yes. Each translationsRegister mutation costs 10 query points against Shopify's GraphQL cost-throttle bucket, which holds 1,000 points and restores at 50 points per second. Sustained throughput is therefore around 5 mutations per second. For a store with 500 products each carrying 4 translatable metafields across 5 languages, that's 10,000 mutations — roughly 33 minutes at sustained rate if run sequentially. Batching multiple translation objects inside a single mutation call (up to the per-call cost limit) reduces wall-clock time significantly; always check the extensions.cost field in the response to tune your batch size dynamically.

When Shopify says a translation is "outdated," what exactly triggers that and what should I do? Shopify marks a translation outdated whenever the source content changes and the translatableContentDigest no longer matches what was used to register the translation. You can detect this by querying translatableResource and inspecting the outdatedTranslations array, or by listening for resource update webhooks. Once detected, re-fetch the current digest and re-register the translation — submitting a new value against a stale digest will result in a userError.