> This page is for Developer.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.
# Catalyst Multi-Language Setup
> Translate a Catalyst storefront into another language, covering static strings, catalog data, and Makeswift content.
This tutorial shows you how to translate your Catalyst storefront into another language, in this case French, using the features available out of the box. It covers the three places where you update translations for a locale:
* [Static strings in components](#translate-static-strings)
* [Dynamic data from BigCommerce](#translate-dynamic-data-from-bigcommerce)
* [Makeswift content](#translate-makeswift-content)
## Prerequisites
Create a Catalyst storefront with [One-Click Catalyst](/developer/docs/storefront/catalyst/getting-started/one-click-catalyst) and choose the option to use sample catalog data. Then follow the [Run locally](/developer/docs/storefront/catalyst/getting-started/one-click-catalyst#run-locally) steps to run it on your machine.
## Add a locale in Catalyst
You can add languages when you create your Catalyst storefront. To add more later, enable them in the control panel:
1. Under **Channels**, choose your Catalyst storefront and click the **Localization** tab.
2. Click **Add new Language**, select the languages to add, and save. Make sure each new language is active.
Catalyst reads the enabled locales, and the subfolder each one is served at, from your default channel at runtime, so you don't need to change any code or redeploy. The locale configuration is cached for about five minutes, so a newly added or changed locale can take up to five minutes to appear, both locally and on your deployed site.
> **Warning**
>
> Each enabled locale needs a matching translation file in `messages/` (for example, `messages/fr.json`). Pages for an enabled locale without a file return a 404. See [Static Translations](/developer/docs/storefront/catalyst/features/localization/static-translations#enable-the-locale).
Start your development server. When you visit the running application (`localhost:3000` by default), a language selector in the top right corner lets you toggle between locales:
The selector lists all the enabled locales in your storefront. The storefront in this tutorial uses English as the default language and French (`fr`) as an additional language.
## Locale-specific URLs
Switch to your new locale, in this case `fr`, in the language selector. The locale prefix is added to the URL path, for example `http://localhost:3000/fr`. Catalyst uses [prefix-based routing](https://next-intl.dev/docs/routing/configuration#locale-prefix) from the [`next-intl`](https://next-intl.dev/) library, so each localized page is served under its locale's prefix.
The prefix is the subfolder configured for the locale in the control panel, or the locale code if no subfolder is set. For example, a `de` locale configured with the subfolder `de-de` is served at `/de-de`. The locale served at the root (`/`) has no prefix.
## Translate static strings
Catalyst's fixed text is translated with static strings in the `messages` folder of your Catalyst app, which components read with the `next-intl` library. Catalyst ships static string translations for the locales it supports out of the box, such as `fr`.
1. In the `messages` folder, open the French translation file, `fr.json`. It contains predefined translation keys, such as the ones for the empty cart message, along with their translations.
```json showLineNumbers={false}
{
"Cart": {
"Empty": {
"title": "Votre panier est vide.",
"subtitle": "Ajoutez quelques produits pour commencer.",
"cta": "Continuer mes achats"
},
}
}
```
2. Open the Cart page component, `app/[locale]/(default)/cart/page.tsx`, to see how a server component reads translations by calling `getTranslations`. `next-intl` imports translations based on the [current locale that it detects](https://next-intl.dev/docs/routing/middleware#locale-detection).
```tsx showLineNumbers={false}
import { getTranslations } from 'next-intl/server';
export default async function Cart() {
// load all the translation strings from messages/ under the 'Cart' namespace.
const t = await getTranslations('Cart');
// pass translated strings into your components
const emptyState = (
<>
);
}
```
3. Open the cart and switch your locale to `FR` to see the translated empty cart message.
After you enable a supported locale, some components are already translated. For an unsupported locale, [define your own static string translations](/developer/docs/storefront/catalyst/features/localization/static-translations#translation-file) in this directory. To use translations in components you create, see [Use keys in React components](/developer/docs/storefront/catalyst/features/localization/static-translations#use-keys-in-react-components).
## Translate dynamic data from BigCommerce
Catalyst fetches dynamic data from BigCommerce, and the data-fetching client sends the current locale with every GraphQL request. You don't need any extra code to get locale-specific content.
### Translate product data
Component text comes from translation files, but product data, such as the product name, variants, and description, comes from BigCommerce.
You translate product data by sending mutations with the [GraphQL Admin API](/developer/docs/admin/multi-storefront/msf-international-enhancements/overview). Start by translating the name and description of your sample products with a mutation to [set basic product information](/developer/docs/admin/multi-storefront/msf-international-enhancements/product-basic-information). To run the sample requests in Postman:
1. Download the
Product Translations file
.
This JSON file contains French translations for the sample products that come with your Catalyst storefront. Change the product IDs in the file to the actual product IDs from your store. The English translations are included for reference, but aren't used in the requests.
2. Download the
Sample Postman environment
and [import it into Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/). It includes the following [environment variables](https://learning.postman.com/docs/sending-requests/variables/managing-environments/#add-environment-variables), which you’ll need to populate:
* `store_hash` - the store hash from your `.env.local` file
* `channel_id` - the channel ID from your `.env.local` file
* `access_token` - a Store Level V2/V3 API token with the `Products` OAuth scope that you can get by [creating an API Account](https://support.bigcommerce.com/s/article/Store-API-Accounts?language=en_US#creating)
Make sure to [make this environment active](https://learning.postman.com/docs/sending-requests/variables/managing-environments/#switch-between-environments) in Postman.
3. Download and import the
Postman collection for translations
.
The collection includes requests for products, categories, and brands. This step uses the product requests.
4. Run the requests in the [Postman Collection Runner](https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/). Select only the **Product Basic Information** mutation in the run sequence and upload the Product Translations file from Step 1.
Your products should now have French translations for their names and descriptions. When you visit the product page at the path `/fr/chinese-evergreen`, you should see the translated product name and description:
#### Textual search
BigCommerce indexes the localized name, description, and search keywords for a product. This means you can match search queries to translated product content through these fields after you add translations. You've already translated the names and descriptions, so next add search keywords.
Search keywords are custom terms you can define so that a product is more visible in your storefront’s textual search. They aren’t visible on the storefront and don’t affect SEO, but help match more search queries to relevant products.
Your sample data doesn’t include predefined search keywords for your products. You can add them by sending a GraphQL mutation to [set the storefront details for a locale](/developer/docs/admin/multi-storefront/msf-international-enhancements/product-attributes).
In the Postman collection you imported earlier, open the Collection Runner again. This time, select the **Product Search Keywords** mutation in the run sequence. You can use the same
Product Translations file
you downloaded earlier since it also includes translations for search keywords.
With the sample data, when you search for the “communes” keyword, the Chinese Evergreen sample product should appear:
The textual search is powered by BigCommerce’s GraphQL Storefront API. Learn more about the [capabilities and limitations of textual search](/developer/docs/storefront/headless/products/faceted-textual-search), including fallback content for products that haven’t been translated.
### Translate categories
Similar to products, category data is fetched dynamically from BigCommerce, including its name, description, page title, meta description, and search keywords. You can translate category data by sending GraphQL mutations with the [GraphQL Admin API](/developer/docs/admin/store-configuration/translations/product-listings).
To run the sample requests in Postman:
1. Download the
Category Translations file
.
This file contains French translations for the sample categories that come with your Catalyst storefront. Change the category IDs in the file to the actual category IDs from your store. The English translations are included for reference, but aren't used in the requests.
2. Open the same
Postman collection for translations
that you imported when you were translating product data. You can use the same sample Postman environment you imported earlier.
3. Run the requests in the Collection Runner. Select only the **Categories** mutation in the run sequence and upload the Categories Translations file from Step 1.
Refresh the page to see the translated category headings in the header. Translated category metadata appears in the page source.
### Translate brands
A brand is an attribute that groups your products by label and supports SEO. Brand data is fetched dynamically from BigCommerce, including its name, page title, meta keywords, meta description, and search keywords.
Before translating brands, add a brand to a product so that the brand is available on your storefront:
1. Under the **Products** tab, click on **Products**.
2. Click on the ellipses **(...)** next to the product you want to add a brand. Click **Edit**.
3. In the **Basic Information** section, select the Rustic Roots brand in the dropdown. This brand came with the sample catalog data.
You translate brands with the same GraphQL Admin API mutations as categories. To run the sample requests in Postman:
1. Download the
Brand Translations file
.
This file contains French translations for the sample brands that come with your Catalyst storefront. Change the brand IDs in the file to the actual brand IDs from your store. The English translations are included for reference, but aren't used in the requests.
2. Open the same
Postman collection for translations
that you imported when you were translating product data. You can use the same sample Postman environment you imported earlier.
3. Run the requests in the Collection Runner. Select only the **Brands** mutation in the run sequence and upload the Brand Translations file from Step 1.
When you visit the brand page at the path `/fr/rustic-roots`, you should see the translated brand name, along with any translated brand metadata if you view the page source:
## Translate Makeswift content
The Catalyst storefront you created with One-Click Catalyst is connected to a Makeswift site. In the [Makeswift editor](https://docs.makeswift.com/product/builder-basics), you can add localized text for any component that you’re editing in Makeswift.
To try this out, make sure your development server is still running and visit the Makeswift editor by clicking the **Edit in Makeswift** button in the control panel. In the Makeswift editor, switch to your Development (Dev) Makeswift site.
To add a locale in Makeswift, open your site settings and go to the **Locales** tab. Then, click the **+ Add locale** button. This tutorial adds `fr`.
> **Info**
>
> Locales you add when creating your storefront with One-Click Catalyst are added to Makeswift automatically. Locales you add or change later must be added or updated in Makeswift manually.
You should now be able to switch to the French locale in Makeswift.
With the French locale selected, a message says that the localized page inherits from the default locale. To stop inheriting from the default and start customizing the content for the localized page, click the **Edit for this locale** button.
You can now customize the content for the French locale. This doesn't affect the content in the default locale. In the canvas, click on the Slideshow component and change its text in the properties sidebar. You can also localize other properties like the slideshow image and its alt text.
For non-default locales, make sure you [toggle the page to be online](https://docs.makeswift.com/product/page/metadata#metadata) in the sidebar before publishing.
## Next steps
* Translate more of your storefront's fixed text with [Static Translations](/developer/docs/storefront/catalyst/features/localization/static-translations).
* Sell in multiple regions by following the [Catalyst Multi-Storefront Setup](/developer/docs/storefront/catalyst/features/localization/multi-storefront/setup) tutorial.
* Build your own language selector with the GraphQL Storefront API. See [Create a custom language selector](/developer/docs/storefront/catalyst/features/localization/multi-language/overview#create-a-custom-language-selector).