V1 Web PWA · Surface walkthrough

Studio · Internationalization and Localization

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
9sections3 minread
Markdown source
On this page

Context. surface studio · domain governance · route /studio/internationalization-localization · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/internationalization-localization/page.tsx

Last walked. 2026-06-25 i18n route-state addendum — Playwright real-dev-infra coverage now proves admin-scoped catalog load, flat quick-action footer anchors, real BFF default analyzer result rows, client malformed-JSON validation, real BFF 400 validation detail, pending-submit disabled state, catalog loading/error state, and non-admin unauthorized fail-closed state. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §103; spec: apps/oshun/web/e2e/studio-internationalization-localization.spec.ts. Previous: 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Analyze localization coverage with the real analyzer: the Localization Coverage Lane reports per-locale coverage, missing and extra keys, and ICU placeholder parity against the base catalog (mismatched {name} placeholders break runtime formatting). It is a live admin console wired to /v1/admin/studio/i18n-coverage, not an in-page simulation.

Entry points#

  • Direct URL / bookmark — /studio/internationalization-localization (signed-in + studio entitlement; admin scope required to analyze)
  • Sibling Studio routes — reached via the quick-action panel on accessibility-governance, security-hardening-program, performance-budgets, and other governance/operations pages

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioInternationalizationLocalizationWorkspace /> followed by a single panel of quick-action links.

  • Shell: ShellLayout chrome with the Studio tab active
  • Workspace heading: WorkspaceHeading renders the page <h1> "Studio Internationalization & Localization", followed by the data-i18n-summary paragraph
  • Localization Coverage Lane: an <h2> data-i18n-lane-heading ("Localization Coverage Lane") section with the load states and, when ready, the analyze form and result table
  • Quick-actions panel (data-i18n-footer): 5 sibling quickAction Links — API Gateway and BFF Composition, "Back to Accessibility Governance workspace", "Back to Performance Budgets workspace", "Back to Experimentation and Feature Flags workspace", and "Back to Observability and Operational Dashboards workspace". Each link exposes data-i18n-footer-link; no self-link and no Route Map panel.

States#

  • Loading — data-i18n-loading ("Loading coverage analyzer…")
  • Unauthorized — data-i18n-unauthorized ("Access restricted.") on 401/403
  • Error — data-i18n-error ("Could not load the coverage analyzer.")
  • Ready / form — data-i18n-enums ("token syntax … · N metrics") plus the data-i18n-form analyze form
  • Result — data-i18n-result headline (data-i18n-headline with data-i18n-fully-localized-count) and the data-i18n-locales table of data-i18n-locale-row rows (data-i18n-locale, data-i18n-translated, data-i18n-coverage, data-i18n-missing, data-i18n-extra, data-i18n-placeholder-mismatches)
  • Analyze error — data-i18n-analyze-error for invalid JSON or a non-200 response
  • Pending analyze — data-i18n-form-state="analyzing", native disabled submit, aria-disabled="true", and aria-busy="true" until the POST resolves

Interactions#

  • Catalogs (JSON) — textarea data-i18n-payload, aria-label="i18n catalogs json", seeded with { baseLocale, baseMessages{ key: value }, locales[{ locale, messages{ key: value } }] }
  • Analyze coverage — button data-i18n-submit (type="submit"); POSTs the parsed JSON to /v1/admin/studio/i18n-coverage/analyze, setting data-i18n-result on a 200 with a valid result, or data-i18n-analyze-error otherwise
  • Quick-action links — each quickAction Link navigates to its sibling Studio route (see Layout regions for the 5 targets)

E2E coverage#

  • apps/oshun/web/e2e/studio-internationalization-localization.spec.ts — admin-scoped direct route, real catalog ready state, flat quick-action footer targets, real BFF default analyzer result with all three locale rows, client-side malformed-JSON rejection with zero analyze POSTs, real BFF empty baseMessages 400 detail, pending disabled submit state, catalog-loading/error branch, and non-admin unauthorized fail-closed branch.

Data & contracts#

  • Reads: GET /v1/admin/studio/i18n-coverage on mount — returns the catalog (placeholderSyntax, metrics[])
  • Writes: POST /v1/admin/studio/i18n-coverage/analyze — returns { result: { baseKeyCount, locales[], summary{ localeCount, fullyLocalizedCount } } }
  • Realtime: none
  • Caching: client fetch with cache: 'no-store'; buildBffAuthHeaders() attaches the bearer token
  • Auth/role check: admin-scoped fail-closed — admin:* or admin:studio, 401/403 under the studio workspace gate

Cross-references#

Open questions / known gaps#

  • Confirm whether the page will gain a breadcrumb/Route Map panel like other Studio surfaces, or keep the flat quick-action panel — current page.tsx keeps a flat quick-action footer with no breadcrumb and no route-map panel as of 2026-06-25.
  • Document the live message catalogs the analyzer should pull once coverage checks run against the shipped locale bundles — V1 documents the canonical shared catalog in libs/oshun/i18n/src/index.ts (@oshun/i18n) plus the web next-intl message JSON under apps/oshun/web/src/i18n/messages/*. The current BFF route describes the analyzer and analyzes caller-supplied payloads; automatic shipped-bundle ingestion remains a product gap, not a browser interaction.