DocsAdminStore ConfigurationTranslations

Translations for Catalog Pages (Beta)

The Translations Admin GraphQL API is currently available on Catalyst storefronts only.

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