sfnext-i18n

Storefront Next Internationalization

Storefront Next uses i18next with a server instance (all languages loaded) and a browser instance (loads the active language as a static JS chunk). The infrastructure comes from @salesforce/storefront-next-runtime/i18n; your project owns the translations in src/locales/. The full guide ships in your project as docs/README-I18N.md. Caution: its locale-detection and set-locale passages are outdated; trust the code and this skill.

Which API to use

import { useTranslation } from 'react-i18next';

export function AddToCart({ count }: { count: number }) {
    const { t } = useTranslation('product'); // namespace = top-level key in translations.json
    return <button>{t('addToCart', { count })}</button>;
}

import type { LoaderFunctionArgs } from 'react-router';
import { getTranslation } from '@salesforce/storefront-next-runtime/i18n';

export function loader({ context }: LoaderFunctionArgs) {
    const { t } = getTranslation(context); // server: pass the router context
    return { title: t('product:title') };
}

• Without a namespace argument, prefix keys: useTranslation() then t('product:title') works. You lose key autocomplete, not correctness.
• Client-only non-component code may call getTranslation() with no argument.
• Other exports from the same module: getLocale, mockI18nContext (tests), createI18nMiddleware.

File layout

src/locales/
├── index.ts               # barrel: explicit import of every locale
├── types.ts               # DeepPartial<T>
└── en-US/
    ├── index.ts           # merges translations.json + aggregated extension strings
    └── translations.json  # ONE file; each top-level key is a namespace

The project ships 17 locale directories (ls src/locales). Each translations.json is a single file whose top-level keys (product, cart, checkout, routeError, ...) are namespaces. There is no separate per-namespace file.