Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
import { localeEndonym } from '@spree/core'
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
// Relative path, not `@/...`: dashboard-core ships source; the consuming
// project's `@/*` alias is theirs alone (see Phase 1's rationale).
import en from '../locales/en.json'
// localStorage key for the admin's chosen UI language. Shared by the login
// screen (pre-auth), the top-bar switcher, and the profile form so a choice
// made anywhere is honored on the next paint.
export const ADMIN_LOCALE_STORAGE_KEY = 'spree-admin-locale'
// Marks the locale key as auto-applied from a store's `admin_locale`
// (vs an explicit choice). Holds the storeId whose default is currently in
// effect, so crossing into a different store can re-apply that store's default
// while a genuine choice (switcher/profile/login) still wins everywhere. Mirrors
// legacy Rails: the `spree_admin_locale` cookie only ever held an explicit
// login-screen pick; the store default was re-derived per request, never stored.
const ADMIN_LOCALE_AUTO_STORE_KEY = 'spree-admin-locale-auto-store'
function readStorage(key: string): string | null {
try {
if (typeof localStorage === 'undefined') return null
return localStorage.getItem(key)
} catch {
return null
}
}
function writeStorage(key: string, value: string): void {
try {
if (typeof localStorage !== 'undefined') localStorage.setItem(key, value)
} catch {
// Restricted-storage contexts (Safari private mode, sandboxed iframes) throw
// on write; the choice still applies for this session via the booted `lng`.
}
}
function clearStorage(key: string): void {
try {
if (typeof localStorage !== 'undefined') localStorage.removeItem(key)
} catch {
// Ignore — see writeStorage.
}
}
// A full reload is deliberate for a language change: many labels (table columns,
// nav, registry titles) are resolved with `i18n.t(...)` at module-load time and
// don't react to a live `changeLanguage`. Reloading re-runs those at boot in the
// new language (read from localStorage by `init`). Deferred to the next macrotask
// so a pending React state flush (e.g. a just-saved form clearing its dirty
// state) completes first — otherwise a still-armed `beforeunload` dirty-guard
// would trigger the browser's "unsaved changes" prompt.
function reloadSoon(): void {
if (typeof window !== 'undefined') {
setTimeout(() => window.location.reload(), 0)
}
}
// Read the stored locale, tolerating restricted-storage contexts where
// `localStorage` access throws. Returns `null` when there is no stored choice
// so callers can distinguish "no choice yet" from an explicit value.
function storedLocale(): string | null {
return readStorage(ADMIN_LOCALE_STORAGE_KEY)
}
function readStoredLocale(): string {
return storedLocale() || 'en'
}
/**
* Reconcile the admin UI language against a store's `admin_locale`
* fallback (legacy `base_controller` parity), for an admin with no genuine
* personal choice. Encodes the precedence:
* account selected_locale > genuine stored choice > store admin_locale > 'en'
*
* No-op when a higher tier owns the language (an account locale, or a genuine
* stored choice — locale key set without an auto-marker). Otherwise drives the
* stored language to this store's current default:
* - a supported default → adopt it (auto-marked to this store);
* - a blank/cleared/unsupported default → revert to 'en' IF the prior value was
* auto-applied (a stale auto-default from this or another store is dropped);
* - already matching → nothing changes.
* Reloads (via the boot path) only when the displayed language actually changes.
*
* @param code the store's current `admin_locale`
* @param storeId the store being entered
* @param accountLocale the account's `selected_locale` (null when unset)
* @param supported locale codes the dashboard ships a bundle for
*/
export function reconcileStoreDefaultLocale(
code: string | null | undefined,
storeId: string,
accountLocale: string | null,
supported: string[],
): void {
if (accountLocale) return
const auto = readStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
const stored = storedLocale()
// A genuine choice (locale key set, no auto-marker) outranks any store default.
if (stored != null && auto == null) return
const target = code && supported.includes(code) ? code : null
const current = i18n.resolvedLanguage ?? i18n.language
if (target) {
writeStorage(ADMIN_LOCALE_STORAGE_KEY, target)
writeStorage(ADMIN_LOCALE_AUTO_STORE_KEY, storeId)
if (target !== current) reloadSoon()
} else if (auto != null) {
// Store has no usable default and the current language was auto-applied —
// drop it so the UI reverts to the app default ('en').
clearStorage(ADMIN_LOCALE_STORAGE_KEY)
clearStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
if (current !== 'en') reloadSoon()
}
}
// All non-English core bundles, imported EAGERLY so the active language has its
// resources synchronously available when init() runs below — no flash, no async
// race with module-load `i18n.t(...)` calls, and the stored language resolves
// to itself rather than falling back.
const coreLocales = import.meta.glob<{ default: Record<string, unknown> }>(
['../locales/*.json', '!../locales/en.json'],
{ eager: true },
)
/** Admin-UI locale codes the framework ships a bundle for (including `en`). */
export function coreLocaleCodes(): string[] {
return localeCodesFromBundlePaths(Object.keys(coreLocales))
}
/**
* Turns a panel's locale-bundle paths into the `{ code, name }` pairs its
* language pickers render, with `en` always first.
*
* The glob itself has to stay in the calling package — `import.meta.glob` is a
* compile-time transform resolved against the file that writes it, so hoisting
* it here would scan the framework's own locales instead of the panel's. What
* IS shared is everything after that: stripping the path down to a code, and
* naming each language in its own words.
*
* @param paths bundle paths from the caller's `import.meta.glob`, e.g.
* `./locales/de.json`
*/
export function localesFromBundlePaths(paths: string[]): Array<{ code: string; name: string }> {
return localeCodesFromBundlePaths(paths).map((code) => ({ code, name: localeEndonym(code) }))
}
// `en` first, then a code per bundle path. The glob hands back whatever prefix
// the calling file used (`./locales/`, `../locales/`), so match either.
function localeCodesFromBundlePaths(paths: string[]): string[] {
return ['en', ...paths.map((path) => path.replace(/^.*\/locales\//, '').replace('.json', ''))]
}
// The languages the running panel can display, as it declared them. `null`
// until a panel does, which accepts every code — the behaviour before panels
// declared anything.
let uiLocaleCodes: readonly string[] | null = null
/**
* Declares the languages this panel can display, so a saved preference for one
* it does not ship is never applied.
*
* The account's language is shared by every panel a person signs in to, and
* panels ship different sets: a language picked in one may not exist in the
* other. Applied anyway, the framework's own strings would switch while the
* panel's stayed in English. Call once at boot with the panel's own list.
*
* @param codes locale codes the panel ships a bundle for, e.g. `['en', 'de']`
*/
export function setUiLocales(codes: readonly string[]): void {
uiLocaleCodes = codes
}
/** @returns whether the running panel can display `code` */
export function isUiLocale(code: string): boolean {
return uiLocaleCodes === null || uiLocaleCodes.includes(code)
}
/**
* The language a new session should switch the page to, or `null` when the
* page is already right.
*
* The account's saved language wins when the panel can display it. When it
* cannot, the page keeps the language it booted in — unless that one is not
* displayable either, which a panel reached before this check existed can be
* left in, and then it goes back to English.
*
* @param saved the account's `selected_locale`
* @param stored the language the page booted in
*/
export function sessionLocale(saved: string | null | undefined, stored: string): string | null {
const target = saved && isUiLocale(saved) ? saved : isUiLocale(stored) ? stored : 'en'
return target === stored ? null : target
}
/**
* Record an explicit, genuine UI-language choice (top-bar switcher, profile,
* login, settings-save) WITHOUT reloading. Persists the locale and clears any
* store-default marker, so the choice now outranks every store default and
* won't be superseded on store switches. Use this when the UI already displays
* `code` (no reload needed) but the choice must still be marked as genuine.
*/
export function markGenuineLocaleChoice(code: string): void {
writeStorage(ADMIN_LOCALE_STORAGE_KEY, code)
clearStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
}
// Switch the admin UI language from an explicit, genuine choice. Marks it as
// genuine (see `markGenuineLocaleChoice`) and reloads (see `reloadSoon`) so
// every module-load label re-resolves in the new language.
export function switchLocale(code: string): void {
markGenuineLocaleChoice(code)
reloadSoon()
}
// Bootstrap i18next with the framework's base translation namespace. Side-effect
// import — `import '@spree/dashboard-core/lib/i18n'` from the consuming app's
// entry point runs this once before any component calls `useTranslation()`.
//
// The app (and any plugin) extends the base by calling
// `i18n.addResourceBundle('en', 'translation', extraKeys, true, true)`
// after this side-effect import has settled. The `deep` + `overwrite` flags
// merge the extension into the base namespace without dropping framework keys.
//
// `lng` is read from localStorage so a previously chosen language is the
// initial language on first paint (no flash).
i18n.use(initReactI18next).init({
// Every bundle is registered up front. Passing `lng` with only English
// loaded would resolve the language to the fallback and leave
// `resolvedLanguage` stuck on 'en' — which reads as "the stored language
// never took effect" and sends the store-default reconciler into a
// reload loop.
resources: {
en: { translation: en },
...Object.fromEntries(
Object.entries(coreLocales).map(([path, mod]) => [
path.replace('../locales/', '').replace('.json', ''),
{ translation: mod.default },
]),
),
},
lng: readStoredLocale(),
fallbackLng: 'en',
interpolation: { escapeValue: false },
// Surface missing keys in dev so we notice gaps as we build pages; ship
// silently humanizing the attribute in prod (a missing key shouldn't blow
// up the UI).
saveMissing: import.meta.env.DEV,
missingKeyHandler: import.meta.env.DEV
? (_lngs, _ns, key) => console.warn(`[i18n] Missing key: ${key}`)
: undefined,
})
// Reflect the active language on the root <html> element so the document
// advertises the right `lang` (a11y, spellcheck, font selection) and `dir`
// (RTL for Arabic/Hebrew/etc.). `i18n.dir()` consults i18next's built-in RTL
// language list. Runs at boot; `switchLocale` reloads the page, so the next
// boot re-applies it for the chosen language — no live listener needed.
function applyDocumentLanguage(code: string): void {
if (typeof document === 'undefined') return
const html = document.documentElement
html.setAttribute('lang', code)
html.setAttribute('dir', i18n.dir(code))
}
applyDocumentLanguage(i18n.language || readStoredLocale())
/** Document text direction for a locale (`ltr` or `rtl`). */
export function uiDirection(locale?: string): 'ltr' | 'rtl' {
return i18n.dir(locale ?? i18n.language) === 'rtl' ? 'rtl' : 'ltr'
}
/** Which edge the primary sidebar docks to for a locale. */
export function primarySidebarSide(locale?: string): 'left' | 'right' {
return uiDirection(locale) === 'rtl' ? 'right' : 'left'
}
export { default as i18n } from 'i18next'
export { Trans, useTranslation } from 'react-i18next'