feat(coach): message catalog for the dialog in all seven languages

Adds every string the dialog needs up front: step labels, table titles,
columns and controls, the method line, the follow-up chips and their
setting, the clarification card, and the caption of an answer reused from
a stored table. A key catalog shared by server and client names each one;
a test holds the catalog and the bundles equal in both directions.
This commit is contained in:
Marc-André Bombeck committed 2026-09-27 10:50:49 +02:00
1 parent ad72ae3e4c
commit fe0a03761e
9 files changed
+1630 -7

No files matched your search

@@ -0,0 +1,157 @@
/**
* The dialog's key catalog and the seven bundles agree, both ways.
*
* Forward: every key the catalog can produce — every label map entry, every
* domain, window, period and granularity, every plural tier — resolves in
* every locale. Reverse: every leaf under the namespaces the catalog owns
* (`coach.step`, `coach.result`, `coach.method`, `coach.followUp`,
* `coach.clarify`, `coach.reuse`) is one the catalog can produce, so a
* string cannot sit in the bundles with nothing able to reach it.
*
* Checked by breaking it: deleting `coach.result.copied` from `ko.json`
* fails the forward test by locale and key; adding an unused leaf under
* `coach.step` fails the reverse test by name.
*/
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { locales, type Locale } from "@/lib/i18n/config";
import {
coachScopeWindowSchema,
type CoachResultGranularity,
type CoachResultPeriod,
} from "@/lib/ai/coach/types";
import { coachStepDomainSchema } from "@/lib/ai/coach/stream-events";
import {
COACH_CLARIFY_UI_KEYS,
COACH_FOLLOW_UP_KEYS,
COACH_FOLLOW_UP_UI_KEYS,
COACH_METHOD_ABSENT_KEYS,
COACH_METHOD_AGGREGATION_KEYS,
COACH_METHOD_KEYS,
COACH_RESULT_COLUMN_KEYS,
COACH_RESULT_TITLE_KEYS,
COACH_RESULT_UI_KEYS,
COACH_RESULT_WITHHELD_KEYS,
COACH_REUSE_CAPTION_KEY,
COACH_STEP_LABEL_KEYS,
COACH_STEP_REASON_KEYS,
COACH_STEP_UI_KEYS,
clarifyWindowLabelKey,
coachDomainLabelKey,
coachGranularityLabelKey,
coachPeriodLabelKey,
coachWindowLabelKey,
methodAveragesKey,
methodReadingsKey,
methodTotalsKey,
stepHeaderDoneKey,
stepMetricsKey,
stepReadingsKey,
stepRowsKey,
} from "@/lib/ai/coach/dialog-keys";
const ROOT = join(__dirname, "../../../../..");
function bundle(locale: Locale): Record<string, unknown> {
return JSON.parse(
readFileSync(join(ROOT, "messages", `${locale}.json`), "utf8"),
) as Record<string, unknown>;
}
function leaves(node: unknown, prefix: string, out: Map<string, unknown>) {
if (node && typeof node === "object") {
for (const [key, value] of Object.entries(node)) {
leaves(value, prefix ? `${prefix}.${key}` : key, out);
}
} else {
out.set(prefix, node);
}
return out;
}
const PERIODS: CoachResultPeriod[] = ["current", "previous", "yearAgo"];
const GRANULARITIES: CoachResultGranularity[] = ["day", "week", "month"];
/** Counts that land on every plural tier some locale uses. */
const COUNTS = [0, 1, 2, 3, 5, 12, 22];
function catalogKeys(): Set<string> {
const keys = new Set<string>([
...Object.values(COACH_STEP_LABEL_KEYS),
...Object.values(COACH_STEP_UI_KEYS),
...Object.values(COACH_STEP_REASON_KEYS),
...Object.values(COACH_RESULT_TITLE_KEYS),
...Object.values(COACH_RESULT_COLUMN_KEYS),
...Object.values(COACH_RESULT_UI_KEYS),
...Object.values(COACH_RESULT_WITHHELD_KEYS),
...Object.values(COACH_METHOD_KEYS),
...Object.values(COACH_METHOD_AGGREGATION_KEYS),
...Object.values(COACH_METHOD_ABSENT_KEYS),
...Object.values(COACH_FOLLOW_UP_KEYS),
...Object.values(COACH_FOLLOW_UP_UI_KEYS),
...Object.values(COACH_CLARIFY_UI_KEYS),
COACH_REUSE_CAPTION_KEY,
]);
for (const domain of coachStepDomainSchema.options) {
keys.add(coachDomainLabelKey(domain));
}
for (const window of coachScopeWindowSchema.options) {
keys.add(coachWindowLabelKey(window));
keys.add(clarifyWindowLabelKey(window));
}
for (const period of PERIODS) {
keys.add(coachPeriodLabelKey(period));
}
for (const granularity of GRANULARITIES) {
keys.add(coachGranularityLabelKey(granularity));
keys.add(methodAveragesKey(granularity));
keys.add(methodTotalsKey(granularity));
}
for (const locale of locales) {
for (const count of COUNTS) {
keys.add(stepHeaderDoneKey(count, locale));
keys.add(stepReadingsKey(count, locale));
keys.add(stepRowsKey(count, locale));
keys.add(stepMetricsKey(count, locale));
keys.add(methodReadingsKey(count, locale));
}
}
return keys;
}
const OWNED = [
"coach.step",
"coach.result",
"coach.method",
"coach.followUp",
"coach.clarify",
"coach.reuse",
];
describe("Coach dialog keys", () => {
const keys = catalogKeys();
it("produces a non-trivial catalog", () => {
expect(keys.size).toBeGreaterThan(130);
});
it.each(locales)("every catalog key resolves in %s", (locale) => {
const strings = leaves(bundle(locale), "", new Map());
const missing = [...keys].filter(
(key) => typeof strings.get(key) !== "string" || strings.get(key) === "",
);
expect(missing).toEqual([]);
});
it("every leaf under the owned namespaces is reachable from the catalog", () => {
const strings = leaves(bundle("en"), "", new Map());
const owned = [...strings.keys()].filter((key) =>
OWNED.some((ns) => key.startsWith(`${ns}.`)),
);
expect(owned.length).toBeGreaterThan(0);
expect(owned.filter((key) => !keys.has(key))).toEqual([]);
});
});
+255
View File
@@ -0,0 +1,255 @@
/**
* The message keys of the Coach dialog: live steps, result tables, the
* method line, follow-up chips, clarifying questions, the reuse caption.
*
* One closed catalog, shared by the server (which renders every `label` in
* the request locale) and the web client (which renders `labelKey` when it
* has the string, and the server's `label` when it does not). A label never
* carries model text: it is one of these keys plus server-chosen values
* (a domain, a window, a count).
*
* Every key here exists in all seven bundles; `__tests__/dialog-keys.test.ts`
* holds that, in both directions for the namespaces this file owns.
*
* Client-safe: no server import.
*/
import type { Locale } from "@/lib/i18n/config";
import { pluralKey } from "@/lib/i18n/plural";
import {
coachScopeSourceSchema,
type CoachFollowUpKind,
type CoachMethodEntry,
type CoachResultGranularity,
type CoachResultPeriod,
type CoachScopeWindow,
type CoachStepDomain,
type CoachStepReason,
} from "@/lib/ai/coach/types";
// ── Steps ─────────────────────────────────────────────────────────────────
/** The step label templates (`{domain}`, `{window}`). */
export const COACH_STEP_LABEL_KEYS = {
read: "coach.step.read",
readWindow: "coach.step.readWindow",
snapshot: "coach.step.snapshot",
showResult: "coach.step.showResult",
reuse: "coach.step.reuse",
} as const;
/** The step list's own chrome. */
export const COACH_STEP_UI_KEYS = {
headerActive: "coach.step.headerActive",
listLabel: "coach.step.listLabel",
toggleShow: "coach.step.toggleShow",
toggleHide: "coach.step.toggleHide",
announceDone: "coach.step.announceDone",
} as const;
/** "Looked at N sources", by plural tier. */
export function stepHeaderDoneKey(count: number, locale: Locale): string {
return pluralKey("coach.step.headerDone", count, locale);
}
/** "N readings" on a step row, by plural tier. */
export function stepReadingsKey(count: number, locale: Locale): string {
return pluralKey("coach.step.readings", count, locale);
}
/** "N rows" on a step row, by plural tier. */
export function stepRowsKey(count: number, locale: Locale): string {
return pluralKey("coach.step.rows", count, locale);
}
/** "N metrics" on the snapshot step, by plural tier. */
export function stepMetricsKey(count: number, locale: Locale): string {
return pluralKey("coach.step.metrics", count, locale);
}
export const COACH_STEP_REASON_KEYS: Readonly<Record<CoachStepReason, string>> =
{
no_data: "coach.step.reason.noData",
outside_window: "coach.step.reason.outsideWindow",
module_disabled: "coach.step.reason.moduleDisabled",
retrieval_failed: "coach.step.reason.retrievalFailed",
invalid_arguments: "coach.step.reason.invalidArguments",
};
const SCOPE_SOURCES: ReadonlySet<string> = new Set(
coachScopeSourceSchema.options,
);
/**
* A domain's display name. A measurement-backed scope source reuses the
* metric names the sources rail already shows; the domains read as a whole
* have their own.
*/
export function coachDomainLabelKey(domain: CoachStepDomain): string {
return SCOPE_SOURCES.has(domain)
? `insights.coach.metric.${domain}`
: `coach.step.domain.${domain}`;
}
/** A window in running text ("last 30 days"). */
export function coachWindowLabelKey(window: CoachScopeWindow): string {
return `coach.step.window.${window}`;
}
export function coachPeriodLabelKey(period: CoachResultPeriod): string {
return `coach.step.period.${period}`;
}
export function coachGranularityLabelKey(
granularity: CoachResultGranularity,
): string {
return `coach.step.granularity.${granularity}`;
}
// ── Results ───────────────────────────────────────────────────────────────
/** Table titles; `{metric}` where the title names one. */
export const COACH_RESULT_TITLE_KEYS = {
byDay: "coach.result.title.byDay",
byWeek: "coach.result.title.byWeek",
byMonth: "coach.result.title.byMonth",
previousPeriod: "coach.result.title.previousPeriod",
yearAgo: "coach.result.title.yearAgo",
workoutsBySport: "coach.result.title.workoutsBySport",
labsLatest: "coach.result.title.labsLatest",
sleepByNight: "coach.result.title.sleepByNight",
complianceByDay: "coach.result.title.complianceByDay",
distribution: "coach.result.title.distribution",
} as const;
/** Column headings. */
export const COACH_RESULT_COLUMN_KEYS = {
day: "coach.result.column.day",
week: "coach.result.column.week",
month: "coach.result.column.month",
night: "coach.result.column.night",
sport: "coach.result.column.sport",
sessions: "coach.result.column.sessions",
analyte: "coach.result.column.analyte",
value: "coach.result.column.value",
unit: "coach.result.column.unit",
date: "coach.result.column.date",
referenceRange: "coach.result.column.referenceRange",
systolic: "coach.result.column.systolic",
diastolic: "coach.result.column.diastolic",
mean: "coach.result.column.mean",
min: "coach.result.column.min",
max: "coach.result.column.max",
readings: "coach.result.column.readings",
rate: "coach.result.column.rate",
duration: "coach.result.column.duration",
range: "coach.result.column.range",
count: "coach.result.column.count",
} as const;
/** The table's own chrome: paging, copy, the chart/table toggle, notices. */
export const COACH_RESULT_UI_KEYS = {
other: "coach.result.other",
noReading: "coach.result.noReading",
showAll: "coach.result.showAll",
showFewer: "coach.result.showFewer",
copyMenu: "coach.result.copyMenu",
copyForSpreadsheet: "coach.result.copyForSpreadsheet",
copyAsText: "coach.result.copyAsText",
copied: "coach.result.copied",
copyFailed: "coach.result.copyFailed",
viewLabel: "coach.result.viewLabel",
viewChart: "coach.result.viewChart",
viewTable: "coach.result.viewTable",
chartSummary: "coach.result.chartSummary",
dataUsed: "coach.result.dataUsed",
truncated: "coach.result.truncated",
loading: "coach.result.loading",
loadFailed: "coach.result.loadFailed",
histogramBin: "coach.result.histogramBin",
} as const;
/** Why a stored table is not shown. */
export const COACH_RESULT_WITHHELD_KEYS = {
module_disabled: "coach.result.withheld.moduleDisabled",
unavailable: "coach.result.withheld.unavailable",
} as const;
// ── Method ────────────────────────────────────────────────────────────────
export const COACH_METHOD_KEYS = {
label: "coach.method.label",
entry: "coach.method.entry",
entryNoWindow: "coach.method.entryNoWindow",
} as const;
/** "N readings" in the method line, by plural tier. */
export function methodReadingsKey(count: number, locale: Locale): string {
return pluralKey("coach.method.readings", count, locale);
}
export const COACH_METHOD_AGGREGATION_KEYS: Readonly<
Record<NonNullable<CoachMethodEntry["aggregation"]>, string>
> = {
mean: "coach.method.aggregation.mean",
median: "coach.method.aggregation.median",
latest: "coach.method.aggregation.latest",
sum: "coach.method.aggregation.sum",
count: "coach.method.aggregation.count",
rate: "coach.method.aggregation.rate",
};
/** "weekly averages" and "weekly totals", by granularity. */
export function methodAveragesKey(granularity: CoachResultGranularity): string {
return `coach.method.averages.${granularity}`;
}
export function methodTotalsKey(granularity: CoachResultGranularity): string {
return `coach.method.totals.${granularity}`;
}
export const COACH_METHOD_ABSENT_KEYS: Readonly<
Record<NonNullable<CoachMethodEntry["absent"]>, string>
> = {
no_data: "coach.method.absent.noData",
outside_window: "coach.method.absent.outsideWindow",
module_disabled: "coach.method.absent.moduleDisabled",
};
// ── Follow-ups ────────────────────────────────────────────────────────────
/** One label per chip kind; `{metric}` on a related-metric chip. */
export const COACH_FOLLOW_UP_KEYS: Readonly<Record<CoachFollowUpKind, string>> =
{
widen_window: "coach.followUp.widenWindow",
previous_period: "coach.followUp.previousPeriod",
year_ago: "coach.followUp.yearAgo",
as_chart: "coach.followUp.asChart",
as_table: "coach.followUp.asTable",
related_metric: "coach.followUp.relatedMetric",
continue: "coach.followUp.continue",
};
export const COACH_FOLLOW_UP_UI_KEYS = {
groupLabel: "coach.followUp.groupLabel",
settingLabel: "coach.followUp.settingLabel",
settingHint: "coach.followUp.settingHint",
} as const;
// ── Clarification ─────────────────────────────────────────────────────────
export const COACH_CLARIFY_UI_KEYS = {
cardLabel: "coach.clarify.cardLabel",
choicesLabel: "coach.clarify.choicesLabel",
freeTextHint: "coach.clarify.freeTextHint",
contextHint: "coach.clarify.contextHint",
} as const;
/** A window choice on a clarification card ("Last 30 days"). */
export function clarifyWindowLabelKey(window: CoachScopeWindow): string {
return `coach.clarify.window.${window}`;
}
// ── Reuse ─────────────────────────────────────────────────────────────────
/** The prose of a turn answered from a stored table without a model call. */
export const COACH_REUSE_CAPTION_KEY = "coach.reuse.caption";