04 — Information Architecture (i18n Module)

1. Data model
2. Catalog contents today
3. Locale taxonomy
4. Resolution chain (server)
5. Admin console IA (planned)
6. Naming rules

How translation data is organized. Global IA per 00-shared/05; API envelope conventions per 00-shared/07.

1. Data model

Translation (logical entity; today a JSON entry, no DB):

Field	Type	Notes	Source
`key`	string	dotted namespace, e.g. `errors.resourceNotFound`	`en.json:3`
`locale`	string	primary BCP-47 tag	`i18n.service.ts:11-21`
`value`	string	localized template, may contain `{param}`	`en.json:9`

Physical storage: one file per locale under src/shared/i18n/translations/<locale>.json, compiled to the in-memory CATALOGS record (i18n.service.ts:6). Not a Mongo collection; not tenant-scoped (no tenantId).

2. Catalog contents today

Namespace	Keys	Example
`app.*`	`app.welcome`	"Welcome to StudyLyon" (`en.json:2`)
`errors.*`	`errors.resourceNotFound`, `errors.conflict`, `errors.validation`, `errors.unauthorized`, `errors.forbidden`, `errors.internal`	`en.json:3-8`
`leave.*`	`leave.requested` (`{days}` param)	`en.json:9`
`announcement.*`	`announcement.published`	`en.json:10`

9 keys total in each of en.json and hi.json (identical key sets today).

3. Locale taxonomy

Shipped (file exists): en, hi.
Declared (in SUPPORTED_LOCALES, no file yet; data-only addition per i18n.service.ts:9-10): ta, te, kn, ml, gu, mr, bn.
Fallback: en is the universal fallback (DEFAULT_CATALOG, i18n.service.ts:7).
All 9 are LTR. No RTL locale is planned; RTL support is (forward-looking).

4. Resolution chain (server)

Accept-Language → middleware whitelist → ctx.locale    (i18n.middleware.ts:16-17)
ctx.locale → CATALOGS lookup → 'en'                    (i18n.service.ts:27-30)
translate(): locale catalog → en catalog → literal key (i18n.service.ts:37-40)

5. Admin console IA (planned)

Translation Console (/admin/i18n)
├── Dashboard        — coverage %, missing per locale, drift alerts
├── Keys             — searchable key list, per-key status
├── Key Editor       — source (en) + per-locale fields (06 §2)
├── Locales          — manage supported locales, promote threshold (06 §3)
└── (settings)       — Crowdin sync, CI drift check (IMPLEMENTATION_PLAN.md:845)

6. Naming rules

Keys are dotted namespaces ordered <module>.<entity>.<state>.
Params are {snake_case}; a key's params must be identical across locales (enforced (planned) in editor + CI).
errors.* mirrors exception semantics — one key per error class, kept in sync with common/filters/http-exception.filter.ts.

Keyboard shortcuts