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
52 lines
5.1 KiB
Markdown
52 lines
5.1 KiB
Markdown
# Research: Platform Localization v1 (DE/EN)
|
|
|
|
## Decision 1: Keep v1 to exactly two locales
|
|
|
|
- **Decision**: Support exactly `en` and `de` in the initial slice.
|
|
- **Why**: The roadmap names DE/EN explicitly, the repo already defaults to English, and the main risk is establishing a trustworthy locale chain and translation ownership, not proving a broad language framework.
|
|
- **Rejected alternative**: A generic multi-locale system or plugin registry was rejected because it would import framework-level complexity before the first runtime locale foundation exists.
|
|
|
|
## Decision 2: Persist one user preference plus one workspace default
|
|
|
|
- **Decision**: Store the personal locale preference directly on the workspace-bound user-owned surface and store the workspace default locale through the existing workspace settings infrastructure.
|
|
- **Why**: The repo already has a strong workspace settings stack (`SettingsRegistry`, `SettingsResolver`, `SettingsWriter`) but no generic user settings registry. A direct workspace-bound user preference field is the narrowest truthful shape.
|
|
- **Rejected alternative**: A new generic preferences table or user-settings registry was rejected because the first release needs only one personal locale field.
|
|
|
|
## Decision 3: Resolve locale in one shared request-time seam
|
|
|
|
- **Decision**: Add one `LocaleResolver` and one request-time application path that can run for normal web requests and Livewire requests across admin, tenant, and system panels.
|
|
- **Why**: Repo evidence shows three active panel providers, shared topbar partials, and existing Livewire-specific middleware. Locale must stay coherent across those paths.
|
|
- **Rejected alternative**: Per-panel or per-page locale logic was rejected because it would drift immediately and would not solve mixed-language notifications or viewer shells.
|
|
|
|
## Decision 4: Keep system-panel locale scope narrower than admin or tenant scope
|
|
|
|
- **Decision**: Admin and tenant panels use the full precedence chain, but the system panel uses `explicit override -> system default` only in v1.
|
|
- **Why**: Repo truth shows the system panel authenticates `PlatformUser`, which is a separate actor model from workspace-bound `User`. Adding a second persisted preference store for platform actors would widen the slice beyond the narrow runtime localization foundation.
|
|
- **Rejected alternative**: A new platform-user locale preference or implicit inheritance from workspace default was rejected because the system plane is not workspace-owned and should not silently reuse workspace preference semantics.
|
|
|
|
## Decision 5: Reuse current shell and settings surfaces instead of inventing new UI
|
|
|
|
- **Decision**: Use the shared context bar or existing shell-adjacent controls for the user-facing locale switch, and use the existing workspace settings page for the workspace default locale.
|
|
- **Why**: The repo already has a shared render-hook surface in `resources/views/filament/partials/context-bar.blade.php` and an existing `WorkspaceSettings` page. That is the narrowest native Filament path.
|
|
- **Rejected alternative**: A dedicated localization page or a second profile/settings shell was rejected because it would duplicate shell-level context choice.
|
|
|
|
## Decision 6: Translate first-wave high-signal surfaces only
|
|
|
|
- **Decision**: First-wave translation coverage includes shell/auth, the current dashboards, Findings, Baseline Compare, representative workspace and tenant management tables, monitoring or operational feedback labels, and customer-safe review or report viewer chrome.
|
|
- **Why**: Repo evidence already shows translation-related usage on Findings and Baseline Compare, while the shared context bar, dashboards, and several relationship tables still contain many raw English strings. These surfaces represent the most visible operator and customer-safe workflows.
|
|
- **Rejected alternative**: Translating every current page in one slice was rejected because it would broaden scope faster than the locale foundation can be validated.
|
|
|
|
## Decision 7: Keep machine-readable artifacts invariant
|
|
|
|
- **Decision**: Locale affects UI copy, validation text, and date or relative-time formatting on in-scope surfaces, but not raw JSON, CSV, audit entries, IDs, or stored machine-readable report artifacts.
|
|
- **Why**: The roadmap requires stable export and audit semantics, and the product already uses customer-safe viewers and operational evidence where raw truth must remain stable.
|
|
- **Rejected alternative**: Localizing stored or exported artifacts was rejected because it would blur audit truth and increase downstream compatibility cost.
|
|
|
|
## Repo Evidence Snapshot
|
|
|
|
- `config/app.php` currently uses English as both default and fallback locale.
|
|
- The repo currently has only two explicit language catalogs: `lang/en/findings.php` and `lang/en/baseline-compare.php`.
|
|
- Translation helpers (`__()`) are already used across multiple Filament resources, notifications, and Blade views, but many shell and management strings remain raw English.
|
|
- The shared context bar partial is a concrete shell anchor and currently contains multiple hard-coded English labels.
|
|
- The repo has no current locale resolver, no workspace locale setting, and no personal locale preference field on `User`.
|