feat(api): per-user UI locale preference and localized API ProblemDetails (spec 058, ADR 0111) #1180

Merged
chris merged 5 commits from feature/i18n-user-locale into main 2026-10-13 01:17:01 +02:00
Owner

Summary

Backend foundation for per-user UI language (spec 058, ADR 0111). Locales: en (base/fallback), de, da; NULL = not chosen → the web client falls back to browser-language detection (the backend never guesses from Accept-Language for the stored preference).

  • Migration V162 user_accounts.locale TEXT NULL — no default, no FK, no CHECK; the {en, de, da} allowlist lives in UserPreferencesService so adding a locale later needs no migration.
  • API: CurrentSession gains locale (populated in GET /api/session for every authenticated principal, super_admin included); new PUT /api/session/preferences {locale} (authenticated-only, jakarta @Pattern validation, null clears the preference, returns the refreshed session).
  • Message infra: Spring MessageSource bundles messages/api-messages (en base + _de + _da, UTF-8, fallbackToSystemLocale=false, configured via spring.messages.*). ApiExceptionHandler ProblemDetail titles and the generic data-integrity detail resolve via LocaleContextHolder (Accept-Language).
  • German leak strings removed (4): the storage-unavailable title in ApiExceptionHandler, the StorageUnavailableException.forPurpose/forPath/notConfigured factory messages (now message keys + English log fallback), and the listing-timeout reason in StoragePathsAdminController (now a keyed StorageUnavailableException.listingTimeout() → same 503 + code=STORAGE_UNAVAILABLE).
  • Machine-readable properties unchanged (code=STORAGE_UNAVAILABLE, candidate_changed, upload_session_not_cancellable, errors[]).
  • OpenAPI contract updated: locale on CurrentSession + the new endpoint.
  • Governance: ADR 0111 (accepted), spec 058 with scope/non-goals sections, backend tasks (done) + frontend extraction waves (pending), plan.json.

Migration note

V162__user_account_locale.sql is additive (ALTER TABLE ... ADD COLUMN locale TEXT), nullable, no rewrite of existing rows — safe to apply on the next deploy; Flyway picks it up automatically. No backfill: NULL is a meaningful value ("not chosen").

Not in this PR (deliberate)

  • Frontend Paraglide lane (cookie transport, language switcher, string extraction waves) — tracked as spec 058 tasks S058T007–T009, separate worktrees/PRs.
  • Localization of the ~500 internal exception detail messages — future task S058T010; only handler-level titles/generic patterns + the known leaks ship here.
  • Email localization (no email subsystem exists, ADR 0056); worker texts; household-level language policy (revisit via ADR 0034).
  • KNOWN_ISSUES [ISSUE-146] records the pending frontend extraction.

Test evidence

rtk ./gradlew :apps:api:test → BUILD SUCCESSFUL, 1946 tests, 0 failures, 0 errors, 9 skipped (Testcontainers-gated).
rtk ./gradlew :apps:api:build → BUILD SUCCESSFUL.

New/extended tests:

  • UserAccountLocaleMigrationTest — V162 content pins (nullable TEXT, no default/constraint).
  • UserPreferencesServiceTest (H2) — set en/de/da, null clears, unknown locale rejected pre-write, case-sensitive allowlist, disabled accounts untouched.
  • SessionPreferencesControllerTest (MockMvc standalone) — PUT contract: persists + returns refreshed session, null clears, fr → 400 from @Pattern without touching the service, missing field clears.
  • ApiExceptionHandlerTest — localized titles per Accept-Language (de leak string now a bundle entry), en fallback for unknown locales, localized data-integrity detail, code=STORAGE_UNAVAILABLE unchanged.
  • FilesystemStorageBackendTest assertion updated to the new English fallback message.
## Summary Backend foundation for per-user UI language (spec 058, ADR 0111). Locales: **en** (base/fallback), **de**, **da**; NULL = not chosen → the web client falls back to browser-language detection (the backend never guesses from Accept-Language for the *stored* preference). - **Migration V162** `user_accounts.locale TEXT NULL` — no default, no FK, no CHECK; the `{en, de, da}` allowlist lives in `UserPreferencesService` so adding a locale later needs no migration. - **API**: `CurrentSession` gains `locale` (populated in `GET /api/session` for every authenticated principal, super_admin included); new `PUT /api/session/preferences {locale}` (authenticated-only, jakarta `@Pattern` validation, null clears the preference, returns the refreshed session). - **Message infra**: Spring `MessageSource` bundles `messages/api-messages` (en base + `_de` + `_da`, UTF-8, `fallbackToSystemLocale=false`, configured via `spring.messages.*`). `ApiExceptionHandler` ProblemDetail titles and the generic data-integrity detail resolve via `LocaleContextHolder` (Accept-Language). - **German leak strings removed** (4): the storage-unavailable title in `ApiExceptionHandler`, the `StorageUnavailableException.forPurpose/forPath/notConfigured` factory messages (now message keys + English log fallback), and the listing-timeout reason in `StoragePathsAdminController` (now a keyed `StorageUnavailableException.listingTimeout()` → same 503 + `code=STORAGE_UNAVAILABLE`). - **Machine-readable properties unchanged** (`code=STORAGE_UNAVAILABLE`, `candidate_changed`, `upload_session_not_cancellable`, `errors[]`). - OpenAPI contract updated: `locale` on `CurrentSession` + the new endpoint. - Governance: ADR 0111 (accepted), spec 058 with scope/non-goals sections, backend tasks (done) + frontend extraction waves (pending), plan.json. ## Migration note `V162__user_account_locale.sql` is additive (`ALTER TABLE ... ADD COLUMN locale TEXT`), nullable, no rewrite of existing rows — safe to apply on the next deploy; Flyway picks it up automatically. No backfill: NULL is a meaningful value ("not chosen"). ## Not in this PR (deliberate) - Frontend Paraglide lane (cookie transport, language switcher, string extraction waves) — tracked as spec 058 tasks S058T007–T009, separate worktrees/PRs. - Localization of the ~500 internal exception detail messages — future task S058T010; only handler-level titles/generic patterns + the known leaks ship here. - Email localization (no email subsystem exists, ADR 0056); worker texts; household-level language policy (revisit via ADR 0034). - KNOWN_ISSUES [ISSUE-146] records the pending frontend extraction. ## Test evidence `rtk ./gradlew :apps:api:test` → **BUILD SUCCESSFUL, 1946 tests, 0 failures, 0 errors, 9 skipped** (Testcontainers-gated). `rtk ./gradlew :apps:api:build` → **BUILD SUCCESSFUL**. New/extended tests: - `UserAccountLocaleMigrationTest` — V162 content pins (nullable TEXT, no default/constraint). - `UserPreferencesServiceTest` (H2) — set en/de/da, null clears, unknown locale rejected pre-write, case-sensitive allowlist, disabled accounts untouched. - `SessionPreferencesControllerTest` (MockMvc standalone) — PUT contract: persists + returns refreshed session, null clears, `fr` → 400 from `@Pattern` without touching the service, missing field clears. - `ApiExceptionHandlerTest` — localized titles per Accept-Language (de leak string now a bundle entry), en fallback for unknown locales, localized data-integrity detail, `code=STORAGE_UNAVAILABLE` unchanged. - `FilesystemStorageBackendTest` assertion updated to the new English fallback message.
feat(api): per-user UI locale preference and localized API ProblemDetails (spec 058, ADR 0111)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m47s
768e678aaa
- V161: user_accounts.locale TEXT NULL (no default/FK/constraint; allowlist
  {en, de, da} enforced in UserPreferencesService so future locales need no
  migration; NULL = not chosen -> client-side browser detection)
- CurrentSession gains locale (populated in GET /api/session for all
  principals incl. super_admin); PUT /api/session/preferences accepts
  {locale} with jakarta @Pattern validation, null clears, returns the
  refreshed session
- Spring MessageSource bundles messages/api-messages (en base + de + da,
  UTF-8, fallbackToSystemLocale=false); ApiExceptionHandler titles and
  generic details resolve via LocaleContextHolder (Accept-Language)
- German leak strings replaced by message keys (ApiExceptionHandler
  storage title, StorageUnavailableException factories, StoragePathsAdmin
  listing timeout); machine-readable code properties unchanged
- OpenAPI contract: locale on CurrentSession + PUT /api/session/preferences
- KNOWN_ISSUES: ISSUE-142 (frontend string extraction pending waves)
- Governance: ADR 0111, spec 058 with sections/tasks/plan
# Conflicts:
#	KNOWN_ISSUES.md
fix(api): renumber locale migration to V162 after merging main (V161 taken by domain singular display names)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m45s
a4de139960
- V161__user_account_locale.sql -> V162__user_account_locale.sql
- migration content test, ADR 0111, spec 058 sections/tasks/plan updated
- KNOWN_ISSUES: entry renumbered to ISSUE-142 -> ISSUE-144 (142/143 claimed on main)
Merge remote-tracking branch 'origin/main' into feature/i18n-user-locale
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m39s
0061d00872
# Conflicts:
#	KNOWN_ISSUES.md
docs(api): fix stale V161 reference in UserPreferencesService comment
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m37s
859b60b2b8
chris merged commit 64afd12099 into main 2026-10-13 01:17:01 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1180
No description provided.