From c9c8cf769845b389d6cf1bddc7a23c217fb05830 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 30 Sep 2025 10:34:14 -0400 Subject: [PATCH 1/3] add updates to multilang being turned on by default in new stores --- .../multi-language/overview.mdx | 9 +++- .../multi-language/setup.mdx | 47 ++++++++++--------- 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/storefront/catalyst/content-management/internationalization/multi-language/overview.mdx b/docs/storefront/catalyst/content-management/internationalization/multi-language/overview.mdx index 816737b84..6c35168d8 100644 --- a/docs/storefront/catalyst/content-management/internationalization/multi-language/overview.mdx +++ b/docs/storefront/catalyst/content-management/internationalization/multi-language/overview.mdx @@ -17,6 +17,10 @@ BigCommerce supports multiple locales for shoppers in different regions. 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](https://developer.bigcommerce.com/docs/store-operations/translations) to add translations to a single channel and locale. + + Managing locales (in Control Panel, CLI, or via the GraphQL Admin API) is available for Catalyst channels. As of `October 2025`, new 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. + + ## Default Catalyst features ### Manage language settings @@ -33,6 +37,8 @@ Out of the box, the Catalyst storefront displays translated product data for the 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. @@ -45,7 +51,7 @@ You can manage language settings within a channel using the GraphQL Admin API or * Setting a default language * Activating or deactivating specific languages -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). +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). ### Configuring language settings using the CLI @@ -91,4 +97,3 @@ By default, BigCommerce offers translations for the checkout page and emails in ## Resources * [Locale Configuration](/docs/store-operations/settings/locales) - diff --git a/docs/storefront/catalyst/content-management/internationalization/multi-language/setup.mdx b/docs/storefront/catalyst/content-management/internationalization/multi-language/setup.mdx index 04114d5eb..cde1e9662 100644 --- a/docs/storefront/catalyst/content-management/internationalization/multi-language/setup.mdx +++ b/docs/storefront/catalyst/content-management/internationalization/multi-language/setup.mdx @@ -12,6 +12,11 @@ Follow the [Getting Started with Catalyst](/docs/storefront/catalyst/getting-sta ## Adding a locale in Catalyst + + **Control Panel access:** The Localization tab in Channel Manager for adding/removing locales is available for Catalyst channels. + **Default:** On newly created stores, multi-language is enabled by default. + + 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. You can enable more locales for your storefront through the Control Panel: @@ -34,17 +39,17 @@ Go ahead and start your development server. When you visit the running applicati 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. -You might have to restart your development server to see the new locale in your storefront selector. +You might have to restart your development server to see the new locale in your storefront selector. ## Locale-specific URLs -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. +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. ## Translating static strings 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. -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. +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. 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. @@ -68,7 +73,7 @@ Let’s explore more of how this works! Static string translations are already p // load all the translation strings from core/messages under the 'Cart' namespace. const t = await getTranslations('Cart'); - + // pass translated strings into your components const emptyState = ( <> @@ -84,13 +89,13 @@ Let’s explore more of how this works! Static string translations are already p } ``` -3. If you click on the cart, you should see a translated empty cart message if you switch your locale to `FR`. +3. If you click on the cart, you should see a translated empty cart message if you switch your locale to `FR`.