feat(api): per-user UI locale preference and localized API ProblemDetails (spec 058, ADR 0111) #1180
Loading…
Reference in a new issue
No description provided.
Delete branch "feature/i18n-user-locale"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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).
user_accounts.locale TEXT NULL— no default, no FK, no CHECK; the{en, de, da}allowlist lives inUserPreferencesServiceso adding a locale later needs no migration.CurrentSessiongainslocale(populated inGET /api/sessionfor every authenticated principal, super_admin included); newPUT /api/session/preferences {locale}(authenticated-only, jakarta@Patternvalidation, null clears the preference, returns the refreshed session).MessageSourcebundlesmessages/api-messages(en base +_de+_da, UTF-8,fallbackToSystemLocale=false, configured viaspring.messages.*).ApiExceptionHandlerProblemDetail titles and the generic data-integrity detail resolve viaLocaleContextHolder(Accept-Language).ApiExceptionHandler, theStorageUnavailableException.forPurpose/forPath/notConfiguredfactory messages (now message keys + English log fallback), and the listing-timeout reason inStoragePathsAdminController(now a keyedStorageUnavailableException.listingTimeout()→ same 503 +code=STORAGE_UNAVAILABLE).code=STORAGE_UNAVAILABLE,candidate_changed,upload_session_not_cancellable,errors[]).localeonCurrentSession+ the new endpoint.Migration note
V162__user_account_locale.sqlis 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)
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@Patternwithout 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_UNAVAILABLEunchanged.FilesystemStorageBackendTestassertion updated to the new English fallback message.- 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