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

# Translations for Products

The following entities are translatable for products:

* Product Records
  * Name as `name`
  * Description as `description`
  * Pre-order message as `preOrderMessage`
  * Warranty Information as `warrantyInformation`
  * Availability Text as `availability`
  * Search Keywords as `searchKeywords`
  * Page Title as `pageTitle`
  * Meta Description as `metaDescription`
  * Image alt text as `images.altText`
* Custom Fields
  * Name
  * Value
* Product Options
  * Name (option display name, e.g., "Color" or "Size")
  * Value (option value shown to shoppers, e.g., "Red", "XL")

## 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                               |
| -------------- | ----------------------- | ------------------------------------------------- |
| Product        | `PRODUCTS`              | `bc/store/product/{{product_id}}`                 |
| Custom Field   | `PRODUCT_CUSTOM_FIELDS` | `bc/store/productCustomField/{{custom_field_id}}` |
| Product Option | `PRODUCT_OPTIONS`       | `bc/store/product-option/{{option_id}}`           |

## Querying Product Translations (Storefront API)

Data is returned in the current locale determined by the context (e.g., `Accept-Language` header, channel settings, or session locale).

### Example: Query a product in a given locale

#### Request

**`Example query: Query product in a locale`**

```graphql title="Example query: Query product in a locale" showLineNumbers={false}
GRAPHQL https://storefront.example.com/graphql
Accept-Language: es

query {
  site {
    product(entityId: "123") {
      entityId
      name
      description
      pageTitle
      metaDescription
      searchKeywords
      preOrderMessage
      warrantyInformation
      availability
      images {
        altText
      }
      customFields {
        entityId
        name
        value
      }
      options {
        entityId
        displayName   # Option display name (translated if available)
        values {
          label       # Option value text (translated if available)
          entityId
        }
      }
    }
  }
}
```

#### Response

Note that the `entityId` returned is different than the `resourceId` provided in the remaining examples. The full `resourceId` uses the `entityId` as the final piece of its slug. For example, a **product** with an `entityId` of 123 would have a `resourceId` of `bc/store/product/123`.

**`Example query: Query product in a locale`**

```json title="Example query: Query product in a locale" showLineNumbers={false}
{
  "data": {
    "site": {
      "product": {
        "entityId": "123",
        "name": "Nombre del producto",
        "description": "Descripción en español.",
        "pageTitle": "Título de la página del producto",
        "metaDescription": "Meta descripción del producto.",
        "searchKeywords": "palabra1, palabra2",
        "preOrderMessage": "Reserva este producto ahora.",
        "warrantyInformation": "Garantía de 1 año de fabricación.",
        "availability": "En stock",
        "images": [
          {
            "altText": "Modelo vistiendo una camisa azul claro"
          }
        ],
        "customFields": [
          {
            "entityId": "456",
            "name": "Material",
            "value": "Algodón"
          }
        ],
        "options": [
          {
            "entityId": "45",
            "displayName": "Color",
            "values": [
              { "entityId": "100", "label": "Rojo" },    // "Red" in es
              { "entityId": "101", "label": "Azul" }     // "Blue" in es
            ]
          }
        ]
      }
    }
  }
}
```

## Managing Product Translations (Admin API)

Product 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 Product Translations

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

#### Response

The response example below specifically references product translations. If your query is for product options or custom fields, the `resourceId` will be different. Make sure your handling code addresses the correct format.

**`Example query: Query a list of product translations`**

```json title="Example query: Query a list of product translations" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/product/123",
              "fields": [
                {
                  "fieldName": "name",
                  "original": "Widget",
                  "translation": "Gadget (FR)"
                },
                {
                  "fieldName": "description",
                  "original": "A useful widget.",
                  "translation": "Un gadget utile."
                },
                {
                  "fieldName": "page_title",
                  "original": "Widget Product Page",
                  "translation": "Page Produit Gadget"
                }
              ]
            },
            "cursor": "eyJpZCI6MTIzfQ"
          }
        ]
      }
    }
  }
}
```

### Query a Product Translation by Resource ID

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

#### Request

**`Example query: Query a product translation by id`**

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

#### Response

The response example below specifically references product translations. If your query is for product options or custom fields, the `resourceId` will be different. Make sure your handling code addresses the correct format.

**`Example query: Query a product translation by id`**

```json title="Example query: Query a product translation by id" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/product/123",
              "fields": [
                {
                  "fieldName": "name",
                  "original": "Widget",
                  "translation": "Dispositivo (IT)"
                },
                {
                  "fieldName": "description",
                  "original": "A useful widget.",
                  "translation": "Un dispositivo utile."
                }
              ]
            },
            "cursor": "eyJpZCI6MTIzfQ"
          }
        ]
      }
    }
  }
}
```

### Update a Product Translation

#### Request

The request below is for updating the primary product record. For product options or custom fields, replace `resourceType` and `resourceId` with appropriate values from the [Resource fields](#resource-fields) table.

**`Example mutation: Update a product translation`**

```graphql title="Example mutation: Update a product translation" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

mutation {
  translation {
    updateTranslations(input: {
      resourceType: PRODUCTS,
      channelId: "bc/store/channel/1",
      localeId: "bc/store/locale/fr",
      entities: [
        {
          resourceId: "bc/store/product/123",
          fields: [
            { fieldName: "name", value: "Gadget (FR)" },
            { fieldName: "description", value: "Un gadget utile." },
            { fieldName: "page_title", value: "Page Produit Gadget" }
          ]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Update a product translation`**

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

### Delete a Product Translation

The request below is for deleting translations on the primary product record. For product options or custom fields, replace `resourceType` and `resourceId` with appropriate values from the [Resource fields](#resource-fields) table.

#### Request

**`Example mutation: Delete a product translation`**

```graphql title="Example mutation: Delete a product translation" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

mutation {
  translation {
    deleteTranslations(input: {
      resourceType: PRODUCTS,
      channelId: "bc/store/channel/345",
      localeId: "bc/store/locale/fr",
      resources: [
        {
          resourceId: "bc/store/product/123",
          fields: ["name", "description"]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Delete a product translation`**

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