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 class | Example | Mechanism |
|---|---|---|
| UI strings (web) | buttons, labels, errors | next-intl message catalogs |
| UI strings (app) | RN screens | i18next + react-i18next |
| CMS content | blog, pages, testimonials, FAQ | Payload localization (per-field locales) |
| Commerce data | product titles/descriptions, categories | Medusa + 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_LOCALEcookie (English when unset), andapps/storefront/proxy.tsrewrites each request toapp/[locale]/…, so each language's copy of a page is cached separately (apps/storefront/lib/routing.ts). Search engines therefore index English only, and nohreflangtags 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
translationsmap 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)
i18nextnamespaced 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.