For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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:
The Translations Admin GraphQL API covers store content such as products, categories, and checkout settings. Other shopper-facing strings require different tools depending on where they appear:
Stencil theme files — Translate static strings in Stencil themes using the localization file workflow. See Localizing theme files.
Catalyst theme files — Manage static translations for Catalyst storefronts through the built-in internationalization framework. See Static translations.
Optimized one-page checkout — Localize checkout field labels and messages for the optimized one-page checkout. See Checkout localization.
Transactional email templates — Customize email content per language using the Email Templates API. See Update an email template.
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.
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
