Static Translations

You can translate the fixed text in your storefront’s interface, such as buttons and labels, into multiple languages with static strings. This page describes the required messages/ subdirectory, the translation file format, and how to make a locale available to shoppers. Catalyst uses the next-intl library to handle localization.

Required subdirectory

Each Catalyst project reserves a top level /messages/ subdirectory for localization. For your storefront to function properly, both the /messages/ subdirectory and the /messages/en.json file, which contains the default English phrases, must be present. You can localize static phrases by providing other JSON translation files in the /messages/ directory.

The default language file, en.json, is in US English. You can adjust its phrase strings to meet your needs.

Translation file

To translate static phrases, create a JSON file for each language you support.

Name your translation files based on the BCP 47 specification of language tags and country or region codes. For an overview of how these language tags are constructed, see Language tags in HTML and XML.

You can find a list of code subtags in the IANA Language Subtag Registry. These subtags are primitives that you can combine to create file name prefixes for individual regions. Here are some examples:

Translation keys

The JSON files should contain key-value pairs for each locale. You can define translations based on pre-defined keys used to translate the Catalyst storefront’s basic ecommerce functionality. Shoppers see the translated values you specify as static string translations.

Use the existing en.json file as a template for the schema. You can only provide translated values for the translation keys specified in the template.

For example, the en.json file contains the following translation keys:

"Home": {
  "FeaturedProducts": {
    "title": "Featured collection",
    "cta": "View more"
  },
  "NewestProducts": {
    "title": "New arrivals"
  }
}

In your newly-created JSON file, add a translation of the value to the new locale.

"Home": {
  "FeaturedProducts": {
    "title": "Collection en vedette",
    "cta": "Voir plus"
  },
  "NewestProducts": {
    "title": "Nouveautés"
  }
}

Enable the locale

Catalyst doesn’t keep a list of locales in code. It reads the enabled locales, and the subfolder each one is served at, from your store’s default channel (BIGCOMMERCE_CHANNEL_ID) at runtime. To make a new translation file available to shoppers, enable the matching locale on that channel in the control panel.

See Add a locale in Catalyst. No code change or redeploy is needed.

Name each translation file after the locale code you enable. For example, enabling French (fr) requires a messages/fr.json file.

Load a locale from another channel (optional)

If you want a locale to load data from a different channel, map the locale to that channel ID in the channels.config.ts file. The mapping key is the locale code, not the URL subfolder. Subfolders are set per locale in the control panel, and can differ from the code (for example, de served at /de-de).

For example, to have the fr locale use a channel ID of 12345, include the following:

const localeToChannelsMappings: Record<string, string> = {
  fr: '12345',
};

Use keys in React components

In a server component, load messages with getTranslations:

import { getTranslations } from 'next-intl/server';
// ...
export default async function Home() {
  const t = await getTranslations('Home');
  // ...
  return (
    <div>
      <FeaturedProductList
        products={featuredProducts}
        title={t('FeaturedProducts.title')}
      />
    </div>
  );
}

Client and shared components use regular hooks to translate messages:

'use client';
import { useTranslations } from 'next-intl';
// ...
const Component = () => {
  const t = useTranslations('Cart');
  // ...
  return (
    <Button>
      {t('proceedToCheckout')}
    </Button>
  );
}

Routing and locale detection

Catalyst uses next-intl’s default locale detection. When a shopper visits a URL without a locale subfolder, Catalyst picks a locale from the shopper’s locale cookie, set when they choose a locale in the locale switcher, and otherwise from the Accept-Language request header. Detection only chooses among the locales enabled in the control panel. To change this behavior, edit the routing configuration in createRouting in i18n/locale-routing.ts.

Next steps

• Follow the Catalyst Multi-Language Setup tutorial to translate static strings, catalog data, and Makeswift content for a new locale.
• See the next-intl documentation for message formatting options.