DocsStorefrontCatalystFeaturesLocalizationMulti-Language

Catalyst Multi-Language Overview

Catalyst supports translating content into multiple languages on a single storefront. This overview describes how to manage translations for dynamic catalog data, how Catalyst detects and switches shopper languages, and how to customize language settings.

To translate fixed storefront text, such as buttons and labels, see Static Translations.

Content management

BigCommerce supports multiple locales for shoppers in different regions.

  • Get a list of all locales supported by the BigCommerce platform using the GraphQL Admin API.

  • Add locales to your Catalyst channel with the GraphQL Admin API. There is a max of five locales per channel.

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

    It’s possible to modify product URLs in Catalyst so that each variant has a unique URL based on the selected options, essentially creating separate product pages for each variant. However, this isn’t done automatically and requires custom code.

    You can link to a specific product variant using query parameters, which update dynamically as options are selected on the product detail page (PDP).

  • Add translations for categories and locations 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.

You can manage locales for Catalyst channels in the control panel, with the CLI, or with the GraphQL Admin API. Multi-language is enabled by default on Catalyst stores. On stores where it’s disabled, locale mutations and Channel Manager locale controls aren’t available.

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, the Locales features of the GraphQL Admin API, and the CLI:

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

Catalyst always respects the shopper’s Accept-Language header and the storefront language selector; there is no control panel toggle for “use browser language” on Catalyst channels.

Customization

Catalyst provides built-in features, but you can further customize its functionality to fit your needs.

Customize language settings

You can manage language settings within a channel using the GraphQL Admin API or the Catalyst CLI. This includes:

  • Adding and removing languages
  • Setting a default language
  • Activating or deactivating specific languages

By default, a new Catalyst project starts with a single locale. Add and manage additional locales using the GraphQL Admin API or the CLI.

Configure language settings with the CLI

These steps apply only when creating a new channel.

  1. Run the Catalyst CLI

    To create a new Catalyst project, run the following command:

    pnpm create @bigcommerce/catalyst@latest

  2. Configure project settings

    • Enter project name - When prompted, provide a name for your project.
    • Authorize and create a channel - Complete the authorization process, choose to create a new channel, and specify its name.
    • Select a default language - Choose the channel’s default language from the list.
    • Add additional languages (optional) - Choose Yes when asked whether to add additional languages, then select up to four more from the list. The selected languages are added as active languages for the channel.

To create a channel with languages without the interactive prompts, for example from a script, use catalyst channels create from inside an existing project:

pnpm catalyst channels create --name "My Store" --locale en --additional-locales es fr

--locale sets the default language, and --additional-locales accepts up to four more. See the CLI reference for all options.

For a list of webhooks that are triggered when locales are added, updated, and deleted, see the Settings Webhook Events.

Supported languages

BigCommerce provides checkout and email translations for a set of supported languages. The same page lists the translation keys checkout supports.

Create a custom language selector

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

Translate checkout and transactional emails

You can localize your checkout page by translating fixed text elements, known as static strings, into multiple languages. Checkout renders from BigCommerce, so its translations live in the channel’s theme language files.

For the keys checkout supports, see Supported languages. To reach the language files, see Accessing Checkout Theme Files. You can also use translation keys to translate emails using the Email Template endpoints of the REST Content API.

By default, BigCommerce offers translations for the checkout page and emails in 19 languages.

Resources