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

Research — Customer-Facing Localization Adoption v1

Date: 2026-05-04
Spec: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md

Decision 1 — Reuse the current locale precedence and update endpoints

• Decision: Reuse App\Services\Localization\LocaleResolver, App\Http\Controllers\LocalizationController, and the existing /localization/context, /localization/override, and /users/me/locale-preference routes as the only locale-resolution and feedback path for this slice.
• Rationale: Repo truth already resolves explicit override -> user preference -> workspace default -> system default, and existing tests already cover preference updates, override behavior, and localized feedback formatting.
• Alternatives considered: A page-local locale switch or a second localization service was rejected because it would duplicate the repo-real precedence chain and drift immediately from the established foundation.

Decision 2 — Keep the v1 surface inventory bounded to the existing customer review flow

• Decision: Limit customer-facing localization adoption to /admin/reviews/workspace, customer-review-workspace.blade.php, the existing customer-workspace mode of ViewTenantReview, current governance-package and proof-access helper text, and locale-feedback messaging that supports this flow.
• Rationale: These are the current customer-safe governance surfaces already present in the repo, while the user and spec explicitly exclude website localization, broad operator-wide translation, and localized artifact contents.
• Alternatives considered: A wider operator-wide or website-localization pass was rejected because it broadens scope beyond the current productization blocker.

Decision 3 — Use the existing localization.review.* keyspace as the canonical glossary home

• Decision: Fill and normalize the customer-facing glossary in place under the current localization.review.* keys, with supporting reuse of existing locale notification and validation keys.
• Rationale: The current EN and DE catalogs already contain substantial customer-review vocabulary, including customer_safe_review_workspace, download_governance_package, package and proof availability labels, and blocked or expired state wording.
• Alternatives considered: A new glossary registry, a second translation domain, or a generic terminology framework was rejected because the repo already has the right catalog boundary for this flow.

Decision 4 — Preserve the current read-only customer-workspace drilldown seam

• Decision: Keep CustomerReviewWorkspace as the canonical landing surface and ViewTenantReview with customer_workspace=1 as the only secondary context surface.
• Rationale: The current detail page already suppresses lifecycle actions in customer-workspace mode, and current tests already assert the single dominant Download governance package action on that surface.
• Alternatives considered: A new customer-only detail page or customer portal shell was rejected because it would duplicate review truth, routing, and policy or audit behavior.

Decision 5 — Reuse current review-pack and evidence truth for localized access-state wording

• Decision: Localize labels and reasons around current package and proof availability without changing ReviewPack, EvidenceSnapshot, signed download semantics, or current audit behavior.
• Rationale: TenantReviewResource already computes localized governance-package availability states, and ViewTenantReview already exposes the localized Download governance package dominant action. The gap is glossary consistency and coverage, not missing artifact truth.
• Alternatives considered: Localizing review-pack contents, introducing a second package state family, or creating a new proof viewer was rejected because those would exceed the bounded presentation-only scope.

Decision 6 — Keep machine-readable artifacts invariant

• Decision: Exported review-pack contents, raw JSON, audit action IDs and metadata, identifiers, timestamps, and other machine-readable payloads remain untranslated.
• Rationale: Existing localization coverage already guards machine-value invariance in audit tests, and the spec explicitly forbids export, JSON, and audit localization.
• Alternatives considered: Localized artifacts or localized audit payloads were rejected because they would blur product truth and introduce compatibility risk without current-release need.

Decision 7 — Preserve current RBAC and isolation semantics during locale changes

• Decision: Locale adoption changes presentation only; existing workspace and tenant membership checks, capability gates, 404 and 403 behavior, and optional proof or download gating remain unchanged.
• Rationale: The workspace already uses TenantReviewRegisterService to constrain visible tenants, and the detail route already scopes review access to the current tenant and record.
• Alternatives considered: Customer-specific roles, locale-specific authorization branches, or widened artifact access were rejected because they are outside the scope of localization adoption.

Decision 8 — Keep global search, provider registration, and asset strategy unchanged

• Decision: Do not change global-search behavior, provider registration, panel topology, or Filament asset strategy.
• Rationale: This is a copy and glossary adoption pass on existing surfaces. The repo already keeps provider registration in apps/platform/bootstrap/providers.php, and the spec explicitly says global search and asset strategy stay unchanged unless proven otherwise.
• Alternatives considered: Search expansion, provider changes, or new asset bundles were rejected because they are unrelated to the current productization need.

Decision 9 — Prove adoption with focused feature tests plus the existing browser smoke

• Decision: Add one bounded customer-review surface localization feature test and reuse the current locale preference, localized feedback, workspace page, tenant review UI contract, and customer review workspace smoke tests as the proving lane.
• Rationale: The repo already has the localization and review test foundations needed to prove glossary continuity and rendered copy behavior, while the current browser smoke already covers the handoff path that matters most.
• Alternatives considered: A broader browser suite or full-product localization regression lane was rejected because it would add governance cost without better proof for this bounded slice.