feat: sv/en localization for the pre-checkin flow

Sessions now carry a language. The flow engine collapses `{ sv, en }` text
maps in a step's `with` block into a plain string for that language, so a
step declaring `title: "string"` accepts either form in YAML without any
per-step schema change. Steps that generate text in code get `ctx.language`
plus `resolveLocalized`.

The language is chosen on a new `base:selectLanguage` step, placed first in
stepConfig.pre-checkin.yml. Its screen is deliberately bilingual - at that
point we don't know what the user reads. Going back and switching re-resolves
the rest of the flow.

On the client the language rides along on `session:info` into a LanguageContext,
where screens localize their own hardcoded strings through a small
`useTranslations(dict)` helper in plugin-api (no i18n framework). The link
landing page renders before the socket authenticates, so it is bilingual
rather than guessing a locale.

Also resolves data source and subgroup names server-side, so they travel as
plain strings instead of locale maps the client has to pick `.sv` from.

The on-site kiosk flow is untouched: it has no selectLanguage step and stays
Swedish.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: scriptcoded

packages/backend/config/stepConfig.pre-checkin.yml

@@ -1,4 +1,11 @@
+# Pre-checkin runs in a browser, opened from a link sent to the kår. Text is
+# authored per language as `{ sv, en }` maps; the flow engine collapses those to
+# a single string for the language the user picks in the first step.
 steps:
+  # Must stay first: every step after it gets its text resolved in the chosen
+  # language. The screen itself is bilingual, so it needs no text config.
+  - uses: base:selectLanguage
+
   - uses: base:identify
     id: identify
     with:
@@ -9,11 +16,17 @@ steps:
       # Pre-checkin runs in a browser without a card reader, so the start screen
       # must not mention scanning. Manual entry is the only path here, hence the
       # larger button and the hidden scanner callout/arrow.
-      title: Identifiera dig
-      description: Ange ditt person- eller medlemsnummer för att komma igång.
+      title:
+        sv: Identifiera dig
+        en: Identify yourself
+      description:
+        sv: Ange ditt person- eller medlemsnummer för att komma igång.
+        en: Enter your social security or membership number to get started.
       hideCallout: true
       hideScannerArrow: true
-      manualEntryLabel: Ange person- eller medlemsnummer
+      manualEntryLabel:
+        sv: Ange person- eller medlemsnummer
+        en: Enter social security or membership number
       largeManualEntryButton: true
 
   - if: |
@@ -24,16 +37,22 @@ steps:
       }}
     uses: base:block
     with:
-      title: "Du kan inte checka in"
-      message: "Endast ledare kan checka in deltagare."
+      title:
+        sv: "Du kan inte checka in"
+        en: "You cannot check in"
+      message:
+        sv: "Endast ledare kan checka in deltagare."
+        en: "Only leaders can check in participants."
 
   - uses: base:deduplicateSession
     with:
       force: resume
 
   - uses: base:selectSubjects
     with:
-      description: Välj vilka du vill checka in. Avmarkera de som inte är på plats.
+      description:
+        sv: Välj vilka du vill checka in. Avmarkera de som inte är på plats.
+        en: Select who you want to check in. Deselect anyone who isn't here.
 
   # Lists the selected subjects that are "ledarfunktionärer" (a distinct fee,
   # mapped to the `leaderstaff` subGroup in dataSourceConfig.yml) with an
@@ -42,8 +61,12 @@ steps:
   - uses: base:filterSubjects
     with:
       filter: "participant.subGroup == 'leaderstaff'"
-      title: "Ledarfunktionärer"
-      message: "Följande personer är anmälda som ledarfunktionärer. Ledarfunktionärer bor och äter med er kår, men arbetar som funktionärer på lägret och deltar alltså inte på programpass med kåren. Kontrollera noggrant att alla personer i listan är medvetna om detta, och att ingen ledarfunktionär saknas i listan. Om något inte stämmer fortsätter ni med incheckningen och meddelar oss när ni checkar in på plats."
+      title:
+        sv: "Ledarfunktionärer"
+        en: "Leader staff"
+      message:
+        sv: "Följande personer är anmälda som ledarfunktionärer. Ledarfunktionärer bor och äter med er kår, men arbetar som funktionärer på lägret och deltar alltså inte på programpass med kåren. Kontrollera noggrant att alla personer i listan är medvetna om detta, och att ingen ledarfunktionär saknas i listan. Om något inte stämmer fortsätter ni med incheckningen och meddelar oss när ni checkar in på plats."
+        en: "The following people are registered as leader staff. Leader staff sleep and eat with your scout group, but work as staff at the camp and therefore do not take part in the group's programme activities. Check carefully that everyone in the list is aware of this, and that no leader staff is missing from the list. If something is not right, continue with the check-in and let us know when you check in on site."
       whenEmpty: skip
 
   # Informational (never blocks): shows the checking-in leader which of the
@@ -63,13 +86,21 @@ steps:
       safeFromHarmValidYears: 3
       criminalRecordExtractValidYears: 3
       checkDate: "2026-08-01"
-      title: "Ledare som saknar krav"
-      message: "Följande ledare har inte giltigt Trygga Möten och/eller registerutdrag registrerat i Scoutnet. Ni som kår ansvarar själva för att säkerställa att samtliga ledare har uppvisat giltigt Trygga Möten-intyg samt utdrag ut polisens belastningsregister."
+      title:
+        sv: "Ledare som saknar krav"
+        en: "Leaders missing requirements"
+      message:
+        sv: "Följande ledare har inte giltigt Trygga Möten och/eller registerutdrag registrerat i Scoutnet. Ni som kår ansvarar själva för att säkerställa att samtliga ledare har uppvisat giltigt Trygga Möten-intyg samt utdrag ut polisens belastningsregister."
+        en: "The following leaders do not have a valid Safe from Harm (Trygga Möten) certificate and/or criminal record extract registered in Scoutnet. Your scout group is itself responsible for making sure that every leader has presented a valid Safe from Harm certificate and an extract from the Swedish police criminal records."
 
   - uses: base:markPreliminaryCheckedIn
     required: true
 
   - uses: base:message
     with:
-      title: Tack!
-      message: Nu är du klar för tillfället. Glöm inte att skicka en ledare med lite koll till infotältet på Hjärtat för att slutföra incheckningen och hämta er kårpåse med märken och annat kul när ni väl är på lägerområdet!
+      title:
+        sv: Tack!
+        en: Thank you!
+      message:
+        sv: Nu är du klar för tillfället. Glöm inte att skicka en ledare med lite koll till infotältet på Hjärtat för att slutföra incheckningen och hämta er kårpåse med märken och annat kul när ni väl är på lägerområdet!
+        en: You are done for now. Once you are on the camp site, don't forget to send a leader who is up to speed to the info tent at Hjärtat to complete the check-in and pick up your group bag with badges and other fun things!

packages/backend/config_dev/stepConfig.pre-checkin.yml

@@ -1,4 +1,8 @@
 steps:
+  # Must stay first: every step after it gets its `{ sv, en }` text resolved in
+  # the chosen language.
+  - uses: base:selectLanguage
+
   - uses: base:identify
     id: identify
     with:
@@ -14,8 +18,12 @@ steps:
       }}
     uses: base:block
     with:
-      title: "Du kan inte checka in"
-      message: "Endast ledare kan checka in deltagare."
+      title:
+        sv: "Du kan inte checka in"
+        en: "You cannot check in"
+      message:
+        sv: "Endast ledare kan checka in deltagare."
+        en: "Only leaders can check in participants."
 
   - uses: base:deduplicateSession
     with:

packages/backend/prisma/migrations/20260724214909_add_session_language/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "CheckinSession" ADD COLUMN     "language" TEXT NOT NULL DEFAULT 'sv';

packages/backend/prisma/schema.prisma

@@ -89,6 +89,11 @@ model CheckinSession {
   params     Json                     @default("{}")
   stepData   CheckinSessionStepData[]
 
+  // The language this session is conducted in. Drives resolution of
+  // `{ sv, en }` text maps in the step config and the kiosk/link UI. Set by
+  // the `base:selectLanguage` step; flows without that step keep the default.
+  language String @default("sv")
+
   actor CheckinActor?
 
   subjects CheckinSubject[]

packages/backend/src/core/i18n/localized.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  coerceLanguage,
+  isLocalizedString,
+  resolveLocalized,
+  resolveLocalizedDeep,
+} from "./localized.ts";
+
+describe("isLocalizedString", () => {
+  it("accepts maps whose keys are all supported languages", () => {
+    expect(isLocalizedString({ sv: "Hej", en: "Hi" })).toBe(true);
+    expect(isLocalizedString({ sv: "Hej" })).toBe(true);
+    expect(isLocalizedString({ en: "Hi" })).toBe(true);
+  });
+
+  it("rejects anything that isn't purely a language map", () => {
+    expect(isLocalizedString({ sv: "Hej", nb: "Hei" })).toBe(false);
+    expect(isLocalizedString({ sv: 1 })).toBe(false);
+    expect(isLocalizedString({ dietMjolkprotein: "Mjölkprotein" })).toBe(false);
+    expect(isLocalizedString({})).toBe(false);
+    expect(isLocalizedString(["sv"])).toBe(false);
+    expect(isLocalizedString(null)).toBe(false);
+    expect(isLocalizedString("sv")).toBe(false);
+  });
+});
+
+describe("resolveLocalized", () => {
+  it("picks the requested language", () => {
+    expect(resolveLocalized({ sv: "Hej", en: "Hi" }, "en")).toBe("Hi");
+  });
+
+  it("falls back to Swedish, then to any available value", () => {
+    expect(resolveLocalized({ sv: "Hej" }, "en")).toBe("Hej");
+    expect(resolveLocalized({ en: "Hi" }, "nb")).toBe("Hi");
+  });
+});
+
+describe("resolveLocalizedDeep", () => {
+  it("collapses maps nested in objects and arrays", () => {
+    const input = {
+      title: { sv: "Tack!", en: "Thanks!" },
+      message: "Plain",
+      nested: { description: { sv: "Beskrivning", en: "Description" } },
+      items: [{ label: { sv: "Ett", en: "One" } }, "raw"],
+    };
+
+    expect(resolveLocalizedDeep(input, "en")).toEqual({
+      title: "Thanks!",
+      message: "Plain",
+      nested: { description: "Description" },
+      items: [{ label: "One" }, "raw"],
+    });
+  });
+
+  it("leaves non-locale objects and primitives untouched", () => {
+    const input = {
+      dataSources: ["groups"],
+      safeFromHarmValidYears: 3,
+      hideCallout: true,
+      labels: { dietMjolkprotein: "Mjölkprotein" },
+      missing: null,
+      absent: undefined,
+    };
+
+    expect(resolveLocalizedDeep(input, "en")).toEqual(input);
+  });
+
+  it("handles nullish input", () => {
+    expect(resolveLocalizedDeep(null, "en")).toBe(null);
+    expect(resolveLocalizedDeep(undefined, "en")).toBe(undefined);
+  });
+});
+
+describe("coerceLanguage", () => {
+  it("passes through supported languages and defaults otherwise", () => {
+    expect(coerceLanguage("en")).toBe("en");
+    expect(coerceLanguage("sv")).toBe("sv");
+    expect(coerceLanguage("nb")).toBe("sv");
+    expect(coerceLanguage(undefined)).toBe("sv");
+  });
+});

packages/backend/src/core/i18n/localized.ts

@@ -0,0 +1,79 @@
+/**
+ * Localized text resolution.
+ *
+ * Step config text may be authored either as a plain string (single language)
+ * or as a `{ sv: "...", en: "..." }` map. Rather than making every step
+ * declare a localized input type, the flow engine collapses these maps to a
+ * single string for the session's language before the step ever sees its
+ * inputs - so a step declaring `title: "string"` transparently supports both
+ * forms. See `resolveLocalizedDeep` and `getCurrentStep`.
+ */
+
+import {
+  resolveLocalized,
+  SUPPORTED_LANGUAGES,
+} from "@scouterna/scoutin-plugin-api/backend";
+
+export {
+  coerceLanguage,
+  DEFAULT_LANGUAGE,
+  isSupportedLanguage,
+  type Language,
+  resolveLocalized,
+  SUPPORTED_LANGUAGES,
+} from "@scouterna/scoutin-plugin-api/backend";
+
+const supported = new Set<string>(SUPPORTED_LANGUAGES);
+
+/**
+ * A localized string map is a plain object whose keys are *all* supported
+ * language codes and whose values are all strings. The all-keys-known
+ * requirement is what keeps this from misfiring on ordinary config objects
+ * (e.g. a diet-flag map, or `{ sv: 1 }`).
+ */
+export function isLocalizedString(
+  value: unknown,
+): value is Record<string, string> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const entries = Object.entries(value);
+  if (entries.length === 0) return false;
+
+  return entries.every(
+    ([key, val]) => supported.has(key) && typeof val === "string",
+  );
+}
+
+/**
+ * Deep-walks objects and arrays, replacing every localized string map with the
+ * resolved string for `language`. Everything else is returned untouched.
+ */
+export function resolveLocalizedDeep<T>(value: T, language: string): unknown {
+  if (isLocalizedString(value)) {
+    return resolveLocalized(value, language);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveLocalizedDeep(item, language));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = resolveLocalizedDeep(val, language);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+/** Object-preserving wrapper for the common `with`-block case. */
+export function resolveLocalizedInputs(
+  inputs: Record<string, unknown>,
+  language: string,
+): Record<string, unknown> {
+  return resolveLocalizedDeep(inputs, language) as Record<string, unknown>;
+}

packages/backend/src/core/websocket/messageTypes.ts

@@ -42,6 +42,8 @@ export const messageTypes = createMessageRegistry()
     "session:info",
     type({
       "actor?": type({ firstName: "string", lastName: "string" }).or("null"),
+      // The session language, so the client can localize its own strings.
+      "language?": "string",
     }),
   )
   .register(

packages/backend/src/core/websocket/sessionRegistry.ts

@@ -6,6 +6,8 @@ type ScreenData = { screenId: string; payload: object };
 type StepMeta = {
   idInFlow?: string;
   evaluatedInputs?: Record<string, unknown>;
+  /** The session language the inputs above were resolved for. */
+  language?: string;
 };
 
 type SessionEntry = {
@@ -59,6 +61,16 @@ export function setStepMeta(sessionId: string, meta: StepMeta): void {
   getOrCreate(sessionId).stepMeta = meta;
 }
 
+/**
+ * Updates the language on the current step's metadata. Used when a step
+ * changes the session language mid-step (`base:selectLanguage`) so that
+ * `ctx.language` reflects the new choice immediately, without a DB round trip.
+ */
+export function setStepMetaLanguage(sessionId: string, language: string): void {
+  const entry = getOrCreate(sessionId);
+  entry.stepMeta = { ...(entry.stepMeta ?? {}), language };
+}
+
 export function clearScreenTracking(sessionId: string): void {
   getOrCreate(sessionId).hasShownScreen = false;
 }

packages/backend/src/core/workflow/step.ts

@@ -1,8 +1,8 @@
-import type { StepDefinition } from "../../config/stepConfig.ts";
 import {
   deleteStepData,
   findLastCompletedStep,
   getCurrentStep,
+  type ResolvedStepDefinition,
 } from "../../domains/workflows/step.service.ts";
 import { stepRegistry } from "../../domains/workflows/steps.ts";
 import { getLogger } from "../logging/logger.ts";
@@ -18,7 +18,7 @@ import { createStepContext } from "./stepContext.ts";
 export async function startStep(
   c: TypedContext,
   ws: TypedWSContext<unknown>,
-  stepDef: StepDefinition,
+  stepDef: ResolvedStepDefinition,
 ) {
   const step = stepRegistry.get(stepDef.uses);
 
@@ -37,6 +37,7 @@ export async function startStep(
   setStepMeta(sessionId, {
     idInFlow: stepDef.id,
     evaluatedInputs: stepDef.with,
+    language: stepDef.language,
   });
   clearScreenTracking(sessionId);