DocsAdminStore ConfigurationTranslations

Category URL Translations

Translations for Category URLs

The Translations Admin GraphQL API for managing category URL translations is available on Stencil storefronts only.

The following entities are translatable for category URLs:

  • Category URL Path
    • URL path as url_path — The URL path of the category on the storefront

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
Category URL PathCATEGORY_URL_PATHSbc/store/categoryUrlPath/{{category_id}}

Querying Category URL Translations (Storefront API)

Data is returned in the current locale determined by the context (e.g., Accept-Language header, channel language settings, or site subfolder). Category URLs on the storefront reflect the translated URL path; when translations exist for the requested locale, those translated values are returned.

Managing Category URL Translations (Admin API)

Category URL 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 Category URL Translations

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

This query returns a paginated list of translations with a maximum of 50 results per request. Use the cursor from the response in a subsequent request to fetch more results.

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: CATEGORY_URL_PATHS,
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}"
      } first: 50) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}

Query a Category URL Translation by Resource ID

The request below uses several variables for reusability. Replace {{resourceId}}, {{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 category URL translation by id
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(filters: {
      resourceType: CATEGORY_URL_PATHS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      resourceIds: ["{{resourceId}}"]
    }) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}

Update a Category URL Translation

Example mutation: Update a category URL translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(input: {
      resourceType: CATEGORY_URL_PATHS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      entities: [
        {
          resourceId: "bc/store/categoryUrlPath/1",
          fields: [
            { fieldName: "url_path", value: "/bath_es" }
          ]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}

Delete a Category URL Translation

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