You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/storefront/catalyst/content-management/internationalization/multi-language/overview.mdx
+2-7Lines changed: 2 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,10 +17,6 @@ BigCommerce supports multiple locales for shoppers in different regions.
17
17
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).
18
18
* Add translations for categories and locations to multiple locales added to Catalyst channel. Learn about how to use the [GraphQL Admin API](https://developer.bigcommerce.com/docs/store-operations/translations) to add translations to a single channel and locale.
19
19
20
-
<Callouttype="info">
21
-
Managing locales (in Control Panel, CLI, or via the GraphQL Admin API) is available for Catalyst channels. As of `October 2025`, all Catalyst stores have the multi-language feature enabled by default. On stores where multi-language is disabled, locale mutations and Channel Manager locale controls aren't available.
22
-
</Callout>
23
-
24
20
## Default Catalyst features
25
21
26
22
### Manage language settings
@@ -37,8 +33,6 @@ Out of the box, the Catalyst storefront displays translated product data for the
37
33
38
34
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.
39
35
40
-
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.
41
-
42
36
## Customization
43
37
44
38
Catalyst provides built-in features, but you can further customize its functionality to fit your needs.
@@ -51,7 +45,7 @@ You can manage language settings within a channel using the GraphQL Admin API or
51
45
* Setting a default language
52
46
* Activating or deactivating specific languages
53
47
54
-
By default, a new Catalyst project starts with a single locale. Add and manage additional locales using the GraphQL Admin API or the CLI. For detailed instructions, refer to the [Locale Configuration Guide](https://developer.bigcommerce.com/docs/store-operations/settings/locales).
48
+
By default, Catalyst does not include multilingual support when installing a storefront via the CLI. However, you can enable and manage locales using the GraphQL Admin API or the CLI. For detailed instructions, refer to the [Locale Configuration Guide](https://developer.bigcommerce.com/docs/store-operations/settings/locales).
55
49
56
50
### Configuring language settings using the CLI
57
51
@@ -97,3 +91,4 @@ By default, BigCommerce offers translations for the checkout page and emails in
Copy file name to clipboardExpand all lines: docs/storefront/catalyst/content-management/internationalization/multi-language/setup.mdx
+22-27Lines changed: 22 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,12 +12,7 @@ Follow the [Getting Started with Catalyst](/docs/storefront/catalyst/getting-sta
12
12
13
13
## Adding a locale in Catalyst
14
14
15
-
<Callouttype="info">
16
-
**Control Panel access:** The Localization tab in Channel Manager for adding/removing locales is available for Catalyst channels in **Settings** > **Localization** or via editing the channel in **Channel Manager**.
17
-
**Default:** multi-language is enabled by default on all Catalyst stores.
18
-
</Callout>
19
-
20
-
You can add additional languages to your storefront when you initially create your Catalyst storefront through the Control Panel. If you didn't do so, you have a couple of options.
15
+
You can add additional languages to your storefront when you initially create your Catalyst storefront through the Control Panel. If you didn’t do so, you have a couple of options.
21
16
22
17
You can enable more locales for your storefront through the Control Panel:
23
18
@@ -39,17 +34,17 @@ Go ahead and start your development server. When you visit the running applicati
39
34
40
35
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.
41
36
42
-
You might have to restart your development server to see the new locale in your storefront selector.
37
+
You might have to restart your development server to see the new locale in your storefront selector.
43
38
44
39
## Locale-specific URLs
45
40
46
-
Now, try switching to your newlyadded locale, in my case `fr`, in the storefront selector. Notice the locale prefix, e.g. `fr`, has been applied to the pathname in the URL, `http://localhost:3000/fr`. This is because Catalyst uses [prefix-based routing](https://next-intl.dev/docs/routing/middleware#locale-detection) from the [`next-intl`](https://next-intl.dev/) library which means the locale prefix will be added to the pathname of each localized page.
41
+
Now, try switching to your newly-added locale, in my case `FR`, in the storefront selector. Notice the locale prefix, e.g. `fr`, has been applied to the pathname in the URL, `http://localhost:3000/fr`. This is because Catalyst uses [prefix-based routing](https://next-intl.dev/docs/routing/middleware#locale-detection) from the [`next-intl`](https://next-intl.dev/) library which means the locale prefix will be added to the pathname of each localized page.
47
42
48
43
## Translating static strings
49
44
50
45
The Catalyst source code includes text elements that can be translated using predefined static strings. These static translations are housed in the `core/messages` folder in your Catalyst app. You can then access the static translations within your components using the `next-intl` library.
51
46
52
-
Let’s explore more of how this works! Static string translations are already provided for the locales that Catalyst supports out of the box, like `fr`, so let’s start there.
47
+
Let’s explore more of how this works! Static string translations are already provided for the locales that Catalyst supports out of the box, like `FR`, so let’s start there.
53
48
54
49
1. In the `core/messages` folder, open the pre-populated translation file for French, `fr.json`. You should see predefined translation keys — for example, those used in an empty cart message — along with their translations.
55
50
@@ -73,7 +68,7 @@ Let’s explore more of how this works! Static string translations are already p
73
68
// load all the translation strings from core/messages under the 'Cart' namespace.
74
69
75
70
const t =awaitgetTranslations('Cart');
76
-
71
+
77
72
// pass translated strings into your components
78
73
const emptyState = (
79
74
<>
@@ -89,13 +84,13 @@ Let’s explore more of how this works! Static string translations are already p
89
84
}
90
85
```
91
86
92
-
3. If you click on the cart, you should see a translated empty cart message if you switch your locale to `FR`.
87
+
3. If you click on the cart, you should see a translated empty cart message if you switch your locale to `FR`.
As you’ve noticed, after you enable a supported locale, the text for some components on your page will already be translated into this language. But if your locale is unsupported, you’ll need to [define your own static string translations](/docs/storefront/catalyst/content-management/internationalization/static-translations#translation-file) in this directory.
91
+
As you’ve noticed, after you enable a supported locale, the text for some components on your page will already be translated into this language. But if your locale is unsupported, you’ll need to [define your own static string translations](/docs/storefront/catalyst/content-management/internationalization/static-translations#translation-file) in this directory.
97
92
98
-
When you create more components, you’ll want to access the translations from your file. Learn more about [how to use the translations](/docs/storefront/catalyst/content-management/internationalization/static-translations#using-keys-in-react-components) inside your Client and Server Components.
93
+
When you create more components, you’ll want to access the translations from your file. Learn more about [how to use the translations](/docs/storefront/catalyst/content-management/internationalization/static-translations#using-keys-in-react-components) inside your Client and Server Components.
99
94
100
95
## Translating dynamic data from BigCommerce
101
96
@@ -122,7 +117,7 @@ You can translate dynamic product data by sending GraphQL mutations with the [Gr
122
117
<br />
123
118
3. Download and import the [Postman collection for translations](https://storage.googleapis.com/bigcommerce-production-dev-center/template-files/catalyst/translations.postman_collection.json).
124
119
125
-
The Postman collection includes requests for products, categories, and brands, but we’ll focus on the product ones for now.
120
+
The Postman collection includes requests for products, categories, and brands, but we’ll focus on the product ones for now.
126
121
<br />
127
122
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.
128
123
@@ -132,13 +127,13 @@ Your products should now have French translations for their names and descriptio
132
127
133
128

134
129
135
-
#### Textual search
130
+
#### Textual search
136
131
137
-
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 let’s move on to search keywords.
132
+
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 let’s move on to search keywords.
138
133
139
-
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.
134
+
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.
140
135
141
-
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](https://developer.bigcommerce.com/docs/store-operations/catalog/msf-international-enhancements/product-attributes#set-storefront-details-for-a-locale).
136
+
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](https://developer.bigcommerce.com/docs/store-operations/catalog/msf-international-enhancements/product-attributes#set-storefront-details-for-a-locale).
142
137
143
138
Let’s try it out. In the same Postman Collection you imported earlier, open the [Postman Collection Runner](https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/) again. This time, select the **Product Search Keywords** mutation in the run sequence. You can use the same [Product Translations file](https://storage.googleapis.com/bigcommerce-production-dev-center/template-files/catalyst/product-translations.json) you downloaded earlier since it also includes translations for search keywords.
144
139
@@ -164,7 +159,7 @@ Follow along to run sample translation data using Postman.
164
159
<br />
165
160
2. Open the same [Postman collection for translations](https://storage.googleapis.com/bigcommerce-production-dev-center/template-files/catalyst/translations.postman_collection.json) that you imported when you were translating product data. You can use the same sample Postman environment you imported earlier.
166
161
167
-
3. Run the requests in the [Postman Collection Runner](https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/). Select only the **Categories** mutation in the run sequence and upload the Categories Translations file from Step 1.
162
+
3. Run the requests in the [Postman Collection Runner](https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/). Select only the **Categories** mutation in the run sequence and upload the Categories Translations file from Step 1.
@@ -174,12 +169,12 @@ Once again, you should notice the category headings change in the header once yo
174
169
175
170
### Translating brands
176
171
177
-
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.
172
+
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.
178
173
Before translating brands, we’re going to first add a brand to a product, so that the brand is available on your storefront:
179
174
180
-
1. Under the **Products** tab, click on **Products**.
175
+
1. Under the **Products** tab, click on **Products**.
181
176
2. Click on the ellipses **(...)** next to the product you want to add a brand. Click **Edit**.
182
-
3. In the **Basic Information** section, select the Rustic Roots brand in the dropdown. This brand came with the sample catalog data.
177
+
3. In the **Basic Information** section, select the Rustic Roots brand in the dropdown. This brand came with the sample catalog data.
183
178
184
179
To add translations, you can send [GraphQL mutations](https://developer.bigcommerce.com/docs/store-operations/translations/brands) using the GraphQL Admin API. Follow along to run sample translation data using Postman.
185
180
@@ -200,9 +195,9 @@ When you visit the brand page at the path `/fr/rustic-roots`, you should see the
200
195
201
196
## Translating Makeswift content
202
197
203
-
The Catalyst storefront you created with [One-Click Catalyst](/docs/storefront/catalyst/getting-started/workflows/one-click-catalyst) comes integrated with 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.
198
+
The Catalyst storefront you created with [One-Click Catalyst](/docs/storefront/catalyst/getting-started/workflows/one-click-catalyst) comes integrated with 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.
204
199
205
-
To try this out, make sure your development server is still running and visit the Makeswift editor by clicking the **Edit in Makeswift** button from your Control Panel. In the Makeswift editor, switch to your Development (Dev) Makeswift site.
200
+
To try this out, make sure your development server is still running and visit the Makeswift editor by clicking the **Edit in Makeswift** button from your Control Panel. In the Makeswift editor, switch to your Development (Dev) Makeswift site.
206
201
207
202
To add a locale in Makeswift, open your site settings and go to the **Locales** tab. Then, click the **+ Add locale** button. In this case, we’ve added `fr`.
208
203
@@ -218,11 +213,11 @@ You should now be able to switch to the French locale in Makeswift.
218
213
219
214
With the French locale selected, you’ll notice a message that informs you 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.
220
215
221
-
Now you can now customize the content specifically for the French locale. Note that this does not affect the content in the base 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.
216
+
Now you can now customize the content specifically for the French locale. Note that this does not affect the content in the base 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.
220
+
For non-default locales, make sure you [toggle the page to be online](https://docs.makeswift.com/product/page/metadata#metadata) in the sidebar.
226
221
227
222
228
223
## Wrap up
@@ -231,4 +226,4 @@ Now, you should have a Catalyst app that fully supports multiple languages. Reme
0 commit comments