# Feature: i18n (internationalization)

English and Amharic at launch with user locale preference persisted across sessions.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Surfaces

| Location | Control |
|----------|---------|
| `/login` | Language switcher beside role selector |
| Portal topbar / profile menu | Language switcher |
| All portal pages | Translated UI chrome |

Entered data (names, addresses, free text) stays as typed — not machine-translated.

## Locales

| Code | Language | Launch |
|------|----------|--------|
| `en` | English | ✓ |
| `am` | Amharic | ✓ |

Registry extensible for future locales (e.g. `om`, `ti`).

## Implementation (frontend)

Mirror Fortune Admin i18n pattern:

```
src/i18n/registry.ts      — locale metadata
src/i18n/LocaleContext.tsx — client provider
src/messages/en.json      — English strings
src/messages/am.json      — Amharic strings
```

Library: **next-intl** with App Router integration.

Adding a locale = registry row + messages file + optional font adjustments.

## User preference

| Field | Storage |
|-------|---------|
| `user.locale` | Shared backend user record |
| Cookie / localStorage | Client cache for next-intl |

### Endpoint

- `PATCH /v1/auth/me/locale` — see [`auth.md`](../backend/endpoints/auth.md)

### Request

```json
{ "locale": "am" }
```

### Session response includes

```json
{ "locale": "am" }
```

## Entity

- [`SessionUser.locale`](../backend/entities/session-user.md)

## Coverage requirements

All UI strings translated:

- Navigation labels
- Page titles and descriptions
- Buttons, form labels, placeholders
- Table headers and empty states
- Error and toast messages
- Demo role selector labels
- Date/number formatting per locale

## Validation

| Rule | Code |
|------|------|
| `locale` must be registered (`en`, `am`) | `VALIDATION_FAILED` |

## Default locale

- Org default: `organisation.locale_default`
- User override: `user.locale`
- Fallback chain: user → org → `en`

## Clinical withhold

N/A — i18n affects presentation only.

## UI component

Compact language switcher in topbar:

```
[ EN | አማ ]
```

Persist on change via `PATCH /v1/auth/me/locale` + client cookie update.

## Related

- [auth-roles.md](auth-roles.md) — login surface
- [org-departments.md](org-departments.md) — org default locale

## Backend note (shared API)

When production auth ships, `user.locale` must sync across B2B, Ecom, and Mob for consistent customer experience.