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:

• Static string translations in components
• Dynamic data from BigCommerce
• Makeswift content

Prerequisites

Follow the Getting Started with Catalyst (opens in a new tab) documentation to create your Catalyst storefront using One-Click Catalyst (opens in a new tab). Then, follow the Local Development (opens in a new tab) 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:

1. Under the Channels tab, choose your Catalyst Storefront and click on the Localization tab.
2. Click Add new Language and save your language selection. The new language should be active by default, but if you ever need to enable or disable it, you can use the settings here.

Your new locale should now show up in your locally running application. 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. For my storefront, I chose English as my default language and added French (fr) as my 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.

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.

   {
     "Cart": {
       "Empty": {
         "title": "Votre panier est vide.",
         "subtitle": "Ajoutez quelques produits pour commencer.",
         "cta": "Continuer mes achats"
       },
     }
   }

2. 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 calling getTranslations. 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" />
       </>
     );
   }

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 (opens in a new tab) 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 (opens in a new tab) 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.

BigCommerce provides a quick way to translate dynamic product data in bulk through the Translations UI App (opens in a new tab):

1. Click on this link to install the app (opens in a new tab)
2. Navigate to the Translation App in your Control Panel:
   a. Click on the Apps tab
   b. Click on the Translations App
   c. Click Start translation workflow
   
3. Import your translations:
   a. Click the Action tab
   b. Choose Products as your resource type and select your locale
   c. Upload a CSV file with your translations
   

To add my french product translations, I’m using this sample CSV file (opens in a new tab) to upload data in bulk for the sample Catalyst storefront data. If you have a different language, you need to update the CSV headings with your locale before using it. You can’t add translations for the default locale, which come directly from the product data, but my CSV file includes it for your reference.

Behind the scenes, the Translations App uses the GraphQL Admin API to add localized data to the products in your catalog. You could also send GraphQL mutations with the GraphQL Admin API (opens in a new tab) to translate product data instead.

Translating categories

Similar to products, category metadata is fetched dynamically from BigCommerce. You can translate category metadata using the Translations UI App in a similar manner. To add my French category translations, I’m using this sample CSV file (opens in a new tab) to upload data in bulk for the sample Catalyst storefront data.

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.

You can also send GraphQL mutations with the GraphQL Admin API (opens in a new tab) to translate category data instead.

Translating Makeswift content

The Catalyst storefront you created with One-Click Catalyst (opens in a new tab) 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.

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 my mind the three scenarios we covered.

• Static string translations in components
• Dynamic data from BigCommerce
• Makeswift content