Add i18n support: per-locale catalogs, URL-driven locale, translated core and examples

src/auth/flow-view.test.ts

@@ -34,9 +34,11 @@ test("maps a password login flow: csrf hidden, themed email/password fields, a s
   assert.equal(view.method, "post");
   assert.deepEqual(view.hidden, [{ name: "csrf_token", value: "tok123" }]);
 
-  // Visible fields carry label, type, required, autocomplete + a themed input icon.
+  // Visible fields carry label, type, required, autocomplete + a themed input icon. The label is
+  // ours (auth.field.identifier) rather than Kratos' wording — Kratos' generic trait-label id is
+  // ambiguous, so field labels are keyed on the input name.
   assert.equal(view.fields.length, 2);
-  assert.deepEqual(view.fields[0], { autocomplete: "username", icon: "i-mail", id: "field-identifier", label: "E-Mail", name: "identifier", required: true, type: "email" });
+  assert.deepEqual(view.fields[0], { autocomplete: "username", icon: "i-mail", id: "field-identifier", label: "Email", name: "identifier", required: true, type: "email" });
   assert.equal(view.fields[1]?.icon, "i-lock");
   assert.equal(view.fields[1]?.type, "password");
 
@@ -53,7 +55,7 @@ test("maps a password login flow: csrf hidden, themed email/password fields, a s
   assert.equal(view.messages.length, 0);
 });
 
-test("maps field errors and flow-level messages by tone", () => {
+test("maps field errors and flow-level messages by tone, translating the ids we cover", () => {
   const view = buildFlowView(
     flow(
       [
@@ -65,13 +67,15 @@ test("maps field errors and flow-level messages by tone", () => {
     "login",
   );
 
-  // Submitted value is preserved; the node's error rides on the field.
+  // Submitted value is preserved; the node's error rides on the field — with our wording for the
+  // id (4000002), since Kratos writes "Property password is missing." for every required field.
   assert.equal(view.fields[0]?.value, "taken@example.com");
-  assert.deepEqual(view.fields[0]?.error, { text: "This email is already in use." });
+  assert.deepEqual(view.fields[0]?.error, { text: "This field is required." });
 
-  // Flow messages map error→neg, info→info (success→pos covered by the tone map).
+  // Flow messages map error→neg, info→info (success→pos covered by the tone map). A mapped id
+  // (4000006) is replaced; an id we hold no key for keeps Kratos' own text.
   assert.deepEqual(view.messages, [
-    { text: "The provided credentials are invalid.", tone: "neg" },
+    { text: "The credentials are invalid. Check for typos in your email address or password.", tone: "neg" },
     { text: "Check your email.", tone: "info" },
   ]);
 });

src/auth/flow-view.ts

@@ -4,6 +4,8 @@
 // configured `oidc` provider. The form posts straight back to `flow.ui.action`, so Kratos
 // owns its CSRF; we only render and map errors. No providers configured ⇒ no SSO buttons.
 
+import { ENGLISH } from "../i18n/english.ts";
+import type { Translate } from "../i18n/translate.ts";
 import type { Flow, FlowType, UiNode } from "./kratos-public.ts";
 
 export interface FlowField {
@@ -66,14 +68,39 @@ export const AUTH_FLOWS: Record<string, FlowType> = {
   "/verification": "verification",
 };
 
-const CHROME: Record<FlowType, FlowChrome> = {
-  login: { alt: { href: "/registration", label: "Create one", text: "Don't have an account?" }, sub: "Welcome back. Enter your details to continue.", title: "Sign in" },
-  recovery: { alt: { href: "/login", label: "Sign in", text: "Remembered it?" }, back: { href: "/login", label: "Back to sign in" }, sub: "Enter your email and we'll send you a recovery code.", title: "Reset password" },
-  registration: { alt: { href: "/login", label: "Sign in", text: "Already have an account?" }, sub: "Get started — it only takes a minute.", title: "Create account" },
-  settings: { sub: "Update your account details.", title: "Account settings" },
-  verification: { back: { href: "/login", label: "Back to sign in" }, sub: "Enter the code we sent you.", title: "Verify your email" },
+// Where each flow's card links; its words come from the catalog under `auth.<flow>.*`.
+const LINKS: Record<FlowType, { alt?: string; back?: boolean }> = {
+  login: { alt: "/registration" },
+  recovery: { alt: "/login", back: true },
+  registration: { alt: "/login" },
+  settings: {},
+  verification: { back: true },
 };
 
+function chromeFor(type: FlowType, t: Translate): FlowChrome {
+  const links = LINKS[type];
+  return {
+    ...(links.alt ? { alt: { href: links.alt, label: t(`auth.${type}.altLabel`), text: t(`auth.${type}.altText`) } } : {}),
+    ...(links.back ? { back: { href: "/login", label: t(`auth.${type}.back`) } } : {}),
+    sub: t(`auth.${type}.sub`),
+    title: t(`auth.${type}.title`),
+  };
+}
+
+// A string Kratos authored (a field label, a button, a validation message). Kratos writes English
+// and tags it with a stable numeric id, so the first key we hold a translation for wins and
+// anything unmapped keeps Kratos' own words — never a bare key on screen.
+function kratosText(t: Translate, fallback: string, ...keys: (string | undefined)[]): string {
+  for (const key of keys) {
+    if (key === undefined) continue;
+    const text = t(key);
+    if (text !== key) return text;
+  }
+  return fallback;
+}
+
+const idKey = (id: number | undefined): string | undefined => (id === undefined ? undefined : `kratos.${id}`);
+
 const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
 
 // Themed input icon by field semantics; undefined ⇒ no icon.
@@ -93,7 +120,7 @@ function tone(type: string): FlowMessage["tone"] {
 
 const ssoLogo = (value: string): string => (value.charAt(0) || "?").toUpperCase();
 
-function toField(node: UiNode, name: string, type: string): FlowField {
+function toField(node: UiNode, name: string, type: string, t: Translate): FlowField {
   const value = str(node.attributes["value"]);
   // The recovery/verification one-time code: numeric, and Kratos doesn't trim it, so a stray pasted
   // space makes it reject the code as "invalid". A digits-only pattern + numeric keypad block that in
@@ -104,11 +131,13 @@ function toField(node: UiNode, name: string, type: string): FlowField {
   const errorMsg = node.messages.find((m) => m.type === "error");
   return {
     id: "field-" + name.replace(/[^a-z0-9]+/gi, "-"),
-    label: node.meta.label?.text ?? name,
+    // Kratos' generic trait label (id 1070002) is "Email" here and "First name" on a schema with
+    // that trait, so a field falls back to its input name — the one thing that is unambiguous.
+    label: kratosText(t, node.meta.label?.text ?? name, idKey(node.meta.label?.id), `auth.field.${name}`),
     name,
     type,
     ...(autocomplete ? { autocomplete } : {}),
-    ...(errorMsg ? { error: { text: errorMsg.text } } : {}),
+    ...(errorMsg ? { error: { text: kratosText(t, errorMsg.text, idKey(errorMsg.id)) } } : {}),
     ...(icon ? { icon } : {}),
     ...(isCode ? { inputmode: "numeric", pattern: "[0-9]*" } : {}),
     ...(node.attributes["required"] === true ? { required: true } : {}),
@@ -116,7 +145,7 @@ function toField(node: UiNode, name: string, type: string): FlowField {
   };
 }
 
-export function buildFlowView(flow: Flow, type: FlowType): FlowView {
+export function buildFlowView(flow: Flow, type: FlowType, t: Translate = ENGLISH): FlowView {
   const hidden: { name: string; value: string }[] = [];
   const fields: FlowField[] = [];
   const buttons: FlowButton[] = [];
@@ -136,9 +165,10 @@ export function buildFlowView(flow: Flow, type: FlowType): FlowView {
       hidden.push({ name, value: str(node.attributes["value"]) ?? "" });
     } else if (inputType === "submit" || inputType === "button") {
       const value = str(node.attributes["value"]);
-      buttons.push({ label: node.meta.label?.text ?? "Continue", ...(name ? { name } : {}), ...(value != null ? { value } : {}) });
+      const label = kratosText(t, node.meta.label?.text ?? t("auth.continue"), idKey(node.meta.label?.id));
+      buttons.push({ label, ...(name ? { name } : {}), ...(value != null ? { value } : {}) });
     } else {
-      fields.push(toField(node, name, inputType));
+      fields.push(toField(node, name, inputType, t));
     }
   }
 
@@ -147,10 +177,10 @@ export function buildFlowView(flow: Flow, type: FlowType): FlowView {
     buttons,
     fields,
     hidden,
-    messages: (flow.ui.messages ?? []).map((m) => ({ text: m.text, tone: tone(m.type) })),
+    messages: (flow.ui.messages ?? []).map((m) => ({ text: kratosText(t, m.text, idKey(m.id)), tone: tone(m.type) })),
     method: flow.ui.method || "post",
     sso,
     ...(type === "login" ? { recoverHref: "/recovery" } : {}),
-    ...CHROME[type],
+    ...chromeFor(type, t),
   };
 }

src/auth/routes.ts

@@ -29,7 +29,7 @@ export interface AuthRouteDeps {
 }
 
 const TEXT_PLAIN = { "content-type": "text/plain; charset=utf-8" };
-const FORBIDDEN: RouteResult = { data: { title: "Forbidden" }, status: 403, view: "403" };
+const FORBIDDEN: RouteResult = { status: 403, view: "403" };
 
 // Scheme + host for a self-referencing absolute URL (Kratos/Hydra return targets). Host reflects
 // what the browser used (so it matches the allow-lists); scheme follows SECURE_COOKIES. A spoofed
@@ -87,14 +87,14 @@ function flowPage(kratos: KratosPublic, flowType: FlowType, secureCookies: boole
       // documented, so render an honest 503 rather than the catch-all "error on our end" 500.
       if (!(err instanceof KratosError) || err.status >= 500) {
         ctx.log.warn("auth flow failed (Ory unreachable?)", { error: String(err), path: pathname });
-        return { data: { title: "Sign-in unavailable" }, status: 503, view: "503" };
+        return { status: 503, view: "503" };
       }
       throw err; // any other Kratos 4xx → the catch-all (genuinely unexpected)
     }
     // Rendered inside the unified app shell, so set a fresh CSRF cookie when minted — the
     // shell's Sign-out form (shown on /settings, where the user is signed in) needs the token.
     csrf.setCookie();
-    return { data: { chrome: ctx.chrome, flow: buildFlowView(flow, flowType) }, view: "auth" };
+    return { data: { chrome: ctx.chrome, flow: buildFlowView(flow, flowType, ctx.t) }, view: "auth" };
   };
 }
 
@@ -114,7 +114,7 @@ function oauthLogin(deps: { hydra: HydraAdmin; kratos: KratosPublic }, secureCoo
       // A stale/invalid/consumed challenge (Hydra 4xx — back button, slow login, re-used URL) is
       // user-reachable: tell them to restart rather than 500. A 5xx (Hydra down) rethrows → 500.
       if (err instanceof HydraError && err.status < 500) {
-        return { headers: TEXT_PLAIN, html: "This sign-in request has expired. Please start again from the application you were signing in to.", status: 400 };
+        return { headers: TEXT_PLAIN, html: ctx.t("oauth.loginExpired"), status: 400 };
       }
       throw err;
     }
@@ -122,9 +122,9 @@ function oauthLogin(deps: { hydra: HydraAdmin; kratos: KratosPublic }, secureCoo
 }
 
 // Stale/consumed challenge (Hydra 4xx) → recoverable 400; a genuine outage (5xx) → 500 (as /oauth2/login).
-function consentError(err: unknown): RouteResult {
+function consentError(err: unknown, ctx: RequestContext): RouteResult {
   if (err instanceof HydraError && err.status < 500) {
-    return { headers: TEXT_PLAIN, html: "This authorization request has expired. Please start again from the application you were signing in to.", status: 400 };
+    return { headers: TEXT_PLAIN, html: ctx.t("oauth.consentExpired"), status: 400 };
   }
   throw err;
 }
@@ -143,7 +143,7 @@ function consentScreen(deps: { hydra: HydraAdmin; kratos: KratosPublic }, brand:
       csrf.setCookie();
       return { data: { brand, consent: view, csrfField: CSRF_FIELD, csrfToken: csrf.token }, view: "oauth-consent" };
     } catch (err) {
-      return consentError(err);
+      return consentError(err, ctx);
     }
   };
 }
@@ -164,7 +164,7 @@ function consentDecision(deps: { hydra: HydraAdmin; kratos: KratosPublic }): Bui
         : await rejectConsent(deps, challenge);
       return { redirect };
     } catch (err) {
-      return consentError(err);
+      return consentError(err, ctx);
     }
   };
 }
@@ -184,7 +184,7 @@ function oauthLogout(hydra: HydraAdmin): BuiltinRoute["handler"] {
     } catch (err) {
       // Stale/consumed challenge (Hydra 4xx) → recoverable 400; a genuine outage (5xx) → 500.
       if (err instanceof HydraError && err.status < 500) {
-        return { headers: TEXT_PLAIN, html: "This logout request has expired. Please start again from the application you were signing out of.", status: 400 };
+        return { headers: TEXT_PLAIN, html: ctx.t("oauth.logoutExpired"), status: 400 };
       }
       throw err;
     }
@@ -229,7 +229,7 @@ function logout(kratos: KratosPublic, secureCookies: boolean): BuiltinRoute["han
 // canonical-host redirect prevents the common cause (a lost cross-host CSRF cookie); this is the
 // honest fallback for any genuine flow error. The id is shown only for support reference.
 const errorSink = (ctx: RequestContext): RouteResult =>
-  ({ data: { id: ctx.url.searchParams.get("id"), title: "Sign-in problem" }, view: "error" });
+  ({ data: { id: ctx.url.searchParams.get("id") }, view: "error" });
 
 export function buildAuthRoutes({ hydra, keto, kratos, kratosAdmin, menu, secureCookies }: AuthRouteDeps): BuiltinRoute[] {
   const routes: BuiltinRoute[] = [];