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

Quickstart: Platform Localization v1 (DE/EN)

Goal

Implement one deterministic locale foundation for the platform runtime, then translate the first-wave shell and governance surfaces without changing authorization or machine-readable artifact truth.

Targeted Validation Commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Localization/LocaleResolverTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/AuthAndSystemSurfaceLocalizationTest.php tests/Feature/Localization/LocalePreferenceFlowTest.php tests/Feature/Localization/WorkspaceDefaultLocaleTest.php tests/Feature/Filament/Localization/CoreGovernanceSurfaceLocalizationTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/LocalizedNotificationFormattingTest.php tests/Feature/Localization/TranslationFallbackGuardTest.php tests/Feature/Localization/MachineFormatInvarianceTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Smoke Focus

1. Open the admin login page and a representative system-panel page, then verify locale-specific auth and system copy using explicit override plus system default only.
2. Set workspace default locale to de on the existing workspace settings surface, verify an inheriting user sees German admin shell, tenant shell, and tenant dashboard copy, then clear the workspace default and verify inheritance falls back to the system default.
3. Set a personal locale preference to en and verify the shell, dashboards, and representative governance pages switch back to English.
4. Apply and clear the explicit temporary override and verify it wins only while active.
5. Open representative Findings, Baseline Compare, and representative workspace or tenant management tables, then confirm headings, actions, empty states, and glossary terms follow the resolved locale.
6. Open representative monitoring, alert, and operations surfaces and confirm labels, notifications, and relative-time text follow the resolved locale without changing workflow semantics.
7. Open a customer-safe review or report viewer and confirm the viewer shell localizes while underlying artifact content and identifiers stay unchanged.
8. Trigger a representative validation error and a representative notification and confirm they render in the resolved locale.
9. Verify wrong-plane or non-member requests still resolve as 404 and member-but-no-capability requests still resolve as 403 after locale changes or overrides.
10. Verify exported or audited machine-readable values stay stable and non-localized.

Reviewer Watchpoints

• One resolver owns locale precedence.
• The system panel is explicit-override plus system-default only in v1; it does not silently inherit workspace default or a second persisted preference model.
• Livewire requests preserve the already-resolved locale.
• Unsupported locale input falls back safely to English.
• Locale changes do not alter wrong-plane 404, non-member 404, member-but-no-capability 403, or global-search visibility.
• First-wave translation coverage stays bounded to the planned surface families.
• No raw translation keys appear on in-scope surfaces.
• Exports, audit entries, raw payloads, and IDs remain invariant.
• Locale resolution stays local to request, session, user, and workspace settings inputs with no extra remote lookups.