DocsAdminStore ConfigurationTranslations

Translations for Catalog Pages (Beta)

The Translations Admin GraphQL API is available on Catalyst storefronts by default and in early access for Stencil and other headless storefronts. To get early access, reach out to the BigCommerce support team.

The following entities are translatable for catalog listing pages:

  • Categories
    • Name as name
    • Description as description
    • Page Title as page_title
    • Meta Keywords as meta_keywords
    • Meta Description as meta_description
    • Search Keywords as search_keywords
  • Brands
    • Name as name
    • Page Title as page_title
    • Meta Keywords as meta_keywords
    • Meta Description as meta_description
    • Search Keywords as search_keywords

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
CategoryCATEGORIESbc/store/category/{{category_id}}
BrandBRANDSbc/store/brand/{{brand_id}}

Examples

Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for catalog pages.

Query a List of Translations

This query returns a paginated list of translations by resourceType, channel and locale with a maximum of 50 results per request.

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 Translation by Resource ID

This query returns a translation by resourceId.

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 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 Translation

The request below is for updating a category. For brands, replace resourceType and resourceId with appropriate values from the Resource fields table.

Example mutation: Update a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(input: {
      resourceType: CATEGORIES,
      channelId: "bc/store/channel/1",
      localeId: "bc/store/locale/en",
      entities: [
        {
          resourceId: "bc/store/category/18",
          fields: [
            {
              fieldName: "name",
              value: "name (OVR)"
            },
            {
              fieldName: "description",
              value: "description (OVR)"
            },
            {
              fieldName: "page_title",
              value: "page_title (OVR)"
            },
            {
              fieldName: "meta_description",
              value: "meta_description (OVR)"
            },
            {
              fieldName: "search_keywords",
              value: "search_keywords (OVR)"
            }
          ]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}

Delete a Translation

The request below is for deleting translations on a category. For brands, replace resourceType and resourceId with appropriate values from the Resource fields table.

Example mutation: Delete a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    deleteTranslations(input: {
      resourceType: CATEGORIES,
      channelId: "bc/store/channel/1",
      localeId: "bc/store/locale/en",
      resources: [
        {
          resourceId: "bc/store/category/18",
          fields: ["name", "page_title", "meta_description"]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}