Localization and metafields

Use translations for language-specific display text and metafields for project-specific structured data. They solve different problems and should not be interchanged.

Locales and translations

Create and activate the locales the project supports. One locale can be the default. Storefront requests can then supply a locale to resolve translated values, with the project’s default behavior used when no matching translation exists.

translationsUpsertBulk accepts an entity ID and a list of key, locale code, and value entries. Use the exact translation keys exposed by the entity’s translatable fields; do not invent parallel metafields for ordinary localized names and descriptions.

For high-volume work:

  • translationsExport creates an asynchronous export job filtered by entity types and locale codes.
  • translationsImport uploads a translation file for asynchronous processing.
  • Query the returned job until it reaches a terminal state, then inspect its errors before treating the sync as complete.

Metafield definitions

A definition establishes a namespace, key, value kind, and allowed owner type. Supported kinds include text, dropdowns, tags, product or variant pickers, money, integers, and decimals. Definitions let clients validate and render values consistently.

Use a namespaced key that your integration owns, such as erp.material_code, rather than a generic key likely to collide. Choose the narrowest owner type (PRODUCT, PRODUCT_VARIANT, CATEGORY, COLLECTION, CUSTOMER, PRODUCT_ATTRIBUTE, or PRODUCT_ATTRIBUTE_VALUE).

Products and variants can receive initial metafields during create operations. Use dedicated metafield mutations when values must be managed independently.

Design guidance

  • Put customer-facing translated prose in translations.
  • Put operational or domain-specific structured values in metafields.
  • Put searchable merchandising concepts in native tags, categories, collections, and attributes where possible.
  • Treat metafield definitions as versioned contracts. Changing a kind after integrations depend on it can break validation and presentation.
  • Store typed values in the shape required by the definition instead of serializing arbitrary JSON into text.