TenantAtlas/specs/252-platform-localization-v1/research.md

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.