Localizing a Storefront into Multiple Languages
This tutorial walks you through how to translate your default Catalyst storefront into another language or locale, in this case French, for features that are available out of the box. It covers three different places where you can update translations for a locale:
Prerequisites
Follow the Getting Started with Catalyst documentation to create your Catalyst storefront using One-Click Catalyst. To follow along, choose the option to use sample catalog data. Then, follow the Local Development documentation to pull down the code and run locally.
Adding a locale in Catalyst
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:
- Under the Channels tab, choose your Catalyst Storefront and click on the Localization tab.
- Click Add new Language and save your language selection. You can use the settings here to enable the newly-added locale.
Your new locale should now show up in your locally running application.
Although newly added locales show up automatically when running locally, this is not the case for your deployed site. Within Catalyst, locales are only synced at build-time. This means, you will need to redeploy your Catalyst application for new locales to show up in your deployed site.
Go ahead and start your development server. When you visit the running application in the browser (localhost:3000
by default), in the top right corner, you should see a language selector that lets you toggle between locales, for example:
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.
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 (opens in a new tab) from the next-intl
(opens in a new tab) 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.
-
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.{ "Cart": { "Empty": { "title": "Votre panier est vide.", "subtitle": "Ajoutez quelques produits pour commencer.", "cta": "Continuer mes achats" }, } }
-
Open the Cart page component,
core/app/[locale]/(default)/cart/page.tsx
, for an example of how you can access the translations within a server component by callinggetTranslations
.next-intl
imports translations based on the current locale that it detects (opens in a new tab).
import { getTranslations } from 'next-intl/server'; export default async function Cart() { // 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 = ( <> <Slot label="Cart top content" snapshotId="cart-top-content" /> <CartEmptyState cta={{ label: t('Empty.cta'), href: '/shop-all' }} subtitle={t('Empty.subtitle')} title={t('Empty.title')} /> <Slot label="Cart bottom content" snapshotId="cart-bottom-content" /> </> ); }
-
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 in this directory.
When you create more components, you’ll want to access the translations from your file. Learn more about how to use the translations inside your Client and Server Components.
Translating dynamic data from BigCommerce
Catalyst fetches dynamic data from the BigCommerce backend. Each time Catalyst makes a GraphQL request to BigCommerce, the locale is sent with it. This ensures you get the right locale-specific content. It’s all handled automatically by the data-fetching client, so you don’t have to do anything extra.
Translating product data
The text in a given component comes from the translations in the source code but product data comes from BigCommerce. We still need to fetch product data dynamically, like the product name, variants, description, and more.
You can translate dynamic product data by sending GraphQL mutations with the GraphQL Admin API (opens in a new tab). Let’s start by translating the name and description of your sample products by sending a mutation to set basic product information (opens in a new tab). We’ll be running sample translation data using Postman.
Steps for making the GraphQL Admin API request
-
Download the Product Translations file (opens in a new tab).
This JSON file contains French translations for sample products that come with your Catalyst storefront. You will need to change the product IDs in the sample file to use the actual product IDs from your store. The English translations are included for reference, but aren’t used in the requests.
-
Download the Sample Postman environment (opens in a new tab) and import it into Postman (opens in a new tab). It includes the following environment variables (opens in a new tab), which you’ll need to populate:
store_hash
- the store hash from yourenv.local
filechannel_id
- the channel ID from yourenv.local
fileaccess_token
- a Store Level V2/V3 API token with theProducts
OAuth scope that you can get by creating an API Account (opens in a new tab)
Make sure to make this environment active (opens in a new tab) in Postman.
-
Download and import the Postman collection for translations (opens in a new tab).
The Postman collection includes requests for products, categories, and brands, but we’ll focus on the product ones for now.
-
Run the requests in the Postman Collection Runner (opens in a new tab). 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 let’s move on to 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 (opens in a new tab).
Let’s try it out. In the same Postman Collection you imported earlier, open the Postman Collection Runner (opens in a new tab) again. This time, select the Product Search Keywords mutation in the run sequence. You can use the same Product Translations file (opens in a new tab) 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:
Translating 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 (opens in a new tab).
Follow along to run sample translation data using Postman.
Steps for making the GraphQL Admin API request
-
Download the Category Translations file (opens in a new tab).
This file contains French translations for sample categories that come with your Catalyst storefront. You will need to change the category IDs in the sample file to use the actual category IDs from your store. The English translations are included for reference, but aren’t used in the requests.
-
Open the same Postman collection for translations (opens in a new tab) that you imported when you were translating product data. You can use the same sample Postman environment you imported earlier.
-
Run the requests in the Postman Collection Runner (opens in a new tab). Select only the Categories mutation in the run sequence and upload the Categories Translations file from Step 1.
Once again, you should notice the category headings change in the header once you refresh the page, along with any uploaded category metadata if you view the page source.
Translating 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, we’re going to first add a brand to a product, so that the brand is available on your storefront:
- Under the Products tab, click on Products.
- Click on the ellipses (...) next to the product you want to add a brand. Click Edit.
- In the Basic Information section, select the Rustic Roots brand in the dropdown. This brand came with the sample catalog data.
To add translations, you can send GraphQL mutations (opens in a new tab) using the GraphQL Admin API. Follow along to run sample translation data using Postman.
Steps for making the GraphQL Admin API request
-
Download the Brand Translations file (opens in a new tab).
This file contains French translations for sample brands that come with your Catalyst storefront. You will need to change the brand IDs in the sample file to use the actual brand IDs from your store. The English translations are included for reference, but aren’t used in the requests.
-
Open the same Postman collection for translations (opens in a new tab) that you imported when you were translating product data. You can use the same sample Postman environment you imported earlier.
-
Run the requests in the Postman Collection Runner (opens in a new tab). 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:
Translating Makeswift content
The Catalyst storefront you created with One-Click Catalyst comes integrated with a Makeswift site. In the Makeswift editor (opens in a new tab), 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 from your 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. In this case, we’ve added fr
.
Locales that you add initially when creating your storefront using One-Click Catalyst are automatically propagated. Any changes to locale after your storefront need to be manually added or updated in Makeswift.
You should now be able to switch to the French locale in Makeswift.
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.
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 (opens in a new tab) in the sidebar.
Wrap up
Now, you should have a Catalyst app that fully supports multiple languages. Remember as you continue to build out and customize your app, you’ll need to keep in mind the three scenarios we covered.
- Static string translations in components
- Dynamic data from BigCommerce
- Makeswift content