Managing Localized and Multi-Language Content Using Shopify Metaobjects

You add French and German, run Translate & Adapt, and the product pages look right until someone opens the size guide drawer and it’s still in English. Metaobject entries don’t get translated just because the store has more languages. The definition has to allow translation, and each field type has its own rule about whether it can be translated at all.

This guide covers the switch to turn on, which fields you can and can’t translate, three ways to get translations in at volume, and the cases where you shouldn’t translate at all, because what you need is a different entry per market.

Turn on translation for the definition

Translation is a property of the metaobject definition, not of each entry. In the admin it’s the Translations option on the definition under Settings > Custom data; in the API it’s the translatable capability:

graphql

mutation EnableTranslations($id: ID!) {
  metaobjectDefinitionUpdate(
    id: $id
    definition: { capabilities: { translatable: { enabled: true } } }
  ) {
    metaobjectDefinition { type capabilities { translatable { enabled } } }
    userErrors { field message }
  }
}

Until that’s on, entries of that type won’t show up as translatable content anywhere, including Translate & Adapt. It’s the first thing to check when “the size guides didn’t translate”.

Which field types can be translated

Turning on translation doesn’t make every field translatable. Shopify decides per field type:

Two consequences catch people out:

• Numbers don’t translate. A chart stored as number fields in centimeters can’t “become” inches by translation. That’s a market problem, not a language problem (more below).
• File references do translate. If your size guide is an image with English text baked in, you can attach a French version of the image as the French translation of that field. That’s often the quickest win for image-based charts.

Three ways to load translations

1. Translate & Adapt

Shopify’s Translate & Adapt app lists translatable metaobjects alongside products and pages. It’s fine for a handful of entries, and for reviewing machine translations before they go live. For hundreds of entries in several languages, you’ll want one of the bulk routes.

2. The translations CSV

Under Settings > Languages, Export produces a CSV of translatable content for the languages you choose (it’s emailed to you). Every row is one field of one resource in one locale, with the default content and a column for the translated content. Fill in the translations, then import the file back from the same screen.

Two snags for metaobject work:

• Rows identify resources by Shopify’s internal IDs, not by handle, so you can’t easily match a row to “the slim fit chart” without looking at its default content.
• If the file contains errors, the whole import stops and lists them. Keep files small enough to fix quickly: one language, one content type at a time.

3. The API

For a repeatable process (for example, translations coming back from an agency or a translation system), use the Admin API. First, read each entry’s translatable content. Every field comes with a digest of its current source text:

graphql

query TranslatableEntries {
  translatableResources(first: 50, resourceType: METAOBJECT) {
    nodes {
      resourceId
      translatableContent { key value digest locale }
    }
  }
}

Then register a translation for a field, passing that digest:

graphql

mutation Translate($id: ID!, $translations: [TranslationInput!]!) {
  translationsRegister(resourceId: $id, translations: $translations) {
    translations { key locale value }
    userErrors { field message }
  }
}

json

{
  "id": "gid://shopify/Metaobject/1234567",
  "translations": [
    {
      "key": "fit_notes",
      "locale": "fr",
      "value": "Coupe près du corps",
      "translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9"
    }
  ]
}

The digest ties the translation to the exact source text it was made from. That’s what makes the next section work.

Translate or localize by market?

Language and market are different axes, and metaobjects handle them differently.

Translate when the content is the same and only the words change: fit notes, care instructions, FAQ answers, designer bios.

Localize by market when the content itself differs by region: measurements in inches for the US and centimeters for the EU, regional compliance text, a different supplier’s warranty. Numbers can’t be translated, and you shouldn’t try to fake it with text fields.

The pattern that works: keep one entry per variant of the content (chinos-chart-in, chinos-chart-cm), and make the product’s reference to it market-specific. A product metafield of type metaobject_reference can be localized by market, so the US market points at the inches entry and the EU market at the centimeters entry, while the product stays one product. Through the Admin API that’s marketLocalizationsRegister. Test the whole flow on a development store with two markets before you roll it out; it’s the least-trodden path in this guide.

The anti-pattern is one entry per language: size-guide-en, size-guide-fr, size-guide-de. It looks simple, then doubles every edit, breaks the “one entry, many references” model, and leaves products pointing at the wrong language unless something swaps them.

Keeping translations current after a bulk edit

Translations are pinned to a digest of the source text. Change the English fit notes on 300 entries and the French and German translations of those fields are now marked as outdated. They don’t vanish, but they no longer match what the English says. The translations CSV export includes a status column that shows which ones are outdated.

So plan bulk edits in this order:

1. Edit the source language in bulk (export, edit in a spreadsheet, import by handle).
2. Export translations for the affected languages.
3. Filter to the outdated rows and send only those for translation.
4. Import the translations.

Doing it the other way round, translating first and editing the source later, means paying for the same translations twice.

Checklist for a multi-language metaobject rollout

• The definition has translations turned on.
• Fields that need translating are text, rich text, URL, link, JSON or file fields.
• Anything that varies by region (units, legal text) is a separate entry, referenced per market.
• The source language is final before translations are commissioned.
• After every bulk edit of the source, outdated translations are re-exported and refreshed.

For deciding which data belongs in a metafield and which in a metaobject in the first place, see metafields vs metaobjects. For unit-specific size charts, see migrating size guides into metaobjects. And for step 1 of the edit workflow, see bulk editing metaobjects in Excel or Google Sheets.