1 ADR 0111 per user ui locale preference and localized api messages
Forgejo Actions edited this page 2026-10-12 23:17:11 +00:00

ADR 0111: Per-user UI locale preference and localized API messages

Status: accepted Date: 2026-10-12

Context

The web UI and the API surface a mix of hardcoded English, German and Danish strings. Households are multilingual (ADR 0034 already frames place-label language selection for that reason), so each user account needs a persistent UI language preference that the Paraglide-based frontend can consume, and the API's RFC7807 ProblemDetail responses need a message infrastructure so handler-level titles and generic details are not English-only. There is deliberately no email channel (ADR 0056), so no transactional-message localization concern exists. Revisit trigger: a household-level language policy (see ADR 0034) that would override or seed per-user choices.

Decision

Per-user UI locale: user_accounts gains a nullable TEXT column locale (V162; renumbered from V161 after main claimed V161 for domain singular display names). Allowed values are validated in the service layer against the allowlist {en, de, da} — en is the base/fallback locale, de and da are translations; NULL means 'not chosen', which the web client treats as browser-language detection (the backend never guesses from Accept-Language for the stored preference; no CHECK constraint on the column so adding a locale later needs no migration). Transport to the Paraglide frontend is a cookie set by the frontend from GET /api/session (CurrentSession gains a locale field) and PUT /api/session/preferences {locale} (authenticated-only, @Pattern-validated, null clears the preference). API ProblemDetail localization is separate from the per-user preference: ApiExceptionHandler resolves titles and generic detail patterns through a Spring ResourceBundleMessageSource (basename messages/api-messages, UTF-8, fallbackToSystemLocale=false) keyed off the request Accept-Language header, with messages/api-messages.properties (en, base), _de and _da bundles; the four German leak strings in ApiExceptionHandler/StorageUnavailableException/StoragePathsAdminController become message keys while machine-readable code properties (e.g. STORAGE_UNAVAILABLE) stay unchanged. There is no email subsystem (ADR 0056), so no transactional-email localization exists. Revisit trigger: household-level language policy (ADR 0034) that would override or seed per-user choices.

Consequences

  • user_accounts.locale is nullable TEXT with no default and no FK/CHECK: existing rows are untouched, NULL reads as 'not chosen', and future locales need no migration.
  • GET /api/session now carries locale (null when unset); the frontend owns cookie transport and browser-detection fallback, the backend stays out of Accept-Language guessing for the stored preference.
  • PUT /api/session/preferences is authenticated-only and validates against the {en, de, da} allowlist; an unknown locale is a 400, null clears the preference.
  • ProblemDetail titles and generic details are localizable per Accept-Language; the ~500 internal exception messages passed as detail stay in their original language for now (future spec tasks).
  • Machine-readable ProblemDetail properties (code, STORAGE_UNAVAILABLE, ...) are unchanged, so existing clients keep working.
  • No email channel exists (ADR 0056), so nothing else needs message catalogs.
  • Revisit: household-level language policy (ADR 0034) may supersede per-user-only selection.