feat(dashboard): localize the tenant app with react-i18next (4/4)

[marcelo-maciel]

Carries two infrastructure fixes that are not this PR's topic. Without them CI cannot even reach this PR's code.

• Dependency bump: Microsoft.SourceLink.GitHub to 10.0.401 and Testcontainers to 4.14.0, clearing NU1902/NU1903 so restore succeeds. Those are the versions #1375 (SourceLink) and #1369 (Testcontainers) carry: this hunk is the union of the two, plus one comment per pin naming the advisory it answers.
• MinIO (b13fb9f8): minio/minio is gone from Docker Hub, so every Testcontainers-backed integration test dies on the image pull. Pulls from quay.io on a pinned tag instead. Same fix as #1388.

The MinIO hunk is byte-identical to #1388. The dependency hunk is not byte-identical to #1375 or #1369, which each carry half of it without the comments, but it is identical across all twelve PRs in this series: src/Directory.Packages.props resolves to the same blob (854deb95) at every head. Either way they merge in any order, and these copies can be dropped once the PRs that own them land.

Reopened from #1363. That PR was closed automatically on 2026-09-14, when the head fork
was deleted. It reopened at 23989b14, and review has added commits on top since then (the
commit list above is the current one). The earlier review history stays on #1363.

---

clients/dashboard slice of the i18n work, split out of #1344. 134 files, of which 32 are JSON catalogs. Same shape as the admin slice.

Mergeable before the backend slices, with two named dependencies (the earlier claim of full
independence was wrong, and review caught it):

• The language the user picks is persisted through PUT /identity/profile, and the locale field
  only exists once the framework slice (#1381)
  lands. Until then the switch still applies, and still survives a page reload through the client
  store, but the server drops the field.
• isTenantDeactivatedError keys off the ProblemDetails code, which the API only sends once
  #1382 lands. It now also matches
  the current English detail, so the terminal page is reached either way, and the text branch can be
  deleted the day that slice merges.

Slice	Files	PR
Framework	56	#1381 — the hard review
Module catalogs and wiring	229	#1382 — depends on the framework slice
clients/admin	111	#1383 — independent
clients/dashboard	134	this one

What is in here

• react-i18next wiring in src/i18n.ts. The chosen language is persisted to the user profile and sent to the API as Accept-Language through apiFetch; variants are canonicalised onto a supported tag before the call, so the API never sees a bare pt.
• en-US and pt-BR catalogs per feature namespace — catalog, chat, tickets, files, billing, identity, settings — held at strict key and placeholder parity in both directions by tests/i18n/parity.spec.ts.
• Language switcher in the topbar, and html[lang] follows the active language through a languageChanged listener, replacing the static lang="en" that nothing updated.
• Formatting stays in the presentation layer, the other half of the framework slice's UI-culture-only decision.
• Impersonation handoff adopts locale from the URL before createRoot, which fixes the shell language and Accept-Language in the same step. Harmless on its own: on main nothing sends the parameter until the admin slice lands, and this PR's handoff-locale.spec.ts passes with only this half present.
• The topbar stops hydrating the language from the profile once the user chooses one in-session. updateMyProfile is a read-modify-write with no concurrency token, and Settings › Profile invalidates the same ["identity","me"] key the topbar reads, so a save whose read preceded the language PUT could echo the old locale back and win — and the hydration effect would then switch the UI to it. A locale set on another device still carries over on a fresh mount.

Testing

Everything below is this slice on its own, at main plus these 134 files — not a share of the unsplit branch's totals.

• npm ci, npm run build (tsc -b + vite build), npx tsc -b tsconfig.tests.json and npm run lint: all exit 0.
• Playwright, full suite, one worker: 207 passed, 0 failed, 0 flaky, 0 skipped. That is 183 at the
  time of the split (the same count as on the unsplit branch, so nothing was lost in the cut) plus the
  24 the review follow-ups below added. That includes tests/impersonation/handoff-locale.spec.ts, which passes with only this half of the handoff present.

src/Directory.Packages.props

One backend file in a React PR, which needs explaining. template-smoke.yml triggers on paths: clients/** and runs dotnet build on the scaffolded solution, and .template.config/template.json does not exclude src/Tests/** — so a front-end-only PR still restores the full package graph and hits NU1903 / GHSA-q939-rpr3-3284 on SSH.NET 2025.1.0, pulled transitively by Testcontainers. That advisory fails restore on main too, re-verified today at 3f2959e6.

What that file carries is the Testcontainers and SourceLink bumps, byte-identical to #1378, so both stay mergeable in either order and this copy can be dropped once #1378 lands. The explicit SSH.NET pin it used to carry is gone: Testcontainers 4.14.0 already depends on the patched version. See the note at the end.

Notes

• The hydration guard has no regression test. Reproducing it needs an in-mount profile refetch driven through the Settings form, and the click races the language-change re-render (element detached from the DOM). Three distinct approaches, then stopped rather than paper over it. The underlying lost update on PUT /identity/profile is a contract change and is tracked in #1359, where the ponytail: comment in the topbar points.
• SignalR does not carry the app locale: the hub client builds its own requests instead of going through apiFetch, so Accept-Language on the negotiate is the browser's. Named explicitly in handoff-locale.spec.ts so any other channel that stops carrying the locale fails the test.

Docs (Golden Rule #10)

fullstackhero/docs#238, kept as a single PR covering all four slices — internationalization.mdx is one page whose sections map across the split. The Frontend (admin and dashboard) section is this slice and the admin one: catalogs, language detection and normalization, Accept-Language, the switcher and locale-aware formatting. That PR should merge after the last of the four, so the page never describes code that is not on main yet.

Review follow-ups

An independent review of this slice found one P1 and a handful of smaller things. All are fixed here:

• Choosing a language could end the session. The switcher fires a token refresh so the new
  locale claim is minted, and refreshAccessToken() cleared the token store on any non-ok
  response — so a refresh token that had been revoked, rotated in another tab or dropped by a
  reseed logged the user out for picking a language. Proved end to end before fixing it: a 401 on
  /identity/token/refresh landed the user on /login. Clearing the session now belongs to the
  callers that know the request needed auth (the 401 retry and the boot probe); the switcher reports
  the failure instead. The single-flight moved into refreshAccessToken() at the same time, so the
  switcher and the boot probe share the in-flight call rather than racing the server-side rotation.
• Catalog parity now covers interpolation, not just keys. A translation that drops or renames
  {{var}} renders the placeholder as literal text and no key is missing, so the old gate passed.
  Verified by mutation.
• The command palette searched in English only. Every action carried a hardcoded English keyword
  list, so a pt-BR user read every label in their language and still had to type "helpdesk" to find
  Chamados. The lists moved into the catalog, keyed by action id.
• A failed save was invisible. The language mutation had an onSuccess and no onError, so a
  rejected PUT /identity/profile left the UI switched with nothing on screen to say the choice was
  not stored — it reverts on the next fresh mount, which reads as the app forgetting on its own. It
  now raises a toast, covered by a spec.
• Two negative assertions could not fail. The impersonation switcher spec asserted "no PUT was
  sent" and "no refresh fired" immediately after the label flipped, which is before either request
  would have been issued. They now wait for the network to settle first.

---

Infra carve-outs, corrected after review. Two things in the out-of-topic hunks were wrong and
are fixed on the branch:

• The MinIO carve-out only moved minio/minio to quay.io. minio/mc is gone from Docker Hub too
  (hub.docker.com/v2/repositories/minio/mc/ answers 404) and it is what minio-init runs, so both
  dotnet run --project src/Host/FSH.Starter.AppHost and docker compose up died on the pull and the
  fsh bucket was never created. Now pinned to the same quay tag #1388 uses.
• The SSH.NET pin is gone: it pinned nothing. Its own comment claimed bumping Testcontainers
  does not help, but 4.14.0 — which this branch also carries — declares SSH.NET >= 2026.0.0.
  Measured rather than argued: with the pin removed, dotnet restore src/FSH.Starter.slnx --force
  reports zero NU1902/NU1903 and exits 0. (The MessagePack pin next to it stays; removing that one
  does bring its advisory straight back.)

With both applied, deploy/docker/docker-compose.yml and src/Directory.Packages.props are now
genuinely byte-identical to #1388 (git diff --exit-code, checked today), which the earlier claim
was not.

---

A real defect in the fallback this PR introduced. parseMissingKeyHandler took only the key
and returned its capitalized last segment. i18next calls that handler for a missing key whether
or not the call site passed a defaultValue, and the handler's return value is what renders, so
every t(key, { defaultValue }) in the app was being degraded to a truncation of its own key.
Measured against the installed i18next (26.3.6) before the fix:
t("perm.entry.Permissions.Users.Create", { defaultValue: "Create users" }) returned "Create",
and the handler's second argument arrives as the defaultValue (null when there is none, not
undefined). The two rules (a caller's fallback wins, otherwise degrade to the last segment)
moved to lib/i18n-fallback.ts, and tests/i18n/missing-key.spec.ts drives them through a real
i18next instance rather than re-implementing the contract. Reverting the guard turns it red.

And the same number formatting. {{count}} and the named count placeholders interpolated the
number raw, so a Portuguese UI read "1234" beside correctly grouped currency and dates. They go
through i18next's number formatter now, except the two that must not: the files dropzone
interpolates already formatted byte sizes, and the activity page pre-formats its own count.

Upload failures were still English prose built inside the hook and in module-scope XHR handlers
(cancel, transport failure, a rejected PUT, a blocked extension, an oversize file). They raise an
UploadError carrying a catalog key now, namespaced because the resolver runs with whatever t
the display site is bound to, and one exported resolver renders it at the three places that show
it.

A later round: the storage key and a gate for the upload errors.

The language detector kept i18next's default i18nextLng storage key. Every other value this app
persists is namespaced (fsh.dashboard.accessToken, fsh.dashboard.tenant,
fsh.dashboard.impersonation.*), and the bare key is claimed by both apps on a shared origin and
by any other i18next app deployed beside them. It is fsh.dashboard.lng now. The i18n page said the language was cached in localStorage and left the key implicit, which now reads as the library default; named there in fullstackhero/docs@0f4f1d97, on the same docs PR. The migration cost
is one session: a returning user's old value is not read, so the first paint after deploy falls to
the browser locale or the deployment default, and the profile hydrate then restores User.Locale.

The namespacing above had no test of its own, which is the half that matters here: every upload
surface in this app binds t to "files" while the messages live in "common", so a dropped prefix
resolves nothing and renders the last segment of the key.
tests/i18n/upload-errors.spec.ts drives the real avatar picker on /settings/profile under
?culture=pt-BR through a storage PUT that never connects, one the bucket rejects with a 403, and
a presign that never leaves the browser. The 403 case asserts the interpolated {{status}}, not
just that some catalog string rendered; dropping common: from upload.networkError turns the
first case red.

Writing it found one more English string on that path. describeUploadError returned e.message
for any plain Error, and apiFetch does not wrap fetch, so a presign that never reached the
API surfaced as the browser's own TypeError("Failed to fetch") ahead of the localized fallback
the caller had already passed in. That branch logs the original for diagnosis and returns the
catalog string now.

And the PhoneNumberConfirmed question from review is now pinned rather than answered. It does
not reproduce: UserProfileService compares the incoming phone to the stored one with a plain
string compare and only calls SetPhoneNumberAsync on a difference, and updateMyProfile re-reads
the profile and echoes phoneNumber back byte for byte, so a language switch never produces one.
What made that worth a test is that the safe version and the damaging version look identical:
"" and null are not interchangeable to that comparison, so adding a .trim() || null on this
path reads like tidying and would un-confirm a verified phone number for choosing a language, with
no error and no log. Three cases pin the echo now (null, "", a real number), and that exact
normalization is what turns the "" case red.

One timing change, flagged rather than buried. expect.timeout in playwright.config.ts is
10 s rather than the 5 s default, which aligns it with the action (10 s) and navigation (15 s)
budgets already in this config: every test ends in a toBeVisible, and under CPU contention the
first paint of a lazy route lands past 5 s while staying well inside the other two. It is a wait
budget, not a correctness threshold, and it is called out here so it can be vetoed rather than
discovered.

[marcelo-maciel]

Two follow-ups that belong to this PR rather than to the ones it sits next to:

The switcher persists a field main does not have. updateMyProfile({ locale }) depends on the locale column and the JWT claim introduced in #1381 and #1382. Merged out of order, the PUT silently drops the value. Worth a line in the PR body naming that dependency so the merge order is explicit.

Adaptation needed once #1387 lands. #1387 rewrites updateMyProfile to take the profile the form was seeded from plus its ETag ({ profile, expectedETag, firstName, lastName, phoneNumber }) and deletes getMyProfile in favour of getMyProfileWithETag. clients/dashboard/src/components/layout/topbar.tsx imports both and calls updateMyProfile({ locale: tag }), so whichever of the two merges second fails tsc -b in Frontend CI. Agreed order: #1387 first, this PR adapts — the switcher reads through getMyProfileWithETag and passes profile, expectedETag and locale. The ponytail: comment in that file already anticipates this and can be removed with the change, since the ETag is exactly the fix it points at (#1359).