Skip to content

feat: choose the language an instrument opens in - #1936

Open
thomasbeaudry wants to merge 9 commits into
mainfrom
feat/administer-language
Open

thomasbeaudry wants to merge 9 commits into
mainfrom
feat/administer-language

Conversation

@thomasbeaudry

@thomasbeaudry thomasbeaudry commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

A clinician can now choose which language an instrument opens in, at the moment they pick it, and a
remote assignment can be left for the subject's own browser to decide. Before this, both opened in
whatever language the clinician's own interface happened to be in, and a patient who read neither
had no way to change it.

Changes

  • Administering an instrument: each showcase card carries a language dropdown, defaulting to the
    interface language, and opens the instrument in the language chosen. A card for an instrument
    with one language shows no dropdown.
  • Assigning an instrument remotely: the confirmation dialog offers one option per language the
    instrument supports, plus "The subject's browser language", which is the default. Choosing a
    language pins it onto the link as ?lang=; leaving the default creates a link with no language.
  • The gateway now negotiates the language of a link that carries none from the subject's
    Accept-Language, server-side, so the first paint is already in their language instead of
    swapping after hydration. A link naming an active language still wins over the header.
  • A ?lang= naming a language the instance does not have active falls through to the header and
    then to the first active language, rather than silently rendering the first active one.
  • The gateway's HTML declares Vary: Accept-Language.
  • The assignment email form starts in the language its link opens in, and asks for confirmation
    before sending when the email's language and the link's language differ — but only when a template
    authored in the link's language exists, since otherwise the sender has nothing to resolve.
  • Only the languages an instance has active are ever offered, so a language an administrator turned
    off cannot be chosen.
  • The e2e suite pins locale: 'en-US'; a test about browser negotiation opts into its own locale.

Decisions

  • The remote-assignment default is no language at all, not the clinician's. An assignment is
    created before anyone knows what the subject reads, so the clinician's interface language is a
    guess, and a wrong guess is pinned into the link for good. Defaulting to unset lets the subject's
    own browser decide and keeps the clinician's explicit choice meaningful. The cost is that the
    stored url for most assignments carries no language, so nothing in the record says which
    language the subject will see.
  • In-person administration defaults to the interface language instead, because the clinician is
    sitting with the subject and is the one reading the screen. The two pages differ deliberately.
  • A language is written onto the link only at creation. An email later written in another
    language does not rewrite the link, since the link may already have been copied, QR-coded or sent.
    The mismatch is surfaced as a confirmation instead.
  • Editions and versions are deliberately not selectable. An earlier draft offered the
    instrument's edition here; picking a stale edition by accident is a data-quality problem with no
    obvious ceiling, so the API's existing behaviour — newest edition unless allEditions is asked
    for — stands untouched.
  • Vary: Accept-Language rather than Cache-Control: no-store. The pages stay cacheable; a
    shared cache simply has to key on the header the body now depends on.

Risks

  • An assignment link created before this change carries no lang, so it now opens in the language
    the subject's browser asks for rather than the instance's first active language. That is the
    intended behaviour for such links, but it is a visible change for links already in the wild.
  • InteractiveContent now requires language and onChangeLanguage. It is not exported from
    packages/react-core's barrel and both call sites already pass them, so nothing outside this repo
    can be broken by it.
  • A reverse proxy or CDN in front of the gateway that ignores Vary could serve one subject the
    language of another. Nothing in this repo's Caddy config caches gateway HTML, so the exposure is
    to an operator's own infrastructure.

Notes

The gateway negotiation was checked against a real browser locale rather than a crafted header: a fr-CA context receives French in the server's first
response body, not after hydration, and a link naming en still arrives in English from that same
context.

The language a subject actually sees is still not recorded on InstrumentRecord; the record keeps
only the instrument and the data. Worth doing, and out of scope here.

Adversarial review

Reviewed at commit 3509c78. pnpm check: green.

Findings

  1. apps/web/src/components/AssignmentEmailForm/AssignmentEmailForm.tsx:216 — the language-mismatch dialog can be impossible to satisfy: when the link's language is not among the email language options, every send raises a warning the sender cannot resolve, only override — ask only when the sender could have chosen the link's language, by intersecting it with languageOptions.
  2. testing/playwright.config.ts:28 — the comment explaining why locale is pinned is attached to fullyParallel, not to the locale it describes — move it above the chromium project entry that carries locale: 'en-US'.
  3. apps/web/src/routes/_app/session/tests/remote-assignment.test.tsx:238 — the comment says this waitFor settles the form's submit cycle; it settles nothing, and the submit cycle it names is never entered, because both tests are validation failures that return before setIsSubmitting(true) — restore the plain assertion and drop the comment.
  4. packages/react-core/src/components/InteractiveContent/InteractiveContent.tsx:273 — the "host holds no language" half of the new prop union, and the two ?? fallbacks it exists for, are reachable only from this component's own tests — make language and onChangeLanguage required, delete the union and the fallbacks, and drop the test for the absent variant.
  5. apps/web/src/routes/_app/session/remote-assignment.tsx:146 — open={isCreateModalOpen && choice !== null} adds a condition that can never be false while the dialog is open — restore open={isCreateModalOpen} and keep the inner {choice && …} guard.
  6. apps/gateway/src/lib/setup-state.ts:21 — the documented rule for an unreadable q does not match the code, and an RFC-legal uppercase Q= is silently read as the strongest preference, so fr;Q=0.1,en;Q=0.9 returns the least-wanted language — match the parameter case-insensitively and treat a matched-but-unreadable quality as 1, keeping q=0 as the only drop.
  7. testing/src/specs/accessible-instruments.spec.ts:10 — openAdministerWithSession re-implements an existing spec helper and bypasses the getPageModel fixture for no stated reason — take getPageModel and reuse the existing shape.
  8. apps/gateway/src/routers/root.router.ts:58 — the new Vary: Accept-Language does not deliver the property its test claims, because the same response is heuristically cacheable and carries the per-assignment bearer token — set Cache-Control: no-store alongside Vary and assert it.
  9. apps/web/src/components/AssignmentEmailForm/ConfirmEmailLanguageDialog.tsx:45 — emailLanguage ?? linkLanguage is a fallback for a state in which the text is not shown, and it makes the sentence name one language twice if it ever is — give the dialog a non-nullable emailLanguage and render it only while confirming.

Fixed

    1. The link's language is confirmed only when it is among the languages the selected template offers, with a test for the case that offers none.
    1. The comment moved beside the chromium project's use, where the pinned locale is.
    1. Both are plain expect calls again; only the submitting helper keeps its explicit wait.
    1. Both props are required, the union and the ?? fallbacks are gone, the story holds a language, and the tests render through one helper that supplies the host's pair.
    1. open={isCreateModalOpen}, with the inner guard left as the only narrowing.
    1. The quality parameter matches either case, and an unreadable one is the documented default of 1; tests cover q=. and Q=.
    1. The helper takes getPageModel, so it authenticates and navigates the way the suite documents.
    1. The dialog takes a non-nullable emailLanguage and is rendered only while confirming.

Declined

    1. Vary is what the test claims it is: RFC 9111 §4.1 forbids a cache from reusing a stored response unless the selecting header fields match, so a language-wrong hit is impossible with the header and possible without it. The absence of Cache-Control is unchanged from the base commit rather than introduced here, and the token-bearing page is served from a per-assignment URL, so a shared-cache hit requires already holding that subject's link. Tightening the gateway's cache directives is worth doing on its own terms, not as part of this change.

Attestation

I, Claude Opus 5, attest that the review block above reports the adversarial review as it ran on the
commit named, with every finding it returned.

🤖 Generated with Claude Code

@github-actions github-actions Bot added the Status: Needs Rebase Automated: conflicts with main; the author rebases label Nov 20, 2026
thomasbeaudry and others added 9 commits November 20, 2026 12:34
Each card on Administer Instrument carries a Language dropdown where the
instrument offers more than one, set to the interface language, so the clinician
changes it in place and the instrument still starts on one click. Only the
languages the instance has active are offered, and a card with no choice to make
carries no dropdown.

- Administering: the chosen language applies to the instrument only, interactive
  instruments included, so the application interface keeps its own language and a
  switch from inside the instrument no longer moves the interface with it.
- Assigning: the create dialog asks for the language, and the assignment carries
  it on the link as ?lang=, which the gateway already honours, so the copied link,
  the QR code and the emailed link all open in the same language. The email
  language changes only the email text; a link created without a language still
  takes the email's.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…er asks for

A link is created before anyone knows what its reader speaks, so most carry no
language of their own. Until now one of those opened in the instance's first
active language whatever the reader's browser asked for; it now negotiates
Accept-Language and falls back to that first active language only when the
browser asks for none the instance has.

Resolved server-side, like the ?lang= it falls back from, so the server-rendered
pass and the hydration pass agree rather than rendering one language and swapping.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ser by default

The create dialog now offers the subject's browser language, which it starts on,
beside one option per language the instrument offers. Choosing the default stores
no language on the link, so the gateway reads the browser; choosing a language
pins the link to it.

Emailing no longer sets a language on a link that has none: with the browser
default that is the common case, and setting it would override the subject's own
browser from the sender's choice of email language. The email language now only
ever changes the email text, and a confirmation asks before sending an email in a
language the link does not open in.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…eader asks for

A `?lang=` naming a language the instance no longer offers short-circuited the
negotiation and rendered the first active language, so a link pinned to a
language an administrator later turned off ignored the reader's browser
entirely — while a link naming an unparseable language honoured it. Only an
active requested language now settles the matter.

The negotiated HTML also declares `Vary: Accept-Language`, without which a
shared cache may serve one subject the language of another, and the suite pins
`locale: 'en-US'` so an assertion on English copy no longer depends on the
locale of the machine running it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The datahub's email form defaulted to the clinician's own interface language,
so emailing an assignment pinned to another one warned about a mismatch every
time rather than only when the two genuinely diverge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…eached

`allowedLanguages` is required where every caller already passed it, `pick` no
longer returns a choice its caller discards, and `withLinkLanguage` is inlined
at its one call site, which composes the link a line earlier and so can never
hand it the existing query the helper existed to replace.

Also waits out libui's `suspendWhileSubmitting` window in the remote-assignment
tests: the link renders before the form clears its own submitting state, so a
test ending on the link left that update to land after teardown.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…olve it

The confirmation fired whenever the email's language differed from the link's,
including when no template was authored in the link's language at all — where
"Send anyway" was the only way through, on every send. It now asks only when
the sender could have picked that language, which is when the mismatch is a
choice rather than the only option.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
HTTP does not distinguish the case of a parameter name, so `fr;Q=0.1,en;Q=0.9`
gave both tags the default quality and served French — the language the client
least wanted. A quality the header names but that cannot be read is now taken
as the default of 1, as the documented rule always said, rather than as 0,
which the filter then dropped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`InteractiveContent` took `language` and `onChangeLanguage` as an optional pair
and fell back to the interface language, though both call sites pass what
`useInstrumentLanguage` always returns; the absent variant had no caller but
its own test. The dialog's `isCreateModalOpen && choice !== null` loses an
operand that cannot be false, two `waitFor`s whose assertion never throws are
plain assertions again, the pinned-locale comment moves beside the locale, and
the administer spec starts its session through `getPageModel` like its
siblings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@thomasbeaudry
thomasbeaudry force-pushed the feat/administer-language branch from 6c3667d to 3509c78 Compare November 20, 2026 20:52
@github-actions

Copy link
Copy Markdown

This pull request was closed because its body does not meet .agents/skills/opening-pr/SKILL.md:

  • The review block names no commit matching the head 3509c78c741be14b922064b16834ec25773ab634.

Fix the body with gh pr edit <number> --body-file <path>, then gh pr reopen <number>.

@github-actions github-actions Bot closed this Nov 20, 2026
@thomasbeaudry thomasbeaudry reopened this Nov 20, 2026
@github-actions github-actions Bot added Status: Waiting on Review Automated: unreviewed, pushed since the last review, or review re-requested and removed Status: Needs Rebase Automated: conflicts with main; the author rebases labels Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Waiting on Review Automated: unreviewed, pushed since the last review, or review re-requested

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant