AdminStore ConfigurationTranslations

Translations for Customer Form Fields (Beta)

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

The following entities are translatable for customer form fields:

  • Label as label - The display label for the form field
  • Option values as option_{base64string} - Option values where the base64 string encodes the original option text

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
Customer Form FieldCUSTOMER_FORM_FIELDSbc/store/customerFormField/{field_id}

Field Name Format for Options

  • label - The display label for the form field
  • option_{base64string} - Option values where the base64 string encodes the original option text
    • Example: option_SG9tZSBBZGRyZXNz (where SG9tZSBBZGRyZXNz is base64 for “Home Address”)
    • Example: option_TW9iaWxl (where TW9iaWxl is base64 for “Mobile”)

Examples

Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for customer form fields.

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

Query a Translation by Resource ID

This query returns translation(s) by resourceId.

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 translation by resource id
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(
      filters: {
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}",
        resourceType: CUSTOMER_FORM_FIELDS,
        resourceIds: ["bc/store/customerFormField/18", "bc/store/customerFormField/19"]
      }
    ) {
      edges {
        cursor
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
      }
    }
  }
}

Update a Translation

This mutation updates a translation.

Example mutation: Update a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(
      input: {
        resourceType: CUSTOMER_FORM_FIELDS,
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}",
        entities: [
          {
            resourceId: "bc/store/customerFormField/18",
            fields: [
              { fieldName: "label", value: "Adresse personnalisée" },
              { fieldName: "option_SG9tZSBBZGRyZXNz", value: "Adresse domicile" },
              { fieldName: "option_V29yayBBZGRyZXNz", value: "Adresse bureau" }
            ]
          },
          {
            resourceId: "bc/store/customerFormField/19",
            fields: [
              { fieldName: "label", value: "Téléphone" },
              { fieldName: "option_TW9iaWxl", value: "Portable" },
              { fieldName: "option_SG9tZQ==", value: "Fixe" }
            ]
          }
        ]
      }
    ) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
        ... on InvalidTranslationEntityFieldsError {
          id
          fields
          message
        }
      }
    }
  }
}

The mutation example above shows a successful response. If an entity is not found, the API will return an error response. See the Error Handling Reference for more details on error responses.

Example error response for entity not found:

{
  "data": {
    "translation": {
      "updateTranslations": {
        "__typename": "UpdateTranslationsResult",
        "errors": [
          {
            "__typename": "EntityNotFoundError",
            "message": "Entity bc/store/customerFormField/999 not found."
          }
        ]
      }
    }
  }
}

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: {
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}",
        resourceType: CUSTOMER_FORM_FIELDS,
        resources: [
          { 
            resourceId: "bc/store/customerFormField/18",
            fields: ["label", "option_SG9tZSBBZGRyZXNz", "option_V29yayBBZGRyZXNz"]
          },
          { 
            resourceId: "bc/store/customerFormField/19",
            fields: ["label", "option_TW9iaWxl"]
          }
        ]
      }
    ) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
        ... on InvalidTranslationEntityFieldsError {
          id
          fields
          message
        }
      }
    }
  }
}