--- path: /studio/internationalization-localization surface: studio domain: governance auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/internationalization-localization/page.tsx status: walked 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) --- # Studio · Internationalization and Localization ## 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 `` and renders `` followed by a single `panel` of quick-action links. - **Shell**: `ShellLayout` chrome with the Studio tab active - **Workspace heading**: `WorkspaceHeading` renders the page `

` "Studio Internationalization & Localization", followed by the `data-i18n-summary` paragraph - **Localization Coverage Lane**: an `

` `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` `Link`s — 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 - [x] **Loading** — `data-i18n-loading` ("Loading coverage analyzer…") - [x] **Unauthorized** — `data-i18n-unauthorized` ("Access restricted.") on 401/403 - [x] **Error** — `data-i18n-error` ("Could not load the coverage analyzer.") - [x] **Ready / form** — `data-i18n-enums` ("token syntax … · N metrics") plus the `data-i18n-form` analyze form - [x] **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`) - [x] **Analyze error** — `data-i18n-analyze-error` for invalid JSON or a non-200 response - [x] **Pending analyze** — `data-i18n-form-state="analyzing"`, native disabled submit, `aria-disabled="true"`, and `aria-busy="true"` until the POST resolves ## Interactions - [x] **Catalogs (JSON)** — `textarea` `data-i18n-payload`, `aria-label="i18n catalogs json"`, seeded with `{ baseLocale, baseMessages{ key: value }, locales[{ locale, messages{ key: value } }] }` - [x] **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 - [x] **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`](../../../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 - Parent: [`../studio-overview.md`](../studio-overview.md) - Sibling: [`studio-accessibility-governance.md`](./studio-accessibility-governance.md), [`studio-security-hardening-program.md`](./studio-security-hardening-program.md), [`studio-experimentation-feature-flags.md`](./studio-experimentation-feature-flags.md) - Component source: `apps/oshun/web/src/components/studio/StudioInternationalizationLocalizationWorkspace.tsx` - BFF store: `apps/oshun/bff/src/studio/` localization-coverage analyzer behind `/v1/admin/studio/i18n-coverage` ## Open questions / known gaps - [x] 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. - [x] 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.