AdminStore ConfigurationTranslations

Translations Admin GraphQL API (Beta)

The Translations Admin GraphQL API is currently available on Catalyst storefronts only. This API enables merchants to translate a single website into multiple languages.

With a single storefront setup, the shopper’s experience remains consistent, but the content is displayed in their preferred language. This use case is particularly common in multilingual countries like Canada and for customers selling cross-border, where the same storefront serves shoppers in multiple languages without altering the overall user experience.

The API currently supports translations for the following resource types, and more are expected in the future:

Refer to the Error Handling guide for understanding and handling errors while managing translations.

Translation API allows users to add content translations to any non-default channel locale. In order to update content on a default channel language, please use respective management API.

How does this API work?

Core Concepts

When using the GraphQL Admin API to manage translations, the following fields are used to identify the relevant channel, locale, and resource so that all data is assigned properly.

  • resourceType: The type of entity being translated (PRODUCTS, CATEGORIES, BRANDS, etc.)
  • resourceId: The specific entity ID (format varies by type, e.g. bc/store/category/{id})
  • channelId: The channel context (format: bc/store/channel/{id})
  • localeId: The target language (format: bc/store/locale/{locale_code})

Authentication

Access to the Translations Admin GraphQL API requires valid API credentials. GraphQL Admin API endpoints use the X-Auth-Token header to authenticate to BigCommerce servers. To make a call to the Admin GraphQL, use an API client tool such as Postman. Ensure authentication tokens are included in requests.

OAuth scopes

NamePermissionDescription
Store Translationsread-onlyView translation details
Store TranslationsmodifyView and modify translation details

For more information on OAuth Scopes, see our Guide to API Accounts.

Behavior Notes

  • Adding a translation to a default locale will result in unexpected behavior. Do not attempt to add translations to a channel’s default locale.
  • Across all translatable resources, the API will return the default values for any field that doesn’t have an existing translation in the requested locale.
  • With translations enabled, the API will automatically return translated fields, whenever possible, based on the requested locale.
  • For more complex translation requests (e.g. product listing pages with many products), the use of pagination is required. Currently, the Translations API supports up to 50 results per request.

Limitations

  • Currently in Beta and subject to changes
  • Catalyst storefronts only
  • Rate limits apply
  • Can only translate non-default channel locales

Best Practices

  • Cache translations to minimize API calls
  • Check existing translations before creating duplicates
  • Use pagination effectively for large translation sets
  • Validate resourceIds match resourceType format requirements

Resources