Metafield key is not a valid translatable field

Technical Q&A

Topic summary

A developer is encountering an error when attempting to translate product metafields via Shopify’s GraphQL API. The translationsRegister mutation returns “Key [key] is not a valid translatable field” despite using metafield key and namespace parameters.

Attempted approach:

  • Using translationsRegister mutation with resourceId (Product GID)
  • Passing translation parameters: locale, key, value, and translatableContentDigest

Suggested solution:

  • Verify the metafield is translatable by checking Shopify’s “Translate & Adapt” app
  • If the field appears in that app, it can be translated programmatically
  • Use browser developer tools (Network tab) to inspect actual API requests when performing translations manually
  • Analyze the request structure to identify the correct field format

The issue appears to stem from documentation gaps regarding proper metafield translation syntax. The discussion remains open with no confirmed resolution yet.

Summarized with AI on November 2. AI used: claude-sonnet-4-5-20250929.
1

Hello, I have a lot of metafields that I want to translate into another language through the GraphQL API but tried with metafield key and namespace and all I get is that Key [key] is not a valid translatable field

this is the query

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

{
  "resourceId": "gid://shopify/Product/xxx",
  "translations": [
    {
      "locale": "ar",
      "key": "placeholder",
      "value": "placeholder",
      "translatableContentDigest": "placeholder"
    }
  ]
}
2

You need to check on Shopify’s “Translate & Adapt” app. If the field is visible and translatable from that app it means you can reproduce it from code. Now if you see your field you need to open your browser’s developer console and go to the Network tab, then you do a first translation and analyze the requests sent as in the screenshot I shared.

Capture d'écran 2025-01-18 191559.png
Capture d'écran 2025-01-18 191559.png997×726 50.4 KB

Sometimes the documentation lacks explanation :disappointed_face: