Skip to main content

Internationalization (i18n) Strategy

Requirement (notes #3): the entire website and app are multilingual. India-first means English + major vernaculars (Hindi, Tamil, Telugu, Marathi, Bengali, …), configurable per tenant.

Scope — four content classes, three mechanisms​

Content classExampleMechanism
UI strings (web)buttons, labels, errorsnext-intl message catalogs
UI strings (app)RN screensi18next + react-i18next
CMS contentblog, pages, testimonials, FAQPayload localization (per-field locales)
Commerce dataproduct titles/descriptions, categoriesMedusa + translation layer (see below)

Locale resolution​

  • Supported + default locales come from the Tenant Config Contract (SUPPORTED_LOCALES, DEFAULT_LOCALE).
  • User preference persisted on profile (and device for apps).
  • URL strategy for web (as built): one URL per page in every language. The choice lives in the NEXT_LOCALE cookie (English when unset), and apps/storefront/proxy.ts rewrites each request to app/[locale]/…, so each language's copy of a page is cached separately (apps/storefront/lib/routing.ts). Search engines therefore index English only, and no hreflang tags are emitted yet. Public /hi/… URLs would now be a change to the proxy alone, since the pages already live under [locale].

Commerce (Medusa) translations​

Medusa's core is not deeply multilingual per field, so:

  • Approach: a translation sidecar — translatable product/category fields stored as a translations map keyed by locale, resolved at the BFF when assembling storefront payloads.
  • Falls back to default locale when a translation is missing.
  • Editable in the admin alongside the product.

CMS (Payload) localization​

  • Payload localization is enabled per collection/field; editors switch locale in the admin and provide per-locale rich text/media.
  • The storefront requests content in the active locale; Payload returns localized fields with fallback.

Apps (React Native)​

  • i18next namespaced catalogs bundled + remotely updatable.
  • RTL-readiness in the design system (future-proofing).
  • Number/date/currency via Intl.

SEO implications (web)​

  • Localized URLs + hreflang + localized meta/OG tags.
  • Localized sitemaps per locale.
  • Server-rendered localized content (no client-only translation) so crawlers see translated pages. See Storefront module.

Operational notes​

  • Translation source of truth: catalogs in repo (UI), Payload (content), translation sidecar (commerce).
  • Missing-translation policy: fall back to default locale, never show keys.
  • Adding a locale: add to tenant config, provide UI catalogs, translate CMS + product fields; no code change.
  • Pseudo-localization check in CI to catch hard-coded strings.

Rule for contributors​

  • No hard-coded user-facing strings. Everything goes through the relevant catalog/localization layer — this is also enforced as a lint/CI check.