sfnext-i18n

Internationalization (i18n) Skill

This skill covers internationalization in Storefront Next using i18next with a dual-instance architecture (server + client).

Overview

• Server instance — Has access to all translations for all languages
• Client instance — Dynamically imports translations as JavaScript chunks
• Dual API — useTranslation() for components, getTranslation() for non-component code

Translation File Structure

Translations are organized as namespace files per locale, compiled into a TypeScript index:

src/locales/en-US/
├── index.ts              # Merges all namespace files + extensions
├── translations.json     # Default namespace (top-level keys become namespaces)
└── product.json          # "product" namespace (separate file)

src/locales/en-GB/
├── index.ts
├── translations.json
└── product.json

The index.ts imports all namespace files and extension translations:

import translations from '@/locales/en-US/translations.json';
import product from '@/locales/en-US/product.json';
import extensionTranslations from '@/extensions/locales/en-US/';

const allTranslations = { ...translations, product, ...extensionTranslations };
export default allTranslations satisfies ResourceLanguage;

Namespace structure in translations.json

Each top-level key is a namespace:

{
    "header": {
        "search": "Search",
        "account": "Account"
    },
    "footer": {
        "copyright": "© {{year}} Company"
    }
}

Separate namespace file (product.json)

{
    "title": "Product Details",
    "addToCart": "Add to Cart",
    "greeting": "Hello, {{name}}!",
    "itemCount_one": "{{count}} item",
    "itemCount_other": "{{count}} items"
}

Usage in Components

import { useTranslation } from 'react-i18next';

export function ProductCard() {
    const { t } = useTranslation('product');

    return (
        <div>
            <h1>{t('title')}</h1>
            <button>{t('addToCart')}</button>
            <p>{t('greeting', { name: 'John' })}</p>
            <p>{t('itemCount', { count: 5 })}</p>
        </div>
    );
}