12 — API Mapping (i18n Module)
- 1. Live endpoints
- 2. Planned endpoints (admin console)
- 3. Consumer API mapping (server-side translation)
- 4. Integration surface for the Flutter app
Exact endpoints, contracts and RBAC. Envelope conventions per 00-shared/07_API_Conventions.md; versioning
/api/v1URI (src/main.ts:44-46).
1. Live endpoints
GET /api/v1/i18n/messages
| Field | Detail |
|---|---|
| Auth | JWT (JwtAuthGuard, i18n.controller.ts:8) — Bearer token required |
| RBAC permission | none (guard only; no i18n.* perm exists in permissions.constants.ts — verified: all 97 perms, no i18n entries) |
| Query | locale?: string (optional; default = resolved locale) |
| Behavior | locale provided → CATALOGS[locale]; else resolved locale; unknown/missing → English DEFAULT_CATALOG (i18n.service.ts:47-49) |
| Response | flat Record<string,string> (key → localized template), e.g. { "app.welcome": "Welcome to StudyLyon", "leave.requested": "Leave requested for {days} day(s)." } |
| Source | src/modules/i18n/i18n.controller.ts:13-17 → I18nService.getMessages |
Locale resolution (server-side, all routes)
Accept-Language: hi-IN, hi;q=0.9 → first tag → strip region → lowercase →
whitelist check → ctx.locale (i18n.middleware.ts:13-18). Applied globally
(src/app/app.module.ts:139). Read via TenantContextService.getLocale()
(src/shared/tenant/tenant-context.service.ts:58-60).
2. Planned endpoints (admin console)
| Method | Path | Purpose | RBAC (planned) | Status |
|---|---|---|---|---|
| GET | /api/v1/i18n/keys | list keys + per-locale status (paginated, filter/search) | i18n.key.read | (planned) |
| POST | /api/v1/i18n/keys | create key + en source | i18n.key.create | (planned) |
| GET | /api/v1/i18n/keys/:key | one key, all locale values + params + version | i18n.key.read | (planned) |
| PUT | /api/v1/i18n/keys/:key | update values (params parity enforced) | i18n.key.update | (planned) |
| DELETE | /api/v1/i18n/keys/:key | delete key in all locales | i18n.key.delete | (planned) |
| POST | /api/v1/i18n/keys/bulk | bulk create/update (import CSV) | i18n.key.update | (planned) |
| GET | /api/v1/i18n/locales | list locales + coverage | i18n.locale.read | (planned) |
| POST | /api/v1/i18n/locales | add/promote locale | i18n.locale.manage | (planned) |
| GET | /api/v1/i18n/drift | missing-keys + param-drift report | i18n.locale.read | (planned) |
Gap: none of the
i18n.*permissions exist yet — they must be added tosrc/modules/rbac/permissions.constants.tsbefore any console endpoint ships (today: 97 perms,permissions.constants.ts:1-97).
3. Consumer API mapping (server-side translation)
| Consumer | Mechanism | Today | Source |
|---|---|---|---|
| Notifications | event → hardcoded EN title/body | EN-only; drift risk | notifications.handler.ts:16-31,41-49 |
| Announcement publish | AnnouncementPublished event payload title | tenant-authored content — not translated | announcement.service.ts:86-91 |
| Leave request | key leave.requested with {days} exists | no consumer wired yet | en.json:9 |
| Error responses | errors.* keys exist | HTTP filter not yet wired to translate() | en.json:3-8 |
| Planned | notifications + errors consume I18nService.translate() with event/user locale | — | IMPLEMENTATION_PLAN.md:171 |
Interpolation contract (consumers must pass): translate(key, { name: value })
→ {name} replaced; missing params left literal (i18n.service.ts:42-44).
4. Integration surface for the Flutter app
App fetches GET /i18n/messages?locale=<current> → flat map → ARB merge
(15_Flutter_Implementation_Guide.md §2). Keep locale list in sync with
SUPPORTED_LOCALES (i18n.service.ts:11-21): en, hi, ta, te, kn, ml, gu,
mr, bn.