fix(spec,objectql,rest,runtime): localize field-validation messages, name the field by its label (#3957)

.changeset/localized-field-validation-messages.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/rest": minor
+"@objectstack/runtime": patch
+---
+
+fix(spec,objectql,rest,runtime): field-validation messages answer in the caller's language, named by the field's label (#3957)
+
+The write path built every built-in validation message by concatenating the **API
+field name** into a **hardcoded English** template. Those strings are what the
+Console toast, the CSV-import row report, the CLI and any custom client display
+verbatim, so a Chinese-locale user importing a bad row read:
+
+```
+第 1 行:penalty_amount must be ≥ 0
+```
+
+…for a field declared `label: '处罚金额'` with a full `zh-CN` bundle loaded. The
+form layer localized the *same* constraint correctly (the browser's native
+`min`), so the language flipped depending on which layer caught the value.
+
+**Three things changed.**
+
+1. **The message is rendered in the caller's locale** from a built-in catalog
+ (`BUILTIN_VALIDATION_MESSAGES`, `@objectstack/spec/system`) shipping `en`,
+ `zh-CN`, `ja-JP`, `es-ES` — the same four locales as the platform bundles.
+ The locale comes from `ExecutionContext.locale`, whose contract already read
+ "Drives message catalogs"; this is the consumer that makes that true. Both
+ HTTP entries (REST server, runtime dispatcher) now resolve it from the
+ request's `Accept-Language` / `?locale` first, falling back to the workspace
+ `localization.locale` — so a rejection message and the field labels around it
+ can no longer disagree.
+
+2. **The field is named by its label, never the API name**: translation bundle
+ (`objects.<obj>.fields.<f>.label`) → declared `label` → API name as the last
+ resort. `FieldValidationError.field` still carries the API name so a form can
+ focus the right input.
+
+3. **The constraint is exposed as data**, so a client can format its own text
+ instead of parsing the sentence:
+ `{ field, code, message, label, constraint: { min: 0 } }`. This rides
+ ADR-0114's existing `constraint` / `value` positions on `FieldErrorSchema`
+ (`constraint` tightens from `unknown` to `Record<string, unknown>`) rather
+ than adding a parallel payload — `label` is the only new field. The bag
+ carries `min`/`max`/`minLength`/`maxLength`/`actual`/`allowed`/`type`, and the
+ message templates interpolate from exactly those keys.
+
+Covered end-to-end, not only in the validator: single and batch insert,
+single-id and multi-row update, ADR-0113's clear-out rejection, the object-level
+rule evaluator's own built-in messages (`requiredWhen`, per-option gating,
+state-machine fallbacks), and the importer's cell-coercion, required pre-check
+and #3956 bound pre-check messages — all of which land in the same row report.
+
+**What this changes for consumers.**
+
+- `code` is unchanged (ADR-0114's `FieldErrorCode`) and remains the thing to
+ match on. Message keys are finer-grained than codes — `invalid_datetime`,
+ `invalid_option_value`, `required_cleared` are rendering detail and never reach
+ the wire — so localization never splits the client-facing vocabulary.
+- `message` **text changes**: it is localized, and it names the field by label
+ even in English (`Budget must be ≥ 0`, not `budget must be ≥ 0`). Anything
+ asserting on the old English string should match `code` (and now
+ `constraint`) instead.
+- An author-written validation-rule `message` is never touched — it is already
+ in the language its author chose.
+- A deployment can override any built-in message with a `translation` item
+ defining `validation.field.<messageKey>` (e.g.
+ `validation.field.min_value: '{{label}}不得小于 {{min}} 元'`).
+- The importer's reference-failure message no longer names the target object's
+ API name (`no sys_user matches "…"`): naming internal identifiers is the
+ defect being fixed, and the column plus the offending value are what an
+ importer can act on.

content/docs/references/api/errors.mdx

@@ -53,7 +53,7 @@ const result = EnhancedApiError.parse(data);
 | **retryStrategy** | `Enum<'no_retry' \| 'retry_immediate' \| 'retry_backoff' \| 'retry_after'>` | optional | Recommended retry strategy |
 | **retryAfter** | `number` | optional | Seconds to wait before retrying |
 | **details** | `any` | optional | Additional error context |
-| **fields** | `{ field: string; code: Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| 'invalid_url' \| 'invalid_phone' \| 'invalid_json' \| 'invalid_format' \| 'min_length' \| 'max_length' \| 'min_value' \| 'max_value' \| 'min_items' \| 'max_items' \| 'invalid_option' \| 'invalid_value' \| 'reference_not_found' \| 'reference_ambiguous' \| 'rule_violation' \| 'json_schema_violation' \| 'invalid_initial_state' \| 'invalid_transition'>; message: string; value?: any; … }[]` | optional | One entry per offending value |
+| **fields** | `{ field: string; code: Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| 'invalid_url' \| 'invalid_phone' \| 'invalid_json' \| 'invalid_format' \| 'min_length' \| 'max_length' \| 'min_value' \| 'max_value' \| 'min_items' \| 'max_items' \| 'invalid_option' \| 'invalid_value' \| 'reference_not_found' \| 'reference_ambiguous' \| 'rule_violation' \| 'json_schema_violation' \| 'invalid_initial_state' \| 'invalid_transition'>; message: string; label?: string; … }[]` | optional | One entry per offending value |
 | **fieldErrors** | `any` | optional | [REMOVED] `EnhancedApiError.fieldErrors` was renamed to `fields` in @objectstack/spec 17 (ADR-0114 D4, #3977) — the array is unchanged, only the property name. Every producer already emitted `fields`; `fieldErrors` was declared and never emitted, so a reader keying on it was reading a field no server sent. |
 | **timestamp** | `string` | optional | When the error occurred |
 | **requestId** | `string` | optional | Request ID for tracking |
@@ -102,9 +102,10 @@ const result = EnhancedApiError.parse(data);
 | :--- | :--- | :--- | :--- |
 | **field** | `string` | ✅ | Field path (supports dot notation) |
 | **code** | `Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| 'invalid_url' \| 'invalid_phone' \| 'invalid_json' \| 'invalid_format' \| 'min_length' \| 'max_length' \| 'min_value' \| 'max_value' \| 'min_items' \| 'max_items' \| 'invalid_option' \| 'invalid_value' \| 'reference_not_found' \| 'reference_ambiguous' \| 'rule_violation' \| 'json_schema_violation' \| 'invalid_initial_state' \| 'invalid_transition'>` | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
-| **message** | `string` | ✅ | Human-readable error message |
+| **message** | `string` | ✅ | Human-readable error message, rendered in the caller’s locale |
+| **label** | `string` | optional | Field display label in the caller’s locale |
 | **value** | `any` | optional | The invalid value that was provided |
-| **constraint** | `any` | optional | The constraint that was violated(e.g., max length) |
+| **constraint** | `Record<string, any>` | optional | The constraint that was violated, as discrete values (e.g. `{ maxLength: 512, actual: 3000 }`) |
 
 
 ---

packages/objectql/src/engine-validation-locale.test.ts

@@ -0,0 +1,200 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ObjectQL } from './engine';
+import { SchemaRegistry } from './registry';
+
+/**
+ * #3957 — the CALL SITE, not the catalog.
+ *
+ * `record-validator.ts` can localize perfectly and still ship English if the
+ * engine never hands it a locale. `ExecutionContext.locale` has carried the
+ * contract "Drives message catalogs and number/date formatting" since ADR-0053
+ * Phase 2 with no consumer — declared ≠ enforced (AGENTS.md PD #10). These
+ * tests assert on what a caller actually gets back from `ql.insert` /
+ * `ql.update`, for every write shape the engine validates: single insert, batch
+ * insert, single-id update, and multi-row update.
+ */
+vi.mock('./registry', () => {
+ const instance: any = {
+ getObject: vi.fn(),
+ resolveObject: vi.fn((n: string) => instance.getObject(n)),
+ registerObject: vi.fn(),
+ getObjectOwner: vi.fn(),
+ registerNamespace: vi.fn(),
+ registerKind: vi.fn(),
+ registerItem: vi.fn(),
+ registerApp: vi.fn(),
+ installPackage: vi.fn(),
+ reset: vi.fn(),
+ metadata: { get: vi.fn(() => new Map()) },
+ };
+ function SchemaRegistry() {
+ return instance;
+ }
+ Object.assign(SchemaRegistry, instance);
+ return {
+ SchemaRegistry,
+ computeFQN: (_ns: string | undefined, name: string) => name,
+ parseFQN: (fqn: string) => ({ namespace: undefined, shortName: fqn }),
+ RESERVED_NAMESPACES: new Set(['base', 'system']),
+ };
+});
+
+// The reporting object from the issue: Chinese labels, range-guarded currency.
+const SETTLEMENT_SCHEMA = {
+ name: 'mes_settlement',
+ fields: {
+ name: { type: 'text', label: '名称' },
+ penalty_amount: { type: 'currency', label: '处罚金额', min: 0 },
+ quota_hours: { type: 'number', label: '定额工时', min: 0 },
+ },
+};
+
+function makeDriver() {
+ const driver: any = {
+ name: 'memory',
+ supports: {},
+ connect: vi.fn().mockResolvedValue(undefined),
+ disconnect: vi.fn().mockResolvedValue(undefined),
+ find: vi.fn().mockResolvedValue([{ id: 'r1' }, { id: 'r2' }]),
+ findOne: vi.fn().mockResolvedValue({ id: 'r1' }),
+ create: vi.fn(async (_o: string, row: any) => ({ id: 'r1', ...row })),
+ update: vi.fn(async (_o: string, id: string, row: any) => ({ id, ...row })),
+ updateMany: vi.fn(async () => 2),
+ delete: vi.fn(),
+ };
+ return driver;
+}
+
+async function makeEngine(driver: any) {
+ vi.mocked((SchemaRegistry as any).getObject).mockImplementation((name: string) =>
+ name === 'mes_settlement' ? SETTLEMENT_SCHEMA : undefined,
+ );
+ const ql = new ObjectQL();
+ ql.registerDriver(driver, true);
+ await ql.init();
+ return ql;
+}
+
+/** The message a write attempt fails with. */
+async function messageOf(run: () => Promise<unknown>): Promise<string> {
+ try {
+ await run();
+ } catch (e: any) {
+ return String(e?.message ?? '');
+ }
+ throw new Error('expected the write to be rejected');
+}
+
+const zhCN = { locale: 'zh-CN' } as any;
+
+describe('engine write path — validation messages honour ExecutionContext.locale (#3957)', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('single insert: a zh-CN principal reads Chinese', async () => {
+ const ql = await makeEngine(makeDriver());
+ const msg = await messageOf(() =>
+ ql.insert('mes_settlement', { name: 'S1', penalty_amount: -1 }, { context: zhCN }),
+ );
+ expect(msg).toBe('处罚金额必须大于或等于 0');
+ expect(msg).not.toContain('penalty_amount');
+ });
+
+ it('batch insert: each rejected row is localized', async () => {
+ const ql = await makeEngine(makeDriver());
+ const msg = await messageOf(() =>
+ ql.insert(
+ 'mes_settlement',
+ [{ name: 'ok', penalty_amount: 1 }, { name: 'bad', penalty_amount: -1 }],
+ { context: zhCN },
+ ),
+ );
+ expect(msg).toBe('处罚金额必须大于或等于 0');
+ });
+
+ it('single-id update: localized', async () => {
+ const ql = await makeEngine(makeDriver());
+ const msg = await messageOf(() =>
+ ql.update('mes_settlement', { id: 'r1', quota_hours: -3 }, { context: zhCN }),
+ );
+ expect(msg).toBe('定额工时必须大于或等于 0');
+ });
+
+ it('multi-row update: localized (the bulk call site, cf. #3106)', async () => {
+ const driver = makeDriver();
+ const ql = await makeEngine(driver);
+ const msg = await messageOf(() =>
+ ql.update(
+ 'mes_settlement',
+ { quota_hours: -3 },
+ { multi: true, filters: [['name', '=', 'S1']], context: zhCN } as any,
+ ),
+ );
+ expect(msg).toBe('定额工时必须大于或等于 0');
+ // The write never reached storage.
+ expect(driver.updateMany).not.toHaveBeenCalled();
+ });
+
+ /**
+ * No principal locale (a system write, a programmatic call, an anonymous
+ * request) keeps the pre-#3957 English rendering — now against the declared
+ * label instead of the API name.
+ */
+ it('no locale: English, and still the label rather than the column name', async () => {
+ const ql = await makeEngine(makeDriver());
+ const msg = await messageOf(() =>
+ ql.insert('mes_settlement', { name: 'S1', penalty_amount: -1 }),
+ );
+ expect(msg).toBe('处罚金额 must be ≥ 0');
+ });
+
+ /**
+ * An app whose metadata is authored in English but shipped with a `zh-CN`
+ * bundle: the bridged i18n service supplies the translated label.
+ */
+ it('uses the bridged i18n service for the field label and message overrides', async () => {
+ vi.mocked((SchemaRegistry as any).getObject).mockImplementation((name: string) =>
+ name === 'mes_settlement'
+ ? {
+ name: 'mes_settlement',
+ fields: { penalty_amount: { type: 'currency', label: 'Penalty Amount', min: 0 } },
+ }
+ : undefined,
+ );
+ const ql = new ObjectQL();
+ ql.registerDriver(makeDriver(), true);
+ await ql.init();
+ ql.setI18nService({
+ t: (key: string, locale: string) => {
+ if (key === 'objects.mes_settlement.fields.penalty_amount.label' && locale === 'zh-CN') return '处罚金额';
+ if (key === 'validation.field.min_value' && locale === 'zh-CN') return '{{label}}不得小于 {{min}} 元';
+ return key;
+ },
+ });
+ const msg = await messageOf(() =>
+ ql.insert('mes_settlement', { penalty_amount: -1 }, { context: zhCN }),
+ );
+ expect(msg).toBe('处罚金额不得小于 0 元');
+ });
+
+ it('a client can format its own text from code + constraint', async () => {
+ const ql = await makeEngine(makeDriver());
+ try {
+ await ql.insert('mes_settlement', { penalty_amount: -1 }, { context: zhCN });
+ throw new Error('expected the write to be rejected');
+ } catch (e: any) {
+ expect(e.code).toBe('VALIDATION_FAILED');
+ expect(e.fields).toEqual([
+ expect.objectContaining({
+ field: 'penalty_amount',
+ code: 'min_value',
+ label: '处罚金额',
+ constraint: { min: 0 },
+ }),
+ ]);
+ }
+ });
+});