# Implementation Plan: Customer-Facing Localization Adoption v1 **Branch**: `275-customer-facing-localization-adoption` | **Date**: 2026-05-04 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md` **Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md` **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts. ## Summary Complete one bounded customer-facing localization adoption pass over the existing customer review flow. The narrow implementation path is to reuse the repo-real locale precedence and update endpoints in `LocaleResolver` and `LocalizationController`, keep the current customer review workspace and released-review detail as the only in-scope read surfaces, fill the remaining EN/DE glossary and helper-copy gaps in the existing `localization.review.*` catalogs, and preserve current review-pack, proof, entitlement, audit, and machine-artifact behavior unchanged. This is prep-only work over the foundations from Specs 252, 258, and 260. Filament remains v5 on Livewire v4, provider registration stays unchanged in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`, global-search behavior remains unchanged, no destructive action is introduced, and no new panel, website-localization lane, export/audit localization lane, or generic locale/plugin framework is planned. ## Technical Context **Language/Version**: PHP 8.4, Laravel 12 **Primary Dependencies**: Filament v5, Livewire v4, Laravel translator, existing `App\Services\Localization\LocaleResolver`, `App\Http\Controllers\LocalizationController`, current `localization.review.*` and locale feedback catalogs, `CustomerReviewWorkspace`, `TenantReviewResource`, `ViewTenantReview`, current review-pack and evidence resource paths, shared RBAC and audit helpers **Storage**: PostgreSQL via existing `users.preferred_locale`, existing workspace localization setting, existing `tenant_reviews`, `review_packs`, `evidence_snapshots`, memberships, and `audit_logs`; translation catalogs in `apps/platform/lang/en` and `apps/platform/lang/de`; no new persistence planned **Testing**: Pest v4 feature coverage plus one existing browser smoke on the current customer review flow **Validation Lanes**: confidence, browser **Target Platform**: Laravel monolith in `apps/platform`, existing admin plane (`/admin`) plus current tenant-scoped review detail reuse (`/admin/t/{tenant}/...`) **Project Type**: web application **Performance Goals**: keep locale adoption request-local and DB-only, avoid extra remote calls, reuse current eager-loaded review/pack/evidence relations, and leave review-pack artifact generation and download payloads unchanged **Constraints**: scope stays on existing EN/DE customer-facing review surfaces only; no new panel/provider/auth plane, no website localization, no export/JSON/audit artifact localization, no generic locale framework, no new global-search behavior, and no new destructive or mutating customer-workspace action **Scale/Scope**: one locale foundation reuse path, one customer review workspace page, one released-review detail route in customer-workspace mode, existing review-pack and proof availability messaging, two existing EN/DE catalogs, and focused reuse of the current localization, reviews, tenant-review, and browser test families ## Likely Affected Repo Surfaces - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Localization/LocaleResolver.php` for the existing locale precedence contract reused by the customer-facing review flow. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Http/Controllers/LocalizationController.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php` for the existing context, override, and personal preference endpoints that already format locale feedback. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` for localized row labels, empty-state copy, helper text, and glossary consistency on the canonical landing surface. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` for the current localized intro and disclosure copy rendered above the workspace table. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource.php` for localized detail labels, package and proof availability wording, and customer-workspace summary copy already composed from existing review truth. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php` for the read-only `customer_workspace` detail mode and the existing `Download governance package` dominant action. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource.php`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` as reuse-only supporting seams for invariant pack and payload behavior and explicit proof-access messaging. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php` as the canonical glossary assets to complete in place. - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/LocalePreferenceFlowTest.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/LocalizedNotificationFormattingTest.php`, planned `CustomerReviewSurfaceLocalizationTest.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` as the bounded proving path for locale adoption. ## Filament v5 / Panel Notes - **Livewire v4.0+ compliance**: The slice remains inside existing Filament v5 pages, resources, Blade views, and Livewire-backed request flows. No Livewire v3 behavior or compatibility work is introduced. - **Provider registration location**: No provider or panel registration change is planned. Existing provider registration remains in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`. - **Global search**: No new globally searchable resource or search behavior is introduced. Existing review-related search posture remains unchanged by this slice. - **Destructive actions**: No destructive action enters scope. The customer-facing review flow stays read-only, and existing destructive or manage actions remain out of scope in customer-workspace mode. - **Asset strategy**: No new Filament asset registration or loading strategy is planned. Deployment expectations remain unchanged; if future work ever registers assets elsewhere, the existing `cd apps/platform && php artisan filament:assets` deploy step still applies. ## Localization / Glossary Fit - Reuse the current `localization.review.*` keyspace as the single canonical customer-facing glossary rather than creating a second glossary file, terminology registry, or translation plugin framework. - Treat the current workspace intro and disclosure, workspace table labels, empty states, released-review detail labels, current governance-package action, package and proof availability reasons, next-step guidance, and locale-feedback notifications as the bounded v1 surface inventory. - Keep provider-specific artifact or report names secondary and already-gated. They may remain in deeper evidence or artifact contexts, but they must not become default customer-facing glossary terms. - Keep raw JSON, exported review-pack contents, audit action IDs and metadata, signed download semantics, identifiers, and timestamps invariant. Localization applies to chrome, helper copy, notifications, and access-state wording only. - Use English as the controlled fallback for missing in-scope German lines, and treat raw translation-key leakage on the customer-safe path as a blocker. ## RBAC / Isolation Fit - Workspace membership remains the first isolation boundary through the existing `WorkspaceContext` and `TenantReviewRegisterService::canAccessWorkspace(...)` path. - `/admin/reviews/workspace` remains the canonical workspace-scoped landing route; `/admin/t/{tenant}/reviews/{review}` remains the tenant-scoped secondary context route reached through the existing `customer_workspace=1` query flag. - Locale changes must not alter current denial behavior: non-members and out-of-scope tenant or review targets remain `404`, while in-scope actors missing record-level review access keep existing `403` behavior. - Optional supporting access remains capability-gated: current review-pack download keeps the existing `REVIEW_PACK_VIEW` path, and evidence proof reuse remains secondary and gated by the current evidence capability model. - No new customer identity plane, no widened download entitlement, and no new role family are introduced. ## Data & Invariance Fit - Existing `users.preferred_locale` and the existing workspace default-locale setting remain the only persisted locale truth. - Existing `TenantReview`, `ReviewPack`, and `EvidenceSnapshot` records remain the canonical source of review, package, and proof truth. - Translation catalogs remain derived presentation assets only; no new persisted glossary inventory, localization projection table, or review-localized artifact copy is created. - Existing audit rows remain stable machine truth. Locale adoption must not rename action IDs, mutate audit metadata keys or values, or localize stored audit payloads. - Existing signed review-pack download and evidence detail routes remain the only secondary artifact and proof seams reused by this slice. ## UI / Surface Guardrail Plan - **Guardrail scope**: changed surfaces - **Native vs custom classification summary**: mixed - **Shared-family relevance**: locale controls, status messaging, action labels, helper copy, evidence/report viewer chrome, governance-package access labels, and proof-access reasons - **State layers in scope**: page, detail, URL-query/session - **Audience modes in scope**: customer/read-only, customer-admin, auditor-read-only, operator-MSP - **Decision/diagnostic/raw hierarchy plan**: decision-first, diagnostics-second, support-raw-third - **Raw/support gating plan**: collapsed and capability-gated on reused detail and proof routes only - **One-primary-action / duplicate-truth control**: the workspace keeps `Open review` as the one dominant row action; released-review detail keeps `Download governance package` as the one dominant header action in customer-workspace mode; localization should not create parallel summary blocks - **Handling modes by drift class or surface**: review-mandatory - **Repository-signal treatment**: review-mandatory - **Special surface test profiles**: standard-native-filament, shared-detail-family - **Required tests or manual smoke**: functional-core, state-contract, bounded-browser-smoke - **Exception path and spread control**: none planned; any new locale framework, new customer shell, or localized export or audit artifact becomes exception-required drift - **Active feature PR close-out entry**: Smoke Coverage ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes - **Systems touched**: locale resolution and feedback endpoints, current review localization catalogs, `CustomerReviewWorkspace`, existing workspace Blade intro, `TenantReviewResource`, `ViewTenantReview`, current governance-package download label, proof-access reasons, and localized status and helper copy - **Shared abstractions reused**: `LocaleResolver`, `LocalizationController`, existing `localization.review.*` and locale notification and validation strings, existing customer-workspace query flag behavior, current review-pack and evidence truth presenters, and current review and detail RBAC paths - **New abstraction introduced? why?**: none planned - **Why the existing abstraction was sufficient or insufficient**: the locale foundation, update endpoints, review workspace, and released-review detail are already repo-real and are the correct shared path. What is insufficient today is glossary completion and consistent surface coverage on those existing seams. - **Bounded deviation / spread control**: none planned. If a future implementation claims the current keyspace or surfaces are insufficient, it must prove that a narrower in-place catalog or surface update cannot solve the current-release gap. ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: no - **Central contract reused**: `N/A` - **Delegated UX behaviors**: `N/A` - **Surface-owned behavior kept local**: localized copy only on existing read surfaces and locale feedback responses - **Queued DB-notification policy**: `N/A` - **Terminal notification path**: `N/A` - **Exception path**: none ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: yes - **Provider-owned seams**: raw provider report or artifact names in already-gated evidence or detail contexts only - **Platform-core seams**: `customer review`, `governance package`, `proof access`, `next step`, `review status`, `evidence`, and locale feedback wording - **Neutral platform terms / contracts preserved**: `customer review`, `governance package`, `current review pack`, `proof access`, `next step`, `accepted risk`, and `customer-safe detail` - **Retained provider-specific semantics and why**: provider-specific names may remain only when a deeper artifact or evidence surface already exposes them under existing entitlement. They do not become default-visible glossary terms. - **Bounded extraction or follow-up path**: none ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* - Inventory-first / snapshot truth: PASS. The slice localizes presentation over existing review, pack, and evidence truth only. - Read/write separation: PASS. The only writes are the already-existing locale override and user preference flows; customer-facing review surfaces remain read-only. - Graph contract path: PASS. No new Graph call or provider contract work is introduced. - Deterministic capabilities: PASS. Existing workspace, tenant, and capability seams remain authoritative. - Workspace and tenant isolation: PASS. Locale changes do not relax current `404` workspace or tenant boundaries. - RBAC-UX plane separation: PASS. Everything stays in the existing admin plane and current tenant-scoped review routes; no new auth plane is added. - Destructive confirmation standard: PASS by non-use. No destructive action enters scope. - Global search safety: PASS. No new searchable resource or search behavior is added. - OperationRun / Ops-UX: PASS by non-use. No run start, lifecycle, or notification semantics change. - Data minimization and machine invariance: PASS. Exported review-pack contents, raw JSON, audit payloads, IDs, and other machine artifacts remain unchanged. - Test governance (TEST-GOV-001): PASS. Proof stays in focused feature coverage plus the existing single browser smoke. - Proportionality / no premature abstraction: PASS. The narrow path is catalog completion and surface adoption on existing seams, not a new locale or glossary framework. - Persisted truth (PERSIST-001): PASS. No new table, projection, artifact family, or locale store is planned. - Behavioral state (STATE-001): PASS. Access and availability labels remain derived presentation over current review-pack and evidence truth; no new persisted state family is added. - UI semantics / shared pattern first / Filament-native UI: PASS. Existing Filament pages, resources, and the current localization keyspace remain the first reuse path. - Provider boundary (PROV-001): PASS. Default customer-facing vocabulary stays platform-owned and provider-neutral. - Filament / Laravel planning contract: PASS. Filament remains v5 on Livewire v4, provider registration remains in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`, no panel or provider change is planned, no global-search change is planned, and no new assets are expected. **Gate evaluation**: PASS. - The narrow implementation remains defensible if it reuses the current locale contract and current customer review flow instead of creating a second glossary or shell. - The gate fails if implementation drifts into website localization, export or audit localization, a new panel, provider, or auth plane, or a generic locale/plugin framework. **Post-design re-check**: PASS once `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/research.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/data-model.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/quickstart.md`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/contracts/customer-facing-localization-adoption.openapi.yaml` are present and the agent-context refresh step is executed. ## Test Governance Check - **Test purpose / classification by changed surface**: Feature for locale preference and override reuse, localized feedback, customer review workspace and detail copy, and glossary consistency; Browser for one existing end-to-end smoke of the customer review flow - **Affected validation lanes**: confidence, browser - **Why this lane mix is the narrowest sufficient proof**: the main risk is rendered customer-facing wording and existing access-state continuity on repo-real surfaces, not new backend workflow breadth or a new browser family - **Narrowest proving command(s)**: - `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` - **Fixture / helper / factory / seed / context cost risks**: low to moderate; reuse existing workspace membership, tenant entitlement, published review, current review-pack, and locale helpers instead of creating a new heavy fixture family - **Expensive defaults or shared helper growth introduced?**: no; any new helper should stay explicit and local to the localization or reviews family - **Heavy-family additions, promotions, or visibility changes**: none beyond the already-existing single browser smoke - **Surface-class relief / special coverage rule**: standard-native-filament relief on the workspace page and shared-detail-family coverage on the customer-workspace review detail - **Closing validation and reviewer handoff**: rerun the exact commands above, verify no raw translation keys appear on the in-scope surfaces, verify workspace and detail copy use the same glossary in EN and DE, verify locale changes do not alter current `404` or `403` behavior, and verify download, audit, and machine artifacts stay unlocalized - **Budget / baseline / trend follow-up**: none expected beyond contained feature-local assertions - **Review-stop questions**: lane fit, hidden fixture growth, glossary drift between workspace and detail, accidental machine-artifact localization, and scope creep into website or framework work - **Escalation path**: `document-in-feature` for contained glossary inventory notes; `reject-or-split` for any drift into new locale infrastructure or broader localization programs - **Active feature PR close-out entry**: Smoke Coverage - **Why no dedicated follow-up spec is needed**: this plan is already the bounded adoption follow-through on existing localization and customer-review foundations; broader operator-wide or website localization remains explicitly out of scope - **Test-governance outcome**: keep ## Review Checklist Status - **Review checklist artifact**: `checklists/requirements.md` - **Review outcome class**: `acceptable-special-case` - **Workflow outcome**: `keep` - **Test-governance outcome**: `keep` - **Escalation rule**: if implementation widens into website localization, export or audit localization, a new locale framework, or a new panel or auth plane, flip the workflow outcome to `split` or `reject-or-split` before continuing ## Rollout & Risk Controls - Keep the canonical entry surface on the existing customer review workspace and the canonical secondary surface on the existing released-review detail route. - Inventory the in-scope customer-facing glossary before code changes, then fill EN/DE catalog gaps in place so workspace and detail copy cannot drift independently. - Treat English fallback and raw-key avoidance as rollout blockers; a missing German string should render approved English, never the raw key. - Keep current signed review-pack download and evidence detail behavior unchanged. Localize only surrounding labels, tooltips, helper text, and blocked or unavailable reasons. - Preserve current tenant and workspace filters and customer-workspace launch context when locale changes mid-flow. - Keep browser validation bounded to the existing smoke harness before considering wider UI rollout or broader localization scope. ## Project Structure ### Documentation (this feature) ```text specs/275-customer-facing-localization-adoption/ ├── plan.md ├── research.md ├── data-model.md ├── quickstart.md ├── contracts/ │ └── customer-facing-localization-adoption.openapi.yaml └── tasks.md # Created later by /speckit.tasks, not by this plan step ``` ### Source Code (repository root) ```text apps/platform/ ├── app/ │ ├── Filament/ │ │ ├── Pages/Reviews/ │ │ │ └── CustomerReviewWorkspace.php │ │ └── Resources/ │ │ ├── TenantReviewResource.php │ │ └── TenantReviewResource/Pages/ViewTenantReview.php │ ├── Http/ │ │ └── Controllers/ │ │ ├── LocalizationController.php │ │ └── ReviewPackDownloadController.php │ ├── Services/ │ │ └── Localization/ │ │ └── LocaleResolver.php │ └── Support/ │ ├── Audit/ │ └── Auth/ ├── lang/ │ ├── en/localization.php │ └── de/localization.php ├── resources/views/filament/pages/reviews/customer-review-workspace.blade.php ├── routes/web.php └── tests/ ├── Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php ├── Feature/Localization/ ├── Feature/Reviews/ └── Feature/TenantReview/ ``` **Structure Decision**: Laravel monolith. The future implementation stays inside the existing `apps/platform` localization, customer-review, review-pack, and proof surfaces, with no new panel or provider location and no new persistence layer. ## Complexity Tracking | Violation | Why Needed | Simpler Alternative Rejected Because | |-----------|------------|-------------------------------------| | None expected at planning time | The plan reuses existing locale, review, and catalog seams instead of introducing new structural machinery | A new glossary framework, locale plugin system, or customer-facing mirror surface would add ownership cost without a new source-of-truth need | ## Proportionality Review - **Current operator problem**: the repo already resolves locale and exposes customer-safe review surfaces, but the customer-facing review flow still contains mixed or incomplete EN or DE wording and uneven glossary coverage across workspace, detail, and access-state messaging. - **Existing structure is insufficient because**: the current locale foundation and customer-review productization seams exist, but they do not yet guarantee one completed customer-facing glossary and one bounded surface inventory for language adoption. - **Narrowest correct implementation**: reuse `LocaleResolver`, `LocalizationController`, current `localization.review.*` catalogs, current workspace and detail surfaces, and focused localization and review tests to complete the customer-facing EN or DE adoption pass in place. - **Ownership cost created**: ongoing maintenance of a bounded EN or DE customer-facing glossary and a small set of feature and browser assertions for those existing surfaces. - **Alternative intentionally rejected**: a generic locale or plugin framework, website localization program, export or audit artifact localization pass, or second customer-facing shell was rejected because the current release needs adoption on already-real surfaces, not new infrastructure. - **Release truth**: current-release follow-through on existing localization and customer-review foundations ## Phase 0 — Research (output: `research.md`) See: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/research.md` Goals: - Confirm the current locale resolution and feedback seams that must be reused rather than replaced. - Confirm the bounded customer-facing surface inventory and glossary scope for v1. - Confirm machine-artifact and audit invariance boundaries. - Confirm the narrowest proving lane that extends current localization and review tests without opening a broader browser or framework scope. ## Phase 1 — Design & Contracts (output: `data-model.md`, `quickstart.md`, `contracts/`) See: - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/data-model.md` - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/quickstart.md` - `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/contracts/customer-facing-localization-adoption.openapi.yaml` Design outputs capture: - the existing locale, review, pack, proof, and glossary truth reused by the slice - the derived localized workspace and detail view models and invariance rules - the conceptual contract for locale endpoints and reused customer-review surfaces - the exact validation commands and smoke focus that should remain canonical for this plan package ## Proposed Implementation Phases 1. **Glossary Inventory & Catalog Gap Audit**: enumerate the current in-scope customer-facing keys across workspace, detail, package and proof reasons, and locale feedback; mark any missing or mixed EN and DE lines without widening scope. 2. **Workspace Localization Adoption**: align the customer review workspace intro, headings, table labels, empty states, and next-step copy with the approved glossary while preserving current tenant filter and row-action behavior. 3. **Released-Review Detail Localization Adoption**: align `ViewTenantReview` customer-workspace mode, detail labels, dominant governance-package action label, helper text, and package and proof availability reasons with the same glossary while keeping the surface read-only. 4. **Regression Proof & Rollout Guardrails**: add or expand the bounded feature test for customer-review surface localization, update the existing workspace and detail assertions as needed, and keep the existing browser smoke as the only browser proof for the slice.