ahmido
7613e339c4
Some checks failed
Main Confidence / confidence (push) Failing after 56s
## Summary - add the localization v1 foundation with request-time locale resolution and workspace or user preference handling - localize the first-wave platform surfaces for auth, shell, dashboards, findings, baseline compare, and review workspace chrome - add Pest coverage for locale resolution, preference flows, fallback behavior, notifications, and governance surface localization ## Scope - active spec: specs/252-platform-localization-v1 - target branch: dev ## Notes - machine-readable artifacts remain invariant and are not localized in this slice - the branch includes the related spec kit artifacts for the feature Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #293
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# Data Model: Platform Localization v1 (DE/EN)
|
|
|
|
## Supported Locale Set
|
|
|
|
| Value | Meaning | Notes |
|
|
|---|---|---|
|
|
| `en` | English | System default and controlled fallback in v1 |
|
|
| `de` | German | First additional supported locale |
|
|
|
|
## Locale Sources
|
|
|
|
| Source | Ownership | Persistence | Allowed Values | Notes |
|
|
|---|---|---|---|---|
|
|
| `tenantpilot.locale_override` | request or session scoped | transient | `en`, `de` | Explicit temporary choice for the current browsing context |
|
|
| `users.preferred_locale` | user-owned | persisted on `users` | `en`, `de`, `null` | Personal preference; `null` means inherit |
|
|
| `localization.default_locale` | workspace-owned | existing workspace settings infrastructure | `en`, `de`, `null` | Workspace default for users without a personal preference |
|
|
| `config('app.locale')` | system-owned | config | `en` initially | Final fallback anchor |
|
|
|
|
## Precedence Rule
|
|
|
|
1. Explicit override
|
|
2. User preference
|
|
3. Workspace default
|
|
4. System default
|
|
|
|
If the chosen source is missing, malformed, or unsupported, resolution falls back to the next valid source until a supported locale is found. The final controlled fallback is English.
|
|
|
|
## Plane-Specific Resolution
|
|
|
|
- **Admin and tenant panels**: use the full precedence rule above.
|
|
- **System panel**: uses `explicit override -> system default` only in v1 because system actors authenticate as `PlatformUser` and do not get a persisted locale preference or workspace-default inheritance in this slice.
|
|
|
|
## Derived Resolved Locale Context
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `locale` | string | Effective locale for the current request (`en` or `de`) |
|
|
| `source` | string | One of `explicit_override`, `user_preference`, `workspace_default`, `system_default` |
|
|
| `fallback_locale` | string | Controlled fallback locale, `en` in v1 |
|
|
| `workspace_default_locale` | string or null | Current workspace default when a workspace context exists |
|
|
| `user_preference_locale` | string or null | Persisted personal locale preference for workspace-bound users; `null` on the system plane |
|
|
|
|
## Persistence Shape
|
|
|
|
- **User preference**: add one nullable locale preference field to the current workspace-bound user-owned surface.
|
|
- **Workspace default**: add one workspace setting definition under a localization-specific domain using the existing settings infrastructure.
|
|
- **No new table**: the first slice does not create a generic preferences or translation state table, and it does not add a second locale-preference store for `PlatformUser`.
|
|
|
|
## Translation Catalog Ownership
|
|
|
|
| Catalog Family | Ownership | Notes |
|
|
|---|---|---|
|
|
| `lang/en/*.php` | canonical English source | Existing `findings.php` and `baseline-compare.php` remain authoritative English catalogs |
|
|
| `lang/de/*.php` | German translation mirror | Added only for the selected first-wave surface families |
|
|
| generic shell or settings catalogs | platform runtime | Used for shell/auth/context-bar and shared operator text that does not belong to one domain file |
|
|
|
|
## Invariance Boundaries
|
|
|
|
The following stay non-localized in v1:
|
|
|
|
- raw JSON and provider payloads
|
|
- audit entries and machine-readable audit values
|
|
- stored report payloads and exported artifact data
|
|
- identifiers, slugs, route parameters, and query semantics
|
|
- global-search scope, authorization outcomes, and tenant/workspace context selection
|