TenantAtlas/specs/275-customer-facing-localization-adoption/quickstart.md

Quickstart — Customer-Facing Localization Adoption v1

Preconditions

• Docker is running and the Sail stack for apps/platform is available.
• The feature stays inside the existing Laravel monolith and current admin plane.
• Filament remains v5 on Livewire v4.
• Provider registration remains in apps/platform/bootstrap/providers.php; no provider or panel change is part of this work.
• No website localization, export or JSON or audit artifact localization, generic locale framework, global-search change, or asset-strategy change is in scope.
• The customer-facing flow must reuse the existing locale foundation, current customer review workspace, current released-review detail, current review-pack download, and current proof-routing seams.

Intended Implementation Order

1. Review the current localization seams in LocaleResolver, LocalizationController, and routes/web.php so the implementation reuses the repo-real locale chain and feedback endpoints.
2. Inventory the in-scope customer-facing glossary across CustomerReviewWorkspace, customer-review-workspace.blade.php, TenantReviewResource, and ViewTenantReview, then mark any missing or mixed EN and DE lines in lang/en/localization.php and lang/de/localization.php.
3. Tighten the customer review workspace intro, headings, accepted-risk accountability summary, table labels, empty states, and next-step copy so they all resolve from the approved glossary without changing tenant filters or row-action behavior.
4. Tighten the released-review detail in customer-workspace mode so section labels, accepted-risk status, package and proof helper text, availability reasons, and the dominant Download governance package action use the same glossary while the surface stays read-only.
5. Reuse existing review-pack and evidence truth for localized partial, blocked, unavailable, and expired reasons instead of adding a new state family or localization-specific presenter.
6. Keep all machine-readable artifacts unchanged: no localized review-pack contents, no localized raw JSON, and no localized audit payloads.
7. Add or expand the bounded feature test for customer-review surface localization and update the existing workspace or detail assertions needed for glossary alignment.
8. Reuse the existing browser smoke as the only browser proof for the slice.

Targeted Validation Commands (after implementation)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/LocalePreferenceFlowTest.php tests/Feature/Localization/LocalizedNotificationFormattingTest.php tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Planned Smoke Checklist (after implementation)

1. Sign in to /admin as an entitled customer-safe reader and open /admin/reviews/workspace.
2. Verify the workspace intro, disclosure copy, table labels, package and proof states, and Open review action render approved English or German copy with no raw translation keys.
3. Change locale through the existing override or personal preference path and confirm the same workspace keeps its current tenant filter and row set.
4. Open a released review through the existing workspace handoff and confirm the detail remains read-only in customer-workspace mode.
5. Verify Download governance package remains the one dominant header action and that blocked or unavailable reasons are localized without changing underlying entitlement behavior.
6. Follow an optional proof path and confirm the route remains capability-gated and secondary.
7. Confirm review-pack downloads, audit identifiers, and other machine-readable artifacts stay unchanged while the surrounding UI text is localized.

Notes

• This is a preparation-only artifact package. No application implementation or validation results belong in this planning output yet.
• Filament remains v5 on Livewire v4.
• Provider registration remains unchanged in apps/platform/bootstrap/providers.php.
• No new globally searchable resource or global-search behavior is planned.
• No destructive or mutating customer-workspace action is introduced.
• No website localization or localized export, JSON, or audit artifact contents belong in this slice.
• No new Filament assets are expected. If later implementation unexpectedly registers assets, deployment still uses cd apps/platform && php artisan filament:assets, but no such change is planned here.