Migrate translatable metafield queries

The METAFIELD value of the TranslatableResourceType enum is deprecated. Metafields are conditionally translatable: whether a metafield's value can be translated depends on the metafield's type and on whether its owner resource allows metafield translations. A shop-wide resource type can't express that condition, so your app had to cross-reference each metafield's type to determine what it could translate.

The Metafield.translatable field answers that question on the metafield itself. In this guide, you'll learn how to replace translatableResources(resourceType: METAFIELD) with a per-resource metafield query, and how to register translations for the translatable metafields that you find.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app is on API version 2026-10 or higher. The translatable field isn't available in earlier versions.
• Your app has the read_translations and write_translations access scopes, and the read scope for each resource that owns the metafields that you translate. The examples in this guide query products, which require the read_products access scope. Learn how to configure your access scopes using Shopify CLI.
• Your app queries translatableResources or translatableResourcesCount with resourceType: METAFIELD.

Anchor to ConsiderationsConsiderations

• You can't filter a metafield query by translatable. Retrieve the metafields for a resource, and then filter the results in your app.
• No single query returns every translatable metafield in a shop. Query each resource type that your app translates. To scan an entire shop, you can use bulk operations.
• The translatable value reflects both the metafield's type and whether its owner allows metafield translations, so the same metafield type can be translatable on one resource and not translatable on another.
• The translatable field tells you which metafields you can translate, but it doesn't return the content digest that the translationsRegister mutation requires. Retrieve digests with translatableResourcesByIds, as shown in step 3. The Metafield.compareDigest field isn't a substitute, because it's computed differently and translationsRegister rejects it.

Anchor to Step 1: Replace the ,[object Object], queryStep 1: Replace the translatableResources query

Previously, you retrieved a shop's translatable metafields with the translatableResources query and resourceType: METAFIELD.

In API version 2026-10 and higher, query the metafields on the resource that owns them and select the translatable field. The following example retrieves the metafields for a product:

{
  translatableResources(first: 10, resourceType: METAFIELD) {
    edges {
      node {
        resourceId
        translatableContent {
          key
          value
          digest
          locale
        }
      }
    }
  }
}

query ProductMetafields($id: ID!) {
  product(id: $id) {
    id
    metafields(first: 10) {
      edges {
        node {
          id
          namespace
          key
          type
          translatable
        }
      }
    }
  }
}

Anchor to Step 2: Filter for translatable metafieldsStep 2: Filter for translatable metafields

Filter the response in your app and collect the IDs of the metafields where translatable is true. You'll use those IDs in the next step:

Anchor to Step 3: Retrieve the translatable content digestsStep 3: Retrieve the translatable content digests

The translationsRegister mutation requires a translatableContentDigest value for each value that you translate. Pass the metafield IDs from the previous step to the translatableResourcesByIds query to retrieve their digests in a single request.

A metafield exposes one translatable key, value:

Anchor to Step 4: Register the translationsStep 4: Register the translations

Use the translationsRegister mutation to write a translation for a metafield. Pass the metafield's ID as the resourceId, value as the key, and the digest from the previous step as the translatableContentDigest:

To verify a translation, query the metafield's translations field with the locale that you registered.

Anchor to Next stepsNext steps

• Learn how to manage translations of merchant-provided content for other resource types.
• Review which metafield data types are translatable.
• Use the Storefront API to retrieve translated content.