DocsAdminStore ConfigurationTranslations

Product Filter Translations

Translations for Product Filters (Beta)

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

This subset of the Translation API is built for translating the labels on the faceted search / product filtering fields on the storefront. In particular, it allows you to translate the general filter names such as Category, Brand, and Custom Fields. These translations specifically apply to the title of the group, not the filter values and variables. To manage the filter values themselves, refer to the specific resources.

The product filter translatable fields are:

Filter TypeTranslatable Fields
Category, Brand, Variants, Custom Fields, Price, RatingDisplay Name as the field name (e.g. brand or category)
Other FiltersDisplay Name as display_name
Has Free Shipping as has_free_shipping
Is Featured as is_featured
In Stock as in_stock

Only string values are translatable. Numeric content such as product count or price values are not translatable.

Query translations

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

Translated fields are returned whenever available, and the default locale values are returned otherwise on a field-by-field basis.

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: PRODUCT_FILTERS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/fr"
    } first: 50) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}

Query a translation by resourceId

When querying by resourceId, the resourceId value must be constructed from the filterName using the format bc/store/productFilters/{filterName}. For example, the filterName brand becomes the resourceId bc/store/productFilters/brand.

This query returns translation(s) filtered by resourceId. For product filters, the resourceId is constructed from the filterName as shown in the callout above.

Example query: Query a translation by resource id
1GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
2X-Auth-Token: {{token}}
3
4query {
5store {
6  translations(filters: {
7    resourceType: PRODUCT_FILTERS,
8    channelId: "bc/store/channel/{{channel_id}}",
9    localeId: "bc/store/locale/it",
10    resourceIds: ["bc/store/productFilters/brand"]
11  }) {
12    edges {
13      node {
14        resourceId
15        fields {
16          fieldName
17          original
18          translation
19        }
20      }
21      cursor
22    }
23  }
24}
25}

Update a translation

This mutation updates a translation.

Duplicate translations for filters is not allowed. For example,

Color -> Colir
Colorr -> neither Color, nor Colir would be valid

Example mutation: Update a translation
GRAPHQL http://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
    translation {
        updateTranslations(input: {
            resourceType: PRODUCT_FILTERS,
            channelId: "bc/store/channel/{{channel_id}}",
            localeId: "bc/store/locale/es",
            entities: [
                {
                    resourceId: "bc/store/productFilters/brand",
                    fields: [
                        {
                            fieldName: "brand",
                            value: "brand (OVR)"
                        }
                    ]
                }
            ]
        }) {
            __typename
            errors {
                __typename
                ... on Error {
                    message
                }
            }
        }
    }
}

Delete a translation

The following mutation deletes a translation.

Example mutation: Delete a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
    translation {
        deleteTranslations(input: {
            resourceType: PRODUCT_FILTERS,
            channelId: "bc/store/channel/{{channel_id}}",
            localeId: "bc/store/locale/es",
            resources: [
                {
                    resourceId: "bc/store/productFilters/brand",
                    fields: ["brand"],
                }
            ]
        }) {
            __typename
            errors {
                __typename
                ... on Error {
                    message
                }
            }
        }
    }
}

Limitations

  • Product count and other numeric-only fields do not support localization.
  • Only displayable string content for filter names and values is translatable.
  • Currently available on Catalyst storefronts only.

Best Practices

  • Use the GraphQL Admin API to manage translations in bulk.
  • Check for existing translations before creating new ones to minimize overwrites.
  • Always use full resourceId values as required by the API.
  • Storefront GraphQL API automatically uses the shopper’s locale for product filter display names.