Skip to main content

Adding a language to the storefront

Adding a language touches multiple layers: the shared locale configuration, translation files, the store config that sets the locale header, URL prefix mapping, and CMS content. This guide walks through each step.

1. Update the locale configuration​

The locale list lives in the shared site-config package. Add the new locale and its URL prefix:

// packages/site-config/src/i18n/config.ts
export const locales = [
  "nl-NL",
  "en-GB",
  "de-DE",  // new
] as const;

export const defaultLocale = "nl-NL";

export const localePrefixes: LocalePrefixes = {
  "nl-NL": "/nl",
  "en-GB": "/en",
  "de-DE": "/de",  // new
};

The locale prefix determines the URL path (e.g., /de/products/...). Next.js uses next-intl routing to match the prefix to the locale.

2. Add translation files​

Create a translation file for the new locale:

frontend/site/src/messages/de-DE.json

Copy an existing locale file (e.g., en-GB.json) as a starting point and translate the values:

{
  "common": {
    "addToCart": "In den Warenkorb",
    "checkout": "Zur Kasse",
    "search": "Suchen"
  }
}

next-intl loads the file automatically based on the locale from the URL.

3. Update the store configuration​

The store configuration determines which locales are available for each store deployment. Add the new locale to your store config:

// frontend/site/src/lib/store-config/my-store.ts
export const storeConfig: StoreConfig = {
  storeKey: "my-store",
  defaultLocale: "en-GB",
  locales: ["en-GB", "nl-NL", "de-DE"],
  currency: "EUR",
  country: "DE",
  // ...
};

The frontend reads this config to set the X-StoreContext-Locale header on every GraphQL request. Backend services use this header to return product names, descriptions, and category names in the correct language.

4. Add commercetools translations​

Make sure your commercetools project has the locale configured and that product data includes translations for the new language. This is typically managed through the Merchant Center or via the commercetools API.

In Terraform, add the locale to the project settings:

resource "commercetools_project_settings" "project" {
  languages  = ["en-GB", "nl-NL", "de-DE"]
  currencies = ["EUR"]
  countries  = ["GB", "NL", "DE"]
}

5. Localize CMS content​

If you use Contentful or Storyblok, enable the new locale in your CMS space and add translations for content entries. The CMS services in Evolve use the X-StoreContext-Locale header to fetch the correct language version of each entry.

For Contentful, add the locale in the space settings (or through Terraform). For Storyblok, the locale is extracted from the header and passed to the Storyblok API as the language parameter.

6. Verify​

Start the development server and navigate to the new locale prefix:

pnpm dev
# Open http://localhost:3000/de

Check that:

  • UI labels show the translated strings from de-DE.json
  • Product names and descriptions appear in German (if translations exist in commercetools)
  • CMS content renders in the correct language

Further reading​