For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
  • Overview
    • Quick Start
    • Sandboxes
    • Tools & SDKs
    • Support
  • Docs
      • Getting Started
          • Overview
          • Products
          • Product Modifiers
          • Product Listings
          • Product Filters
          • Product URLs (Beta)
          • Customer Form Fields
          • Promotions
          • Address Form Fields
          • Checkout Settings
          • Shipping Methods
          • Tax Rates
          • Order Statuses
          • Locations
          • Payment Methods
          • Error Handling
    • Archive
    • Closed Beta Programs
Dev Portal
LogoLogo
On this page
  • Resource fields
  • Querying Product Translations (Storefront API)
  • Example: Query a product in a given locale
  • Managing Product Translations (Admin API)
  • Query a List of Product Translations
  • Query a Product Translation by Resource ID
  • Update a Product Translation
  • Delete a Product Translation
DocsAdminStore ConfigurationTranslations

Translations for Products (Beta)

Was this page helpful?
Previous

Overview

Next

Product Modifiers

Built with

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/productCustomField/{{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

Request
Response
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

Request
Response

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.

Request
Response
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

Request
Response

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.

Request
Response
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
        }
      }
    }
  }
}