Internationalization (i18n)

This project uses i18next (with react-i18next and remix-i18next) for internationalization. The implementation follows a dual-instance architecture with server-side and client-side i18next instances. Locale detection is handled by the multisite middleware, which resolves the locale before i18next initializes.

Quick Start Examples

For React components:

1import { useTranslation } from "react-i18next";
2
3function MyComponent() {
4  // Get translation function for 'product' namespace - dynamically renders localized text based on user's language
5  const { t } = useTranslation("product");
6  return <h1>{t("title")}</h1>;
7}

For everything else (loaders, actions, utilities, helpers, and tests):

1import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
2
3// Client-side or non-component code
4const { t } = getTranslation();
5const message = t("product:title");
6
7// Server-side (loaders/actions) - pass the context
8export function loader(args: LoaderFunctionArgs) {
9  const { t } = getTranslation(args.context);
10  return { title: t("product:title") };
11}

Architecture Overview

The i18n layer is split between the SDK and the template:

SDK (@salesforce/storefront-next-runtime/i18n) — generic infrastructure: middleware factory, context, shared interpolation config
SDK (@salesforce/storefront-next-runtime/i18n/client) — browser-only client initialization
Template — translations (src/locales/), configuration, type augmentation, root.tsx wiring

We maintain two separate instances of i18next:

Server-side instance: Has access to all translations for the entire site
Client-side instance: Dynamically imports translations as static JavaScript chunks

Both instances support dynamic language switching at run time without page reloads.

Server-Side and Client-Side Flow

Server-side middleware detects the user locale and initializes i18next
Server has access to all translations from all locales and renders SSR content with translations
Client-side initializes its own i18next instance, reading the language from the HTML lang attribute to prevent hydration mismatches
- The initI18next() function in root.tsx accepts an optional { language } parameter to ensure consistency between server and client
When a translation is first requested, the client dynamically imports ALL translations for the current language
- This triggers an HTTP request for a JavaScript chunk (e.g., /assets/locales-en-[hash].js)
- The chunk is served as a static asset (pre-built, minified, and cached with long-term headers)
- Much more efficient than an API endpoint: no server processing, CDN-friendly, immutable caching
All namespaces for that language are loaded and cached in memory
Subsequent translation requests use the cached data (no additional requests)
When users switch languages, the client loads the new language’s translations dynamically (if not already cached) and updates the UI immediately

Configuration

Supported Languages and Currencies

Languages and currencies are configured in config.server.ts in two sections that must be kept in sync.

i18n - Translation system configuration:

1i18n: {
2    fallbackLng: 'en-GB',
3    supportedLngs: ['it-IT', 'en-US', 'en-GB'], // The fallback language should be LAST
4}

commerce.sites - Per-site locale and currency configuration:

1commerce: {
2    sites: [
3        {
4            id: 'RefArchGlobal',
5            defaultLocale: 'en-GB',
6            defaultCurrency: 'GBP',
7            supportedLocales: [
8                { id: 'en-GB', preferredCurrency: 'GBP' },
9                { id: 'it-IT', preferredCurrency: 'EUR' },
10                { id: 'en-US', preferredCurrency: 'USD' },
11            ],
12            supportedCurrencies: ['EUR', 'GBP'],
13        },
14    ],
15}

The i18next middleware reads i18n.fallbackLng and i18n.supportedLngs from the config automatically. You don’t need to configure the middleware separately.

Keep these configurations in sync.

The locales in i18n.supportedLngs must match the id values across all entries in commerce.sites[].supportedLocales.
Each locale in supportedLocales has a preferredCurrency that matches one of the site’s supportedCurrencies.
Each locale in i18n.supportedLngs must have a corresponding translation directory under src/locales/.
If you add a new language, update both i18n.supportedLngs and the relevant site’s supportedLocales, and create the translation files.
If the arrays don’t match, you can get partial translations or locale/currency mismatches.

Important

Locale Detection

Locale detection is handled by the multisite middleware, which runs before i18next initializes. The multisite middleware resolves the locale using a configurable detection chain (by default: URL path, query string, cookie, HTTP header) and passes the resolved locale to i18next via an internal request map. The i18next middleware then initializes with the resolved locale.

If no locale can be resolved from any source, the system falls back to the configured fallbackLng.

For details on how locale detection works and how to customize the detection order, see Configure Site and Locale Detection.

Currency System

The app supports independent locale and currency switching.

Locale-based currency: Each locale in commerce.sites[].supportedLocales has a preferredCurrency that’s used by default.
Manual currency selection: Users can manually select any currency from commerce.sites[].supportedCurrencies, which takes precedence over the locale’s preferred currency.
Currency priority: User’s manual selection (cookie) → Locale’s preferred currency → Site’s default currency.

See the Currency Switcher component in src/components/currency-switcher/ for the implementation.

Usage Examples

In React Components

Use the useTranslation hook from react-i18next.

1import { useTranslation } from "react-i18next";
2
3function ProductInfo() {
4  // Specify the namespace to load
5  const { t } = useTranslation("product");
6  // NOTE: without passing in a namespace, the above hook uses `translation` namespace by default.
7  // Since we don't have such namespace in our translations, the `t('namespace:key')` still works,
8  // but its autocomplete no longer works in your IDE.
9
10  return (
11    <div>
12      <h1>{t("title")}</h1>
13      <p>{t("description")}</p>
14      <button>{t("addToCart")}</button>
15    </div>
16  );
17}

With multiple namespaces:

1import { useTranslation } from "react-i18next";
2
3function ProductPage() {
4  // Load multiple namespaces at once
5  const { t } = useTranslation(["home", "product"]);
6
7  return (
8    <div>
9      <h1>{t("home:title")}</h1>
10      <p>{t("product:description")}</p>
11      <button>{t("product:addToCart")}</button>
12    </div>
13  );
14}

With interpolation:

1const { t } = useTranslation("cart");
2const greeting = t("greeting", { name: "John" }); // "Hello John"

With pluralization:

1const { t } = useTranslation("cart");
2const text = t("summary.itemsInCart", { count: 1 }); // "1 item in cart"
3const text2 = t("summary.itemsInCart", { count: 3 }); // "3 items in cart"

In Non-Component Code

Use the getTranslation utility for tests, utilities, or any non-React code.

1import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
2
3// In tests
4describe("ActionCard", () => {
5  const { t } = getTranslation();
6
7  test("shows edit button", () => {
8    render(<ActionCard onEdit={vi.fn()} />);
9    const button = screen.getByRole("button", { name: t("actionCard:edit") });
10    expect(button).toBeInTheDocument();
11  });
12});
13
14// In utility functions
15export function getCountryName(countryCode: string): string {
16  const { t } = getTranslation();
17  return t(`countries:${countryCode}.name`, { defaultValue: countryCode });
18}
19
20// In form schemas (for Zod error messages)
21const schema = z.object({
22  email: z.string().email(t("error:validation.invalidEmail")),
23});

In Route Loaders and Actions (Server-Side)

Use getTranslation with the context parameter for server-side translations.

1import { getTranslation, i18nextContext } from "@salesforce/storefront-next-runtime/i18n";
2import type { LoaderFunctionArgs } from "react-router";
3
4export function loader(args: LoaderFunctionArgs) {
5  // Get translations by passing the context
6  const { t } = getTranslation(args.context);
7  const translatedTitle = t("product:title");
8
9  // Get the current locale for formatting (if needed)
10  const i18nextData = args.context.get(i18nextContext);
11  const locale = i18nextData?.getLocale() ?? "en-GB";
12  const date = new Date().toLocaleDateString(locale, {
13    year: "numeric",
14    month: "2-digit",
15    day: "2-digit",
16  });
17
18  return { translatedTitle, date };
19}

In actions with error handling:

1import type { ActionFunctionArgs } from "react-router";
2import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
3
4export async function action(args: ActionFunctionArgs) {
5  const { t } = getTranslation(args.context);
6
7  try {
8    // ... perform action
9    return { success: true, message: t("product:addedToCart", { productName: "Widget" }) };
10  } catch (error) {
11    return { success: false, message: t("error:api.unexpectedError") };
12  }
13}

File Structure

1src/locales/
2├── index.ts                # Exports all language resources
3├── en-GB/
4│   ├── index.ts            # Exports English (GB) translations
5│   └── translations.json   # All English (GB) translations (namespaced)
6├── en-US/
7│   ├── index.ts            # Exports English (US) translations
8│   └── translations.json   # All English (US) translations (namespaced)
9└── it-IT/
10    ├── index.ts            # Exports Italian translations
11    └── translations.json   # All Italian translations (namespaced)
12
13src/extensions/
14├── my-extension/
15│   └── locales/
16│       ├── en-GB/
17│       │   └── translations.json   # Extension translations (English GB)
18│       ├── en-US/
19│       │   └── translations.json   # Extension translations (English US)
20│       └── it-IT/
21│           └── translations.json   # Extension translations (Italian)
22└── locales/                # Auto-generated (do not edit manually)
23    ├── en-GB/
24    │   └── index.ts        # Aggregated extension translations
25    ├── en-US/
26    │   └── index.ts        # Aggregated extension translations
27    └── it-IT/
28        └── index.ts        # Aggregated extension translations
29
30src/components/
31└── locale-switcher/
32    └── index.tsx           # Client component for switching languages
33
34src/middlewares/
35└── i18next.server.ts       # Thin wrapper around SDK's createI18nMiddleware()
36
37src/routes/
38└── action.set-locale.ts    # Server action to persist locale preference

The i18n utilities (getTranslation, getLocale, mockI18nContext, createI18nMiddleware, initI18next) are provided by the SDK and split across two subpaths:

@salesforce/storefront-next-runtime/i18n — server-capable APIs (getTranslation, getLocale, mockI18nContext, createI18nMiddleware). Safe to import from server modules, route modules, and components.
@salesforce/storefront-next-runtime/i18n/client — browser-only APIs (initI18next). This entry pulls in i18next-browser-languagedetector, which has no Node support, so it must only be imported from client-side code (e.g. inside useEffect in root.tsx). Importing it from a *.server.ts file will fail to bundle and is blocked by ESLint.

Adding New Translations

Approach: Single JSON File Per Language

All translations are stored in a single JSON file per language with namespace-based organization.

Understanding Namespaces

i18next uses the concept of namespaces to organize translations into logical groups. In our implementation, namespaces are simply the top-level keys in each translations.json file. For example, "common", "product", "checkout", and "myNewFeature" are all namespaces that help organize translations by feature or domain.

src/locales/en-GB/translations.json:

1{
2  "common": {
3    "loading": "Loading",
4    "product": "the product"
5  },
6  "product": {
7    "title": "Product Details",
8    "addToCart": "Add to Cart",
9    "greeting": "Hello, {{name}}!",
10    "itemCount": {
11      "zero": "No items",
12      "one": "{{count}} item",
13      "other": "{{count}} items"
14    }
15  },
16  "myNewFeature": {
17    "welcome": "Welcome to the new feature"
18  }
19}

src/locales/it-IT/translations.json:

1{
2  "common": {
3    "loading": "Caricamento",
4    "product": "il prodotto"
5  },
6  "product": {
7    "title": "Dettagli del Prodotto",
8    "addToCart": "Aggiungi al Carrello",
9    "greeting": "Ciao, {{name}}!",
10    "itemCount": {
11      "zero": "Nessun articolo",
12      "one": "{{count}} articolo",
13      "other": "{{count}} articoli"
14    }
15  },
16  "myNewFeature": {
17    "welcome": "Benvenuto nella nuova funzione"
18  }
19}

Using Your New Translations

1// In React components
2const { t } = useTranslation('myNewFeature');
3<p>{t('welcome')}</p>
4
5// In non-component code
6const { t } = getTranslation();
7const message = t('myNewFeature:welcome');
8
9// Simple translation
10<p>{t('title')}</p>
11
12// With interpolation
13<p>{t('greeting', { name: 'John' })}</p>
14
15// With pluralization
16<p>{t('itemCount', { count: items.length })}</p>

Extension Translations

Extensions can have their own translation files that are automatically discovered and integrated into the i18n system. Extension authors can keep translations co-located with their extension code.

File Structure for Extensions

Create translation files within your extension directory using this structure:

1src/extensions/
2├── my-extension/
3│   ├── components/
4│   ├── locales/
5│   │   ├── en-GB/
6│   │   │   └── translations.json
7│   │   ├── en-US/
8│   │   │   └── translations.json
9│   │   └── it-IT/
10│   │       └── translations.json
11│   └── index.ts

Namespace Convention

Extension translations automatically use the extPascalCase naming convention based on the extension folder name.

store-locator → extStoreLocator
bopis → extBopis
my-extension → extMyExtension

This convention prevents namespace collisions between extensions and core app translations.

Using Extension Translations

This example shows how to use an extension translation in a React component.

1import { useTranslation } from "react-i18next";
2
3export function DeliveryOptions() {
4  // Use your extension's namespace
5  const { t } = useTranslation("extBopis");
6
7  return (
8    <div>
9      <h3>{t("deliveryOptions.title")}</h3>
10      <button>{t("deliveryOptions.pickupOrDelivery.pickUpInStore")}</button>
11    </div>
12  );
13}

This example shows how to use an extension translation in non-component code.

1import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
2
3export function getDeliveryMessage() {
4  const { t } = getTranslation();
5  // Use namespace prefix with colon
6  return t("extBopis:deliveryOptions.title");
7}

This example shows how to use an extension translation in route loaders or actions.

1import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
2import type { LoaderFunctionArgs } from "react-router";
3
4export function loader(args: LoaderFunctionArgs) {
5  const { t } = getTranslation(args.context);
6  return {
7    message: t("extBopis:storePickup.title"),
8  };
9}

How Locale Discovery Works

The locale aggregation command (sfnext locales aggregate-extensions) is specifically for extension translations only. Main app translations in /src/locales/ aren’t aggregated by this command—they’re imported directly.

Important

The script scans two locations to discover all supported locales:

Main app locales: /src/locales/{locale}/
Extension locales: /src/extensions/{extension-name}/locales/{locale}/

The script merges locales from both sources and generates extension-only aggregation files under /src/extensions/locales/ for each discovered locale. This means:

If your main app supports Italian (it-IT) but none of your extensions have Italian translations, an empty aggregation file is still generated for it-IT.
If an extension provides translations for a locale not in the main app, those translations are still aggregated (though the main app doesn’t use them unless configured).
Extensions without a locales folder are automatically skipped—no error is thrown.

Example Scenario:

Main app: en-GB, en-US, it-IT translations
Extension A: en-GB, en-US translations
Extension B: en-GB translations only
Extension C: No locales folder

Result: Extension aggregation files generated in /src/extensions/locales/ for en-GB, en-US, and it-IT:

en-GB/index.ts: Contains Extension A + Extension B translations only.
en-US/index.ts: Contains Extension A translations only.
it-IT/index.ts: Empty (no extensions have it).

Main app translations remain in /src/locales/ and aren’t affected by this aggregation process.

Note

Adding Translations to an Extension

1. Create the translation files:

Create locales/{lang}/translations.json within your extension directory for each supported language.

Example: src/extensions/bopis/locales/en-US/translations.json

1{
2  "deliveryOptions": {
3    "title": "Delivery:",
4    "pickupOrDelivery": {
5      "shipToAddress": "Ship to Address",
6      "pickUpInStore": "Pick Up in Store"
7    }
8  },
9  "storePickup": {
10    "title": "Store Pickup Location",
11    "viewButton": "View",
12    "closeButton": "Close"
13  }
14}

2. Translations are automatically aggregated:

When you run pnpm dev or pnpm build, the system automatically:

Discovers all extension translation files.
Aggregates them with the appropriate namespace.
Makes them available to your extension code.

No manual configuration is required.

Switching Languages and Currencies at Run Time

Language Switching

Users can switch languages dynamically without reloading the page using the LocaleSwitcher component. The language change happens in two steps:

Client-side update: Immediately changes the displayed language using i18next’s changeLanguage() method
Server-side persistence: Submits to a server action that sets the lng cookie to persist the preference across page reloads

Using the LocaleSwitcher Component

The project includes a pre-built LocaleSwitcher component to drop into your UI:

1import LocaleSwitcher from "@/components/locale-switcher";
2
3export function Footer() {
4  return (
5    <footer>
6      {/* Other footer content */}
7      <LocaleSwitcher />
8    </footer>
9  );
10}

Building Your Own Language Switcher

For a custom implementation, here’s how to implement language switching. In a multisite setup, the locale switcher must rebuild the current URL with the new locale prefix and trigger a full page reload to revalidate all loaders.

1"use client";
2
3import { useTranslation } from "react-i18next";
4import { useFetcher } from "react-router";
5import {
6  buildUrl,
7  sanitizePrefix,
8  resolvePrefix,
9} from "@salesforce/storefront-next-runtime/multi-site";
10import { useConfig } from "@salesforce/storefront-next-runtime/config";
11import { useCurrentSiteAndLocaleRef } from "@/hooks/use-current-site-and-locale-ref";
12
13export function MyLanguageSwitcher() {
14  const { i18n } = useTranslation();
15  const fetcher = useFetcher();
16  const config = useConfig();
17  const { siteRef, localeRef } = useCurrentSiteAndLocaleRef();
18
19  const handleLanguageChange = async (newLocale: string) => {
20    const newLocaleRef = config.localeAliasMap?.[newLocale] ?? newLocale;
21
22    // Strip current prefix, rebuild with new locale
23    const currentPrefix = config.url?.prefix
24      ? resolvePrefix(config.url.prefix, { siteId: siteRef, localeId: localeRef })
25      : "";
26    const barePath = sanitizePrefix(location.pathname, currentPrefix) || "/";
27
28    const pathname = buildUrl({
29      to: barePath,
30      urlConfig: config.url,
31      params: { siteId: siteRef, localeId: newLocaleRef },
32    });
33
34    // Step 1: Change language client-side for immediate UX
35    await i18n.changeLanguage(newLocale);
36
37    // Step 2: Persist to server cookie and navigate to new locale URL
38    const formData = new FormData();
39    formData.append("locale", newLocale);
40    formData.append("pathname", pathname);
41    await fetcher.submit(formData, {
42      method: "POST",
43      action: "/action/set-locale",
44    });
45
46    // Step 3: Full page reload to revalidate all loaders with new locale
47    window.location.href = pathname;
48  };
49
50  return (
51    <select value={i18n.language} onChange={(e) => void handleLanguageChange(e.target.value)}>
52      {config.i18n.supportedLngs.map((locale) => (
53        <option key={locale} value={locale}>
54          {locale}
55        </option>
56      ))}
57    </select>
58  );
59}

How It Works

The /action/set-locale server action, which is located at src/routes/action.set-locale.ts, receives the POST request and sets the locale cookie using the multisite cookie from router context. It then redirects to the provided pathname, which includes the new locale in the URL prefix.

1import { redirect, type ActionFunction } from 'react-router';
2import { getMultiSiteCookies } from '@salesforce/storefront-next-runtime/multi-site';
3
4export const action: ActionFunction = async ({ request, context }) => {
5    const formData = await request.formData();
6    const locale = formData.get('locale') as string;
7    const pathname = formData.get('pathname') as string;
8
9    if (!locale) {
10        throw new Response('Locale is required', { status: 400 });
11    }
12
13    const cookies = getMultiSiteCookies(context);
14    if (!cookies) {
15        throw new Response('Site and locale cookies were not initialized', { status: 500 });
16    }
17
18    const cookieHeader = await cookies.localeCookie.serialize(locale);
19
20    return redirect(pathname || '/', {
21        headers: {
22            'Set-Cookie': cookieHeader,
23        },
24    });
25};

Key Points

The client-side language change via i18n.changeLanguage() provides an immediate UX update.
In a multisite setup, locale switching triggers a full page reload to revalidate all loaders with the new locale and update the URL prefix.
The preference persists across sessions via the locale cookie (managed by the multisite middleware).
All client-side translations are loaded as static assets (one JavaScript chunk per language).
Switching languages triggers the dynamic import of the new language’s translations if not already loaded.

Currency Switching

Users can manually select a currency independent of their locale using the CurrencySwitcher component. When users switch to a new currency:

Server submits a server action.
Middlewares (client and server) run to update the latest currency into context.
Calls the updateBasket endpoint in SCAPI to update the currency accordingly.
Loader function revalidates and updates the UI to reflect the selected currency.

Using the CurrencySwitcher Component

1import CurrencySwitcher from "@/components/currency-switcher";
2import LocaleSwitcher from "@/components/locale-switcher";
3
4export function Footer() {
5  return (
6    <footer>
7      <div>
8        <h3>Language</h3>
9        <LocaleSwitcher />
10      </div>
11      <div>
12        <h3>Currency</h3>
13        <CurrencySwitcher />
14      </div>
15    </footer>
16  );
17}

Key Points

Currency selection is independent of locale
Manual currency selection takes precedence over locale’s preferred currency
The preference persists across locale changes
Falls back to locale’s preferred currency if no manual selection is made

Best Practices

Namespace by Route/Feature: Organize translations by feature area (for example, product, checkout, account).
Use the right tool:
- React components: Use useTranslation() hook
- Everything else: Use getTranslation() function
  - Non-component code (tests, utilities, schemas): getTranslation()
  - Server-side loaders/actions: getTranslation(context)
Use TypeScript: The project includes type-safe translations based on the English locale.
Interpolation: Use {{variable}} syntax in translation strings (not {variable}).
Pluralization: Use nested objects with zero, one, other keys for count-based translations.
Lazy Loading: Client-side translations are loaded on-demand when first requested.
Fallback Chain: Missing translations fall back to the configured fallbackLng.

Type Safety

The project is configured for type-safe translations. TypeScript autocompletes available keys and warn about missing translations:

1// ✅ TypeScript knows these keys exist
2const { t } = useTranslation("product");
3t("title");
4t("addToCart");
5
6// With namespace prefix in non-component code
7const { t } = getTranslation();
8t("product:title");
9t("cart:empty.title");
10
11// ❌ TypeScript will warn about this
12t("nonexistent.key");

Type definitions are generated from the English (GB) locale. In src/middlewares/i18next.server.ts:

1declare module "i18next" {
2  interface CustomTypeOptions {
3    resources: typeof resources["en-GB"]; // Use `en-GB` as source of truth for the types
4  }
5}