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

# Feature Specification: Customer-Facing Localization Adoption v1

**Feature Branch**: `275-customer-facing-localization-adoption`  
**Created**: 2026-05-04  
**Status**: Draft  
**Input**: User description: "Customer-Facing Localization Adoption v1 as a prep-only, implementation-ready productization slice over the already repo-real localization and customer-review foundations, focused on customer-facing adoption, glossary completion, and productized surface coverage without reopening the localization foundation or broadening into website, export, or full-product translation work."

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: TenantPilot already has repo-real locale resolution, customer-safe review surfaces, and EN/DE translation assets, but customer-facing governance consumption still depends on incomplete glossary coverage and inconsistent language across the current review workspace, released review detail, and governance-package or proof access states.
- **Today's failure**: Customer-safe readers in DACH or EU contexts can reach the right review truth, but they still have to infer meaning from mixed English and German wording, uneven surface coverage, and package or proof labels that feel foundation-ready rather than productized. That leaves the product claim ahead of the actual customer-facing experience.
- **User-visible improvement**: An entitled reader can use the existing locale controls and read the current customer-safe review flow in consistent English or German, with one approved glossary for review status, governance package access, proof access, next-step guidance, and related customer-safe helper text.
- **Smallest enterprise-capable version**: Reuse the existing locale foundation and current customer-safe review flow, then complete one bounded adoption pass over the customer review workspace, released review detail, governance-package or proof access states, and locale-related helper or notification copy needed to make that flow consistently customer-facing in EN and DE.
- **Explicit non-goals**: No new locale or plugin system, no website localization, no new panel or auth plane, no localized export review-pack contents, no JSON or audit artifact localization, no broad full-product translation rewrite, no new persistence or abstraction layer, and no reopening of the completed localization foundation or completed customer-review productization work.
- **Permanent complexity imported**: One bounded customer-facing glossary inventory for already-real surfaces, additional EN/DE catalog coverage for those in-scope keys, and focused regression coverage around customer-safe locale adoption. No new models, tables, state families, or platform-wide presentation framework are introduced.
- **Why now**: `docs/product/roadmap.md`, `docs/product/spec-candidates.md`, and `docs/product/implementation-ledger.md` all keep customer-facing localization as an open productization blocker, while the technical foundation and customer-safe review surfaces are already repo-real. The next value is adoption, not more localization infrastructure.
- **Why not local**: One-off copy fixes on a single page would leave package labels, proof access states, download actions, locale feedback, and released-review detail wording inconsistent. The smallest honest solution is one bounded cross-surface adoption pass over the existing customer-safe review flow.
- **Approval class**: Core Enterprise
- **Red flags triggered**: Foundation-sounding localization theme, multiple surfaces, and a shared glossary obligation. Defense: the slice stays on existing EN/DE locale support and existing customer-safe review surfaces, adds no new locale system, and explicitly forbids export or broad operator-UI localization.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Review Outcome

- **Outcome class**: acceptable-special-case
- **Workflow outcome**: keep
- **Test-governance outcome**: keep
- **Reason**: The package is a bounded productization pass over already-real localization and customer-review foundations. It keeps the current locale chain, current customer-safe review surfaces, and current artifact truth, while explicitly blocking website localization, export or audit localization, and any new locale framework.
- **Workflow result**: Ready for implementation.

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - existing admin-plane customer review workspace at `/admin/reviews/workspace`
  - existing tenant-scoped released review detail route at `/admin/t/{tenant}/reviews/{record}`
  - existing locale context and override endpoints reused by the current admin plane at `/localization/context` and `/localization/override`
  - existing authenticated user locale preference endpoint at `/users/me/locale-preference`
- **Data Ownership**: Existing `preferred_locale` user preference and existing workspace default locale setting remain the only persisted locale truth. Existing tenant-owned review, evidence, and review-pack records remain authoritative for customer-safe review content. Translation catalogs remain derived presentation assets only. No new persisted truth is introduced.
- **RBAC**:
  - this remains inside the existing admin plane and current tenant review access paths
  - workspace membership remains the first isolation boundary for the customer review workspace
  - tenant review visibility, review-pack access, and proof access keep the current capability and entitlement rules
  - locale preference updates remain bound to the authenticated user, and any existing workspace-default locale controls remain under the current workspace settings capability model
  - no new role family, customer identity plane, or widened download capability is introduced

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: The current tenant prefilter behavior of the customer review workspace remains unchanged. Language selection changes presentation only and MUST NOT reset or rewrite current tenant or workspace filter context.
- **Explicit entitlement checks preventing cross-tenant leakage**: Locale changes and localized copy MUST NOT reveal inaccessible tenants, reviews, review packs, or proof links. Non-members or out-of-scope tenant targets remain `404`, and member actors missing a capability keep the existing `403` behavior on gated download or proof actions.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: locale controls, status messaging, evidence or report viewers, governance-package access labels, proof-access labels, helper copy, and locale-related notifications
- **Systems touched**: current locale resolution and preference flow, existing `localization.review.*` catalogs, current customer review workspace page, current released review detail surface, and existing review-pack access or proof-access messaging
- **Existing pattern(s) to extend**: the locale foundation from Spec 252, the customer review productization contract from Spec 258, and the governance-package delivery wording introduced as related context in Spec 260
- **Shared contract / presenter / builder / renderer to reuse**: existing locale resolution and preference flow, existing `localization.review.*` keyspace, current `CustomerReviewWorkspace` page, current `TenantReview` detail surface, and the current governance-package download action on the released review detail
- **Why the existing shared path is sufficient or insufficient**: The resolver, preference flow, and customer-safe review surfaces already exist and are the correct reuse path. What remains insufficient is glossary completion and consistent customer-facing copy coverage across those already-real surfaces.
- **Allowed deviation and why**: none. This slice must not introduce page-local translation behavior, new locale sources, or a second customer-facing glossary.
- **Consistency impact**: Terms such as `review`, `customer review`, `governance package`, `current review pack`, `proof access`, `next step`, and customer-safe availability states must stay aligned across workspace list, released review detail, localized notifications, and helper copy.
- **Review focus**: Reviewers must block any new locale infrastructure, export-localization attempt, page-local synonym drift, or provider-specific wording entering the default customer-facing glossary.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

N/A - no `OperationRun` start, completion, dedupe, or deep-link semantics are changed by this slice.

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: platform-core
- **Seams affected**: customer-facing glossary terms, governance-package labels, proof-access labels, helper text, and availability-state wording
- **Neutral platform terms preserved or introduced**: customer review, governance package, current review pack, proof access, next step, review status, and customer-safe detail
- **Provider-specific semantics retained and why**: Any provider-specific report or artifact names may remain only in already-gated secondary evidence or artifact context where the underlying record is provider-owned. They are not promoted into the default customer-facing glossary.
- **Why this does not deepen provider coupling accidentally**: The slice reuses platform-owned localization keys and current customer-safe review vocabulary rather than translating raw provider payload labels into the default visible path.
- **Follow-up path**: none

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Customer Review Workspace page | yes | Native Filament page plus existing customer-review primitives | status messaging, action labels, localized glossary, package and proof availability | page, filter, disclosure | no | Existing page remains the primary customer-safe index; no new page type is introduced |
| Released Customer Review detail | yes | Native Filament resource detail plus existing review and artifact primitives | detail labels, helper text, governance-package access, proof-access states | detail, disclosure, access-state messaging | no | Existing detail remains the secondary context surface; no new report viewer or package registry is introduced |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | Primary Decision Surface | Reader decides which entitled tenant review to open and whether the current review appears ready for customer-safe follow-up | localized review state, governance-package availability, proof status, and next-step wording | released review detail, proof context, and gated artifact detail only after explicit open | Primary because it is the current customer-safe landing surface and should answer the first cross-tenant review question in the chosen language | Follows current review-consumption workflow instead of inventing a new localization dashboard | Removes manual interpretation of mixed-language labels before review drilldown |
| Released Customer Review detail | Secondary Context Surface | Reader validates why the review says what it says and whether the current governance package or proof can be opened or downloaded | localized narrative labels, current governance-package action, localized access-state reasons, and customer-safe helper text | deeper proof context, gated artifact detail, and any provider-owned secondary references only after explicit drilldown | Secondary because it deepens one selected review rather than replacing the workspace entry surface | Keeps customer-facing localization inside the existing review detail route | Prevents repeating the same summary in multiple languages across parallel detail widgets |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | customer-read-only, customer-admin, auditor-read-only, operator-MSP | localized customer-safe review state, governance-package availability, proof availability, and next-step summary | deeper lineage, freshness, and secondary governance detail only after opening the review | raw payloads, provider IDs, and unrestricted support detail stay hidden or gated | `Open review` | raw or support detail, deeper diagnostics, and any out-of-scope operator controls remain hidden | The workspace states one localized summary per tenant row; the detail view owns deeper explanation |
| Released Customer Review detail | customer-read-only, customer-admin, auditor-read-only, operator-MSP | localized section labels, governance-package action, localized package or proof availability reasons, and customer-safe helper text | release history, evidence freshness, and secondary context stay lower priority | raw evidence payloads, provider-debug detail, and unrestricted support detail remain hidden or gated | `Download governance package` | support-only or raw artifact context remains secondary and capability-gated | Detail adds explanation and access-state wording without duplicating the same overview cards as peer truth |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | List / Table / Read-only workspace report | Read-only registry report | Open the released review for one entitled tenant | dedicated `Open review` link column | forbidden | contextual `Back to governance inbox` and `Clear filters` remain neutral header actions only | none | `/admin/reviews/workspace` | `/admin/t/{tenant}/reviews/{record}` | workspace context, tenant filter, review state, governance-package availability | Customer review | localized review state, governance-package state, proof state, and next step | Existing inspect affordance stays a primary link column rather than row click |
| Released Customer Review detail | Detail / Report / Evidence | Read-only detail report | Download the current governance package or inspect localized proof-access status | detail header action plus in-body secondary proof context | forbidden | proof and supporting artifact links remain secondary in-body actions | no new destructive action enters customer-workspace mode; existing destructive manage actions stay out of scope | `/admin/reviews/workspace` | `/admin/t/{tenant}/reviews/{record}` | workspace, tenant, released-review context, package or proof state | Customer review | localized customer-safe labels and access-state explanations for the current released review | Existing customer-workspace mode keeps one dominant header action and no new action family |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | Customer-safe reader or MSP operator preparing customer consumption | Decide which entitled review to open in the chosen language | Read-only workspace review overview | Which current review matters for this tenant, and is the customer-safe package or proof ready? | localized review state, governance-package availability, proof status, and next-step guidance | deeper lineage, freshness, and supporting detail after drilldown only | review state, package availability, proof availability | none | Open review | none |
| Released Customer Review detail | Customer-safe reader or MSP operator continuing the same review | Understand the current governance record and whether the current package or proof can be safely consumed | Read-only detail report | What does this review say in my chosen language, and what customer-safe artifact can I use now? | localized section labels, helper text, governance-package action label, and localized access-state reasons | deeper proof context, release history, and gated secondary artifact detail | review state, package availability, proof-access state | none | Download governance package | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: The current locale foundation exists, but customer-facing review consumption still presents incomplete or inconsistent translated terminology across the already-real customer-safe review flow.
- **Existing structure is insufficient because**: The repo already has the right resolver and review surfaces, but those existing surfaces do not yet share one completed customer-facing glossary or one bounded surface inventory for locale adoption.
- **Narrowest correct implementation**: Keep the current locale foundation, keep the current review and package flow, and complete a bounded EN/DE glossary and copy pass only on the customer-facing review surfaces that already exist.
- **Ownership cost**: Ongoing maintenance of the in-scope glossary keys and focused regression coverage for those surfaces only.
- **Alternative intentionally rejected**: A full product-wide translation rewrite, localized export program, or second locale framework was rejected because the current release only needs customer-facing adoption on already-real review surfaces.
- **Release truth**: current-release productization blocker, not future-release preparation

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical reuse of the current locale foundation and customer-safe review flow is preferred over introducing any new compatibility layer.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: confidence, browser
- **Why this classification and these lanes are sufficient**: Focused feature coverage is the narrowest sufficient proof for locale preference or override reuse, localized customer-safe review surfaces, access-state wording, glossary consistency, and unchanged artifact truth. One bounded browser smoke remains justified because this slice is primarily about rendered customer-facing copy and dominant-action clarity on existing review surfaces.
- **New or expanded test families**: expand the existing localization feature family plus the current customer review workspace and tenant review UI contract tests; keep exactly one bounded browser smoke around the customer review workspace flow
- **Fixture / helper cost impact**: low to moderate. Reuse existing workspace membership, tenant entitlement, customer review workspace, released review, review-pack, and localization helpers instead of introducing a new heavy fixture family.
- **Heavy-family visibility / justification**: exactly one browser smoke stays explicit because this slice changes rendered customer-facing wording and access-state clarity, not backend workflow breadth.
- **Special surface test profile**: shared-detail-family
- **Standard-native relief or required special coverage**: ordinary Filament feature coverage is sufficient for route, entitlement, and localized label assertions. The bounded browser smoke is the only required rendered proof of customer-safe locale adoption.
- **Reviewer handoff**: Reviewers must confirm that localized copy appears only on in-scope customer-safe surfaces, no raw translation keys leak, no export or audit artifact content changes, tenant or workspace scope remains intact, and glossary terms stay aligned between workspace and detail surfaces.
- **Budget / baseline / trend impact**: low feature-local increase only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**:
  - `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`

## Scope Boundaries

### In Scope

- bounded customer-facing EN/DE glossary completion for the existing customer review workspace and released review detail
- localized governance-package, current review-pack, and proof-access labels, tooltips, helper text, and access-state reasons on those existing customer-safe surfaces
- locale-related helper or notification copy needed to switch into or remain in the chosen language on the in-scope flow
- explicit verification that customer-facing locale adoption changes surface chrome and messaging only, not underlying review-pack, JSON, audit, or other machine-readable artifacts
- consistent use of the approved customer-safe glossary across workspace list, released review detail, and current governance-package action labels

### Non-Goals

- any new locale resolver, plugin framework, or supported-locale expansion beyond the existing EN/DE foundation
- website localization or public documentation translation
- a broad operator-wide translation rewrite outside the existing customer-safe review and package surfaces
- localized export review-pack contents, JSON payloads, audit records, or other machine-readable artifacts
- a new panel, auth plane, customer portal, or new package domain
- reopening Spec 252 localization foundation work or re-normalizing completed Spec 258 artifacts

## Candidate Selection Rationale

- **Selected candidate**: Customer-Facing Localization Adoption v1
- **Source locations**:
  - `docs/product/spec-candidates.md` manual-promotion backlog priority 4
  - `docs/product/roadmap.md` customer-facing localization remains a `Next` and manual-promotion productization lane
  - `docs/product/implementation-ledger.md` explicit blocker: customer-facing localization adoption is incomplete
- **Why selected**: The active auto-prep queue is intentionally empty, this candidate remains unspecced, and it is the next repo-grounded customer-facing localization follow-through that builds directly on already-real foundations rather than requiring new infrastructure.
- **Why this is the smallest viable implementation slice**: The repo already has locale resolution, language catalogs, customer-safe review workspace, released review detail, and governance-package access messaging. The missing piece is one productized adoption pass over glossary completion and customer-safe surface coverage, not a new localization foundation.
- **Why close alternatives are deferred**:
  - `Enterprise Access Boundary & Support Access Governance v1` remains a separate access-governance lane with different trust and audit seams.
  - `Stored Reports Surface v1` remains a retained-artifact product surface lane and is not required to make the current customer-safe review flow readable in EN/DE.
  - `Workspace & Tenant Closure Lifecycle v1` remains a lifecycle-runtime lane and does not tighten the current customer-facing review or locale contract.
  - `First Governed AI Runtime Consumer v1` remains a governed-AI follow-through lane and is not a prerequisite for customer-safe locale adoption.

## Completed-Spec Guardrail Result

- **Spec 252 - Platform Localization v1**: completed context only. It already contains review outcome and implementation close-out evidence, so this spec reuses it as foundation context and does not reopen or normalize it.
- **Spec 258 - Customer Review Workspace Productization v1**: completed context only. It already contains implementation close-out evidence and remains the customer-safe review surface foundation for this adoption slice.
- **Spec 260 - Governance-as-a-Service Packaging v1**: related context only. It remains a terminology and package-surface anchor for current governance-package wording, but this spec does not refresh or broaden that package domain.

## Dependencies

- existing locale resolution and preference flow already present in the repo
- existing EN/DE `localization.review.*` catalogs and current review-related translation keys
- existing `CustomerReviewWorkspace` page and tenant review detail surface
- existing current governance-package download action and proof-access messaging on the released review detail
- existing customer-safe review RBAC, workspace or tenant isolation, and review-pack entitlement behavior

## Assumptions

- The supported locale set remains exactly English and German for this slice.
- Existing locale preference, override, and workspace-default behavior remain the canonical resolution path and are reused rather than redesigned.
- The current `Download governance package` action continues to resolve to the existing current export review pack and remains a customer-safe surface label only.
- Customer-facing localization in v1 applies to surface chrome, helper text, notifications, and access-state wording, not to the underlying downloadable artifact contents or audit payloads.
- Product copy review can approve the bounded customer-facing glossary without creating a new terminology-governance framework.

## Risks

- Glossary drift can reappear if workspace and released-review detail copy are translated independently.
- Partial German coverage can leave mixed-language surfaces if the bounded inventory is not enforced explicitly.
- Scope pressure can try to turn this adoption slice into a broad operator-wide rewrite or an export-localization program.
- Provider-owned artifact names could leak into default-visible customer-facing copy if the glossary is not kept platform-first.

## Follow-Up Candidates Explicitly Kept Out of Scope

- Enterprise Access Boundary & Support Access Governance v1
- Stored Reports Surface v1
- Workspace & Tenant Closure Lifecycle v1
- First Governed AI Runtime Consumer v1
- broad operator-wide localization beyond the current customer-safe review flow
- website localization and localized export, JSON, audit, or stored-artifact contents

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Read the customer review workspace in the chosen language (Priority: P1)

As an entitled customer-safe reader, I want the current customer review workspace to honor the existing locale choice so I can understand which tenant review to open without translating mixed-language labels myself.

**Why this priority**: This is the first customer-facing surface in the current governance consumption flow, and it is where the productization gap is most visible.

**Independent Test**: Set or inherit a supported locale, open the customer review workspace, and verify that the in-scope headings, accepted-risk accountability summary, package or proof states, next-step wording, and `Open review` action use the approved glossary with no raw translation keys.

**Acceptance Scenarios**:

1. **Given** an entitled reader resolves to German through the existing locale foundation, **When** they open the customer review workspace, **Then** the workspace heading, accepted-risk accountability summary, governance-package state, proof state, next-step wording, and `Open review` label render in approved German copy.
2. **Given** the same reader switches back to English using the existing locale controls, **When** they reopen the customer review workspace, **Then** the same in-scope terms, including accepted-risk accountability copy and any partial package or proof state, render in approved English copy and the current tenant or workspace filtering remains unchanged.

---

### User Story 2 - Consume released review detail with one consistent customer-safe glossary (Priority: P1)

As an entitled customer-safe reader, I want the released review detail to use the same approved customer-facing terminology as the workspace so I can trust the current governance package, accepted-risk status, and proof-access messaging.

**Why this priority**: The product claim fails if the workspace is localized but the released review detail falls back to inconsistent English, mixed synonyms, or unclear package or proof wording.

**Independent Test**: Open a released review from the customer review workspace in both supported locales and verify that the section labels, accepted-risk status, helper copy, governance-package action, and package or proof access-state reasons use the same glossary as the workspace.

**Acceptance Scenarios**:

1. **Given** a released review has a downloadable current governance package, **When** the reader opens the detail in German, **Then** the detail labels, accepted-risk status, and the dominant package action render in approved German while the underlying downloadable artifact remains unchanged.
2. **Given** a released review is missing, partial, blocked, or expired for package or proof access, **When** the reader opens the detail in either supported locale, **Then** the access-state reason appears in the selected language without changing the underlying authorization outcome.

---

### User Story 3 - Receive truthful localized access-state and locale-feedback messaging (Priority: P2)

As a reader or operator using the customer-safe review flow, I want locale-related helper or notification copy and customer-safe access-state messages to stay localized so the product does not fall back to raw keys or generic English during common follow-up steps.

**Why this priority**: Trust breaks quickly when the visible review surface is localized but common helper or access-state messages are not.

**Independent Test**: Trigger locale preference or override feedback and package or proof unavailable states on the in-scope customer-safe flow, then verify that the messages are localized while the same authorization and artifact rules still apply.

**Acceptance Scenarios**:

1. **Given** a reader clears or changes their current locale using the existing flow, **When** the action completes, **Then** the resulting helper or notification copy appears in the selected supported language.
2. **Given** a reader can view the released review but not download the current review pack, **When** they inspect the package action state, **Then** the reason is localized and the action remains correctly unavailable.

### Edge Cases

- What happens when a German translation is missing for an in-scope key? The surface MUST fall back to approved English copy and MUST NOT show a raw translation key.
- What happens when the reader can open the released review but not the current review pack or proof? The review remains readable, while the blocked or unavailable reason stays localized and truthful.
- What happens when the reader changes locale mid-flow? The next rendered customer-safe surface updates its localized copy while preserving the same tenant, workspace, and review context.
- What happens when the downloadable review pack or proof artifact is expired? The localized access-state wording changes, but the underlying artifact and machine-readable content remain unchanged.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST reuse the existing EN/DE locale foundation so the current customer review workspace and released review detail honor the reader's resolved locale without adding a new locale source or locale-management surface.
- **FR-002**: System MUST localize the in-scope customer-facing review surfaces with one approved glossary covering workspace headings, section labels, accepted-risk summaries or status, review status, governance-package wording, proof-access wording, next-step guidance, and related helper copy.
- **FR-003**: System MUST keep the same canonical customer-facing terms across the customer review workspace, released review detail, dominant package action, tooltips, helper text, empty states, and locale-related notifications for this slice.
- **FR-004**: System MUST provide localized and truthful package or proof availability messaging for the current customer-safe review flow, including partial or unavailable states, unavailable reasons such as missing or not-ready where applicable, plus blocked and expired states where they already exist in repo truth.
- **FR-005**: System MUST preserve the current workspace, tenant, and capability enforcement semantics on all in-scope localized surfaces, including existing `404` and `403` behavior.
- **FR-006**: System MUST keep exported review-pack files, raw JSON, audit records, identifiers, timestamps, and other machine-readable artifacts unchanged and unlocalized.
- **FR-007**: System MUST use existing locale-related helper or notification messaging for preference and override feedback rather than introducing a new panel, auth plane, or notification framework.
- **FR-008**: System MUST define and validate a bounded v1 surface inventory for customer-facing locale adoption and MUST leave broader operator-wide localization as follow-up work.
- **FR-009**: System MUST fail safely to approved English copy for missing in-scope translations and MUST NOT render raw translation keys on the default customer-safe path.
- **FR-010**: System MUST keep provider-specific artifact or report wording out of the default customer-facing glossary unless the existing underlying record is intentionally opened through a secondary, already-gated context.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace | `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` | `Back to governance inbox` when launched contextually, `Clear filters` | dedicated `Open review` link column | none | none | `Clear filters` only when filters are active | `N/A` | `N/A` | yes | Action-surface contract stays satisfied through one primary inspect affordance and one neutral filter-reset action; this slice only localizes copy and glossary use |
| Released Customer Review detail in customer-workspace mode | `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php` | `Download governance package` remains the dominant header action in customer-workspace mode | `N/A` | none | none | `N/A` | `Download governance package` | `N/A` | yes | Existing destructive manage actions stay outside the customer-workspace-mode scope for this localization slice; no new actions are introduced |

### Key Entities *(include if feature involves data)*

- **Locale Context**: The existing resolved locale and source used to render customer-safe review surfaces, derived from already-real user, workspace, session, and system settings.
- **Customer-Facing Review Glossary Inventory**: The approved EN/DE term set for current customer-safe review surfaces, including review status, governance-package wording, proof-access wording, and next-step guidance.
- **Customer-Safe Artifact Access State**: The existing derived package or proof state shown to a reader on the customer-safe review flow, expressed through localized customer-facing wording without creating a new state family.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In acceptance review, 100% of default-visible labels and helper text on the in-scope customer-facing review surfaces render approved English or German copy with zero raw translation keys.
- **SC-002**: An entitled reader can switch to or inherit either supported locale and identify the current review status, next step, and governance-package or proof availability for one tenant review in under 2 minutes.
- **SC-003**: In 100% of sampled acceptance flows, changing locale updates only in-scope surface chrome, helper copy, and feedback messaging while leaving exported review-pack contents, audit payloads, and other machine-readable artifacts unchanged.
- **SC-004**: Product review confirms that the approved customer-facing glossary stays consistent across the customer review workspace, released review detail, and current governance-package action in both supported locales.