Localization

This guide describes how to provide static string translations for shoppers, including the required subdirectory, file structure, and project configuration.

Catalyst uses Next.js App Router Internationalization (i18n) (opens in a new tab) 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.

Translation file

To translate static phrases, create a JSON file for each language you choose to support. Each language that you want to support must have its own JSON file.

Name your translation files based on the BCP 47 specification (opens in a new tab) 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 (opens in a new tab).

You can find a list of code subtags in the IANA Language Subtag Registry (opens in a new tab). 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 (opens in a new tab). The translated values you specify will display to shoppers 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": {
  "Carousel": {
    "featuredProducts": "Featured Products",
    "newestProducts": "Newest products"
  }
}

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

"Home": {
  "Carousel": {
    "featuredProducts": "Produits populaires",
    "newestProducts": "Produits les plus recentsProduits"
  }
}

Read more about i18n messages in next-intl docs (opens in a new tab).

i18n configuration

After you created a language file, add its name to the routing.ts config file.

For example, if you created a fr.json file, include fr when you define the locales:

const locales = ['en', 'fr'] as const;

Subpath configuration (optional)

If you are using domain subpaths to localize your storefront for a specific language, map the subpath to a channel in the channels.config.ts file.

For example, if you want the /fr subpath to point a channel ID of 12345, include the following:

const localeToChannelsMappings: Partial<RecordFromLocales> = {
  fr: '12345',
};

Using keys in React components

The following example shows how messages can be used in server component:

import { getTranslations } from 'next-intl/server';
// ...
 
export default async function Home() {
  const t = await getTranslations('Home');
  // ...
 
  return (
    <div>
      <ProductCardCarousel
        products={featuredProducts}
        title={t('Carousel.featuredProducts')}
      />
    </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

Even though the next-intl library supports several locale detection strategies (opens in a new tab), Catalyst doesn't use any by default, as full internationalization support is still in progress. This strategy can be changed in the i18n.ts config file.

Currently, the shopper's browser preferences storefront detect locale by default. Catalyst uses the Accept-Language request HTTP header to determine which translation file to choose. If you do not have a JSON file matching the shopper's browser language, Catalyst will use the default English file.