Catalyst Multi-Language Guide
Catalyst supports translating content into multiple languages on a single storefront.
This guide describes tools for managing translations for dynamic product catalog data. It includes managing language settings, detecting shopper preferences based on browser settings or shopper input, and switching between languages on the storefront.
For information on how to manage translations for the storefront theme, see the Theme Translations (opens in a new tab) guide.
Content management
BigCommerce supports multiple locales for shoppers in different regions.
- Get a list of all locales (opens in a new tab) supported by the BigCommerce platform using the GraphQL Admin API.
- Add locales (opens in a new tab) to your Catalyst channel using the GraphQL Admin API
- Add translations for products to multiple locales added to Catalyst channel. Learn about how to use the GraphQL Admin API to add translations to a single channel and locale (opens in a new tab).
Default Catalyst features
Manage language settings
You can select a default language and any additional languages on a single Catalyst storefront through the Control Panel and the Locales features (opens in a new tab) of the GraphQL Admin API:
- In the Control Panel, Localization settings for a storefront (opens in a new tab) are available in the channel manager for Catalyst channels. Locales enabled on your Catalyst storefront are propagated to Makeswift, where you can create and translate pages in the Makeswift Visual Editor (opens in a new tab). Learn more about managing pages in Makeswift (opens in a new tab) through the BigCommerce integration.
- If you want to manage languages through the API, see the Customization - Manage language settings section.
Detect and switch between shopper languages
Out of the box, the Catalyst storefront displays translated product data for the language that the shopper selected in the pre-configured language selector. The Catalyst Client (opens in a new tab) automatically fetches the localized data from the GraphQL Storefront API, which lets you query data from your enabled storefront languages.
The Catalyst storefront sends an Accept-Language HTTP request header to indicate the shopper’s preferred language or locale. This header allows the system to identify the appropriate translation to display. The translations for checkout are dynamically applied based on the locale specified in this header.
Customization
There are features you can customize in addition to what’s provided for Catalyst out of the box.
Manage language settings
To manage language settings, you can use the GraphQL Admin API to manage locales within a channel. This includes adding new languages, removing existing ones, setting a default language, and controlling whether specific languages are active or inactive. These features are not included by default in Catalyst when you install a storefront through the CLI, but can be implemented using the GraphQL Admin API. For more information, see the Locale Configuration (opens in a new tab) guide.
For a list of webhooks that are triggered when locales are added, updated, and deleted, see the Settings Webhook Events (opens in a new tab).
Detect and switch between shopper languages
You can create a custom language selector using the GraphQL Storefront API. The GraphQL Storefront queries allow you to retrieve the available locales and identify the default locale and query content in shopper preferred locale.
To render dynamic product data, GraphQL Storefront API supports fetching language-specific content for products. For more information, see the Multi-Language Support in GraphQL Storefront API (opens in a new tab) guide.
Translate checkout & transactional emails
You can localize your checkout page by translating fixed text elements, known as static strings, into multiple languages. For translation keys that checkout supports, see the Enabling Multi-Language Checkout (opens in a new tab) article. You can also use translation keys to translate emails using the Email Template (opens in a new tab) endpoints of the REST Content API.