AdminStore ConfigurationTranslations

Translations for Products (Beta)

The Translations Admin GraphQL API for managing product translations is available on Catalyst storefronts only.

The following entities are translatable for products:

  • Product Records
    • Name as name
    • Description as description
    • Pre-order message as preOrderMessage
    • Warranty Information as warrantyInformation
    • Availability Text as availability
    • Search Keywords as searchKeywords
    • Page Title as pageTitle
    • Meta Description as metaDescription
    • Image alt text as images.altText
  • Custom Fields
    • Name
    • Value
  • Product Options
    • Name (option display name, e.g., “Color” or “Size”)
    • Value (option value shown to shoppers, e.g., “Red”, “XL”)

Resource fields

The entities listed above are referenced differently based on resource type and must use the following values in the queries outlined below:

Entity TyperesourceTyperesourceId Format
ProductPRODUCTSbc/store/product/{{product_id}}
Custom FieldPRODUCT_CUSTOM_FIELDSbc/store/product-custom-field/{{custom_field_id}}
Product OptionPRODUCT_OPTIONSbc/store/product-option/{{option_id}}

Querying Product Translations (Storefront API)

Data is returned in the current locale determined by the context (e.g., Accept-Language header, channel settings, or session locale).

Example: Query a product in a given locale

Example query: Query product in a locale
GRAPHQL https://storefront.example.com/graphql
Accept-Language: es
query {
  site {
    product(entityId: "123") {
      entityId
      name
      description
      pageTitle
      metaDescription
      searchKeywords
      preOrderMessage
      warrantyInformation
      availability
      images {
        altText
      }
      customFields {
        entityId
        name
        value
      }
      options {
        entityId
        displayName   # Option display name (translated if available)
        values {
          label       # Option value text (translated if available)
          entityId
        }
      }
    }
  }
}

Managing Product Translations (Admin API)

Product translation management (list, update, delete) is available via the Admin GraphQL API. These mutations and queries are not available on the Storefront API.

Query a List of Product Translations

The request below uses several variables for reusability. Replace {{resourceType}}, {{channel_id}}, and {{locale_code}} with the appropriate values for your use case.

Example query: Query a list of translations
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(filters: {
        resourceType: {{resourceType}},
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}"
      } first: 50) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}

Query a Product Translation by Resource ID

The request below uses several variables for reusability. Replace {{resourceId}}, {{resourceType}}, {{channel_id}}, and {{locale_code}} with appropriate values for your use case. Make sure resourceId follows the format from the Resource fields table.

Example query: Query a product translation by id
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(filters: {
      resourceType: {{resourceType}},
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      resourceIds: ["{{resourceId}}"]
    }) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}

Update a Product Translation

The request below is for updating the primary product record. For product options or custom fields, replace resourceType and resourceId with appropriate values from the Resource fields table.

Example mutation: Update a product translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(input: {
      resourceType: PRODUCTS,
      channelId: "bc/store/channel/1",
      localeId: "bc/store/locale/fr",
      entities: [
        {
          resourceId: "bc/store/product/123",
          fields: [
            { fieldName: "name", value: "Gadget (FR)" },
            { fieldName: "description", value: "Un gadget utile." },
            { fieldName: "page_title", value: "Page Produit Gadget" }
          ]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}

Delete a Product Translation

The request below is for deleting translations on the primary product record. For product options or custom fields, replace resourceType and resourceId with appropriate values from the Resource fields table.

Example mutation: Delete a product translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    deleteTranslations(input: {
      resourceType: PRODUCTS,
      channelId: "bc/store/channel/345",
      localeId: "bc/store/locale/fr",
      resources: [
        {
          resourceId: "bc/store/product/123",
          fields: ["name", "description"]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}