> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Category URL Translations

> Translate category URL paths for multilingual storefronts using the Translations Admin GraphQL API.

# Translations for Category URLs

> **Note**
>
> 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 Type       | `resourceType`       | `resourceId` Format                        |
| ----------------- | -------------------- | ------------------------------------------ |
| Category URL Path | `CATEGORY_URL_PATHS` | `bc/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

#### Request

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 title="Example query: Query a list of translations" showLineNumbers={false}
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
      }
    }
  }
}
```

#### Response

**`Example query: Query a list of category URL translations`**

```json title="Example query: Query a list of category URL translations" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/categoryUrlPath/1",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/bath",
                  "translation": "/bath_es"
                }
              ]
            },
            "cursor": "eyJpZCI6MX0"
          },
          {
            "node": {
              "resourceId": "bc/store/categoryUrlPath/2",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/kitchen",
                  "translation": null
                }
              ]
            },
            "cursor": "eyJpZCI6Mn0"
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "hasPreviousPage": false,
          "startCursor": "eyJpZCI6MX0",
          "endCursor": "eyJpZCI6Mn0"
        }
      }
    }
  }
}
```

### 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](#resource-fields) table.

#### Request

**`Example query: Query a category URL translation by id`**

```graphql title="Example query: Query a category URL translation by id" showLineNumbers={false}
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
      }
    }
  }
}
```

#### Response

**`Example query: Query a category URL translation by id`**

```json title="Example query: Query a category URL translation by id" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/categoryUrlPath/1",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/bath",
                  "translation": "/bath_es"
                }
              ]
            },
            "cursor": "eyJpZCI6MX0"
          }
        ]
      }
    }
  }
}
```

### Update a Category URL Translation

#### Request

**`Example mutation: Update a category URL translation`**

```graphql title="Example mutation: Update a category URL translation" showLineNumbers={false}
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
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Update a category URL translation`**

```json title="Example mutation: Update a category URL translation" showLineNumbers={false}
{
  "data": {
    "translation": {
      "updateTranslations": {
        "__typename": "UpdateTranslationsResult",
        "errors": []
      }
    }
  }
}
```

#### Response with errors

**`Example mutation: Update a category URL translation for a missing entity`**

```json title="Example mutation: Update a category URL translation for a missing entity" showLineNumbers={false}
{
  "data": {
    "translation": {
      "updateTranslations": {
        "__typename": "UpdateTranslationsResult",
        "errors": [
          {
            "__typename": "EntityNotFoundError",
            "message": "Entity bc/store/categoryUrlPath/11 not found."
          }
        ]
      }
    }
  }
}
```

### Delete a Category URL Translation

#### Request

**`Example mutation: Delete a category URL translation`**

```graphql title="Example mutation: Delete a category URL translation" showLineNumbers={false}
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
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Delete a category URL translation`**

```json title="Example mutation: Delete a category URL translation" showLineNumbers={false}
{
  "data": {
    "translation": {
      "deleteTranslations": {
        "__typename": "DeleteTranslationsResult",
        "errors": []
      }
    }
  }
}
```

#### Response with errors

**`Example mutation: Delete a category URL translation for a missing entity`**

```json title="Example mutation: Delete a category URL translation for a missing entity" showLineNumbers={false}
{
  "data": {
    "translation": {
      "deleteTranslations": {
        "__typename": "DeleteTranslationsResult",
        "errors": [
          {
            "__typename": "EntityNotFoundError",
            "message": "Entity bc/store/categoryUrlPath/11 not found."
          }
        ]
      }
    }
  }
}
```