fix(i18n): translate the platform packages' declared surface; gate all nine bundles, not one (#3762) (#3780)

Closes the fillable half of #3762. Follows #3370 → #3753 → #3768.

Nine packages own a translation bundle; ONE was wired into a drift check. The
other eight shipped a `scripts/i18n-extract.config.ts` that nothing ever ran,
and four had already drifted — plugin-security / plugin-audit / plugin-sharing
/ plugin-webhooks, 4 locales each out of date. Exactly the silent staleness
`pnpm check:i18n` exists to prevent, sitting one directory outside the only
path it guarded.

Translated: plugin-security (45 strings/locale), plugin-webhooks (15),
plugin-audit (8), plugin-sharing (7), service-storage (7) — 246 translations,
zero untranslated declared strings across zh-CN / ja-JP / es-ES. Most were
newly VISIBLE rather than newly missing: #3753 taught the coverage detector to
walk action `params`, `resultDialog`, `listViews`, object `description`, field
`help`/`placeholder`. Wording was harvested from the repo's own bundles first
(1382 unambiguous en→locale mappings scraped from what is already translated),
so `Created At` is `创建时间` here because that is what it is everywhere else;
only 59 strings had no precedent and were written by hand. Protocol tokens are
deliberately identical across locales: GET/POST/PUT/PATCH/DELETE, ETag, ACL,
URL.

`scripts/check-i18n-bundles.mjs` replaces the single-package `pnpm check:i18n`
and covers all nine (40 bundles). It does not restate each package's command —
it parses the regenerate command out of that config's own docstring and runs
exactly that, plus `--check`, so the documented command and the gate cannot
diverge. Same anti-drift principle as making the coverage detector share the
extractor's walker in #3753: one source, not two that agree today.

The #3768 coverage ratchet grows the same way, `examples/*` → twelve configs:
app-showcase / app-todo / app-crm at 456 / 212 / 97, platform-objects at 231,
and the other eight packages at 0 — meaning the ratchet IS the strict gate for
them, any regression immediately red rather than merely visible.

Both gates were verified to bite, not merely run: deleting a key block the
schema still declares reports DRIFTED and exits 1, restoring exits 0 (a
hand-edited translation correctly does NOT trip it — merge mode preserves it,
and the gate is about schema drift); the ratchet was proven in #3768 (97 → 99,
exit 1).

A real truncation bug this exposed: wiring the ratchet to platform-objects
failed on unparseable JSON whose output was exactly 65536 bytes — one pipe
buffer. `console.log(big)` followed by `process.exit(1)` tears the process down
before an async pipe write drains; interactively it looks perfect because
stdout to a TTY is synchronous, but piped — i.e. every scripted consumer — it
silently yields invalid JSON. `emitJson` (packages/cli/src/utils/format.ts)
awaits the write callback and sets `process.exitCode` instead; `lint`,
`i18n check` and `i18n extract` use it, and `os lint --json` on
platform-objects goes from 65536 truncated bytes to 234603 that parse. ~30
other CLI commands share the pattern and are NOT touched here — a mechanical
sweep that could not be verified command-by-command in this change. The ratchet
also captures to a file rather than a pipe regardless, since a gate that can
read a truncated payload and report a smaller number is worse than no gate.

The nine documented regenerate commands gain `--no-metadata-forms` (#3768) —
the Studio metadata-form baseline belongs to platform-objects alone, not a copy
in every plugin.

Not in scope: platform-objects' own 77-per-locale gap is `apps.*` /
`dashboards.*` navigation and widget labels, which live outside the `objects`
subtree, so the package's `--objects-only` extract cannot scaffold them — which
is why `--check` reports in sync while coverage reports 77 missing. That needs
an emit decision (drop `--objects-only`, or a companion `.apps.generated.ts`)
before any translating; it stays in #3762 and the 231 is frozen in the baseline
meanwhile. Also filed: #3778.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/i18n-translate-platform-bundles.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/plugin-security": patch
+"@objectstack/plugin-audit": patch
+"@objectstack/plugin-sharing": patch
+"@objectstack/plugin-webhooks": patch
+"@objectstack/service-storage": patch
+"@objectstack/cli": patch
+---
+
+fix(i18n): translate the platform packages' declared surface, and gate all nine bundles instead of one (#3762)
+
+Only `platform-objects` was wired into a translation-drift check. The other
+**eight** packages shipped a `scripts/i18n-extract.config.ts` that nothing ever
+ran — and four of them had already drifted out of sync with the schema, exactly
+the rot `pnpm check:i18n` exists to catch, one directory over.
+
+**Translated.** `plugin-security` (45 strings per locale), `plugin-webhooks`
+(15), `plugin-audit` (8), `plugin-sharing` (7) and `service-storage` (7) are now
+at **zero** untranslated declared strings in zh-CN / ja-JP / es-ES — 246
+translations. Most were newly *visible* rather than newly missing: #3753 taught
+the coverage detector to walk action `params`, `resultDialog`, `listViews` and
+the rest of the declared surface, and these are what it found.
+
+Wording was harvested from the repo's own bundles wherever a string was already
+translated somewhere (1382 unambiguous source strings), so `Created At` reads
+`创建时间` here because that is what it reads everywhere else, rather than a
+fresh invention. Protocol tokens are deliberately left identical across locales:
+`GET` / `POST` / `PUT` / `PATCH` / `DELETE`, `ETag`, `ACL`, `URL`.
+
+**Gated.** `scripts/check-i18n-bundles.mjs` replaces the single-package
+`pnpm check:i18n` and checks all nine. It does not restate each package's
+command — it parses the one already documented in that config's own docstring
+and runs it, so the documented regenerate command and the gate cannot diverge.
+The coverage ratchet grows the same way, from `examples/*` to twelve configs;
+eight of them sit at zero, which makes it the strict gate there.
+
+**Fixed a real truncation bug it exposed.** `os lint --json` on a large config
+came out of a pipe cut off at exactly 65536 bytes — `console.log(big)` followed
+by `process.exit(1)` tears the process down before an async pipe write drains,
+while an interactive run (stdout is a TTY, written synchronously) looks perfect.
+Every scripted consumer silently got invalid JSON. `emitJson` in
+`packages/cli/src/utils/format.ts` waits for the write to drain and sets
+`process.exitCode` instead; `lint`, `i18n check` and `i18n extract` use it.
+Roughly 30 other CLI commands share the pattern and are not touched here.
+
+The nine documented regenerate commands also gain `--no-metadata-forms` (added
+in #3768), since the Studio metadata-form baseline belongs to `platform-objects`
+alone, not to a copy in every plugin.
+
+Not fixed here: `platform-objects`' own 77-per-locale gap is `apps.*` /
+`dashboards.*` navigation and widget labels, which live outside the `objects`
+subtree and cannot be scaffolded while the package extracts with
+`--objects-only`. That needs an emit decision first — tracked in #3762.

.github/workflows/lint.yml

@@ -262,21 +262,30 @@ jobs:
       # mode, so it never asks anyone to re-translate: a fresh extract of an
       # up-to-date bundle is byte-identical to what is committed.
       #
-      # Reads the built @objectstack/spec dist through the extract config, so
+      # Now covers ALL NINE packages that own a bundle, not just
+      # platform-objects. The other eight shipped an `i18n-extract.config.ts`
+      # that nothing ever ran, and four of them had already drifted — the same
+      # rot this gate exists to catch, one directory over. Each package is
+      # checked with the exact command its own config docstring documents, so
+      # the docs and the gate cannot diverge.
+      #
+      # Reads the built @objectstack/spec dist through the extract configs, so
       # it belongs after the build step with the other consumer gates.
       - name: Check generated translation bundles are in sync with the schema
         run: pnpm check:i18n
 
       # Ratchet on the OTHER i18n question. The step above asks "are the
       # generated bundles still what the schema produces?"; this one asks "did
       # anyone declare a new label and not translate it?" — the gap #3370 closed
-      # in `os lint` but which had ~765 pre-existing misses across the examples,
-      # so `--i18n-strict` cannot simply be switched on without painting CI red
-      # and getting switched back off. The debt is frozen in
+      # in `os lint`, which had ~1000 pre-existing misses across the examples and
+      # platform-objects, so `--i18n-strict` cannot simply be switched on without
+      # painting CI red and getting switched back off. The debt is frozen in
       # scripts/i18n-coverage-baseline.json; growth fails the build.
       #
-      # Runs the built CLI over each example config, so it also belongs after
-      # the build step.
+      # Eight of the twelve tracked configs sit at zero, so for those this is
+      # already the strict gate — any regression is immediately red.
+      #
+      # Runs the built CLI over each config, so it also belongs after the build.
       - name: Check no new untranslated declared labels
         run: pnpm check:i18n-coverage
 

AGENTS.md

@@ -188,7 +188,7 @@ Root also exports: `defineStack`, `composeStacks`, `defineView`, `defineApp`, `d
 | Path | Type | Rule |
 |:---|:---|:---|
 | `content/docs/references/` | **AUTO-GEN** | ❌ Never hand-edit. Regenerated by `packages/spec/scripts/build-docs.ts`. |
-| `packages/platform-objects/src/apps/translations/*.generated.ts` | **AUTO-GEN** | ❌ Never hand-edit. Run `pnpm i18n:extract` (merge mode — existing translations are preserved). `pnpm check:i18n` gates it in CI. |
+| `**/translations/*.generated.ts` (nine packages — `platform-objects`, five plugins, three services) | **AUTO-GEN** | ❌ Never hand-edit the file *structure*. Run `node scripts/check-i18n-bundles.mjs --write` to regenerate all nine (merge mode — every existing translation is preserved); `pnpm i18n:extract` still covers `platform-objects` alone. Translation *values* are hand-written and expected to be: the gate compares against a merge-mode extract, so editing a string is fine, while adding or dropping keys is drift. `pnpm check:i18n` gates all nine in CI, and `pnpm check:i18n-coverage` ratchets untranslated declared labels. |
 | `content/docs/guides/` | hand-written | ✅ Update `meta.json` when adding pages. |
 | `content/docs/concepts/` | hand-written | ✅ |
 | `content/docs/getting-started/` | hand-written | ✅ |

package.json

@@ -27,7 +27,7 @@
     "objectui:clean": "rm -rf packages/console/dist .cache/objectui-*",
     "lint": "eslint . --no-inline-config",
     "i18n:extract": "tsx packages/cli/bin/run-dev.js i18n extract packages/platform-objects/scripts/i18n-extract.config.ts --locales=zh-CN,ja-JP,es-ES --fill=default --out=packages/platform-objects/src/apps/translations",
-    "check:i18n": "pnpm i18n:extract --check",
+    "check:i18n": "node scripts/check-i18n-bundles.mjs",
     "check:i18n-coverage": "node scripts/check-i18n-coverage.mjs",
     "check:nul-bytes": "node scripts/check-nul-bytes.mjs",
     "check:doc-authoring": "node scripts/check-doc-authoring.mjs",

packages/cli/src/commands/i18n/check.ts

@@ -12,6 +12,7 @@ import {
   printInfo,
   printStep,
   createTimer,
+  emitJson,
 } from '../../utils/format.js';
 import { computeI18nCoverage } from '../../utils/i18n-coverage.js';
 
@@ -77,12 +78,10 @@ export default class I18nCheck extends Command {
         : [];
 
       if (flags.json) {
-        console.log(JSON.stringify({
-          ...report,
-          thresholdViolations,
-          duration: timer.elapsed(),
-        }, null, 2));
-        if (report.totals.errors > 0 || thresholdViolations.length > 0) process.exit(1);
+        await emitJson(
+          { ...report, thresholdViolations, duration: timer.elapsed() },
+          report.totals.errors > 0 || thresholdViolations.length > 0 ? 1 : 0,
+        );
         return;
       }
 

packages/cli/src/commands/i18n/extract.ts

@@ -13,6 +13,7 @@ import {
   printInfo,
   printStep,
   createTimer,
+  emitJson,
 } from '../../utils/format.js';
 import { extractTranslations, renderTranslationModule, type FillStrategy } from '../../utils/i18n-extract.js';
 
@@ -159,15 +160,15 @@ export default class I18nExtract extends Command {
         flags['metadata-forms'] && (metadataFormsCounts[locale] ?? 0) > 0;
 
       if (flags.json) {
-        console.log(JSON.stringify({
+        await emitJson({
           totalExpected: result.totalExpected,
           counts: result.counts,
           metadataFormsCounts,
           bundles: objectsOnly
             ? Object.fromEntries(localesEmitted.map((l) => [l, result.bundles[l].objects ?? {}]))
             : result.bundles,
           duration: timer.elapsed(),
-        }, null, 2));
+        });
         return;
       }
 

packages/cli/src/commands/lint.ts

@@ -25,6 +25,7 @@ import {
   printInfo,
   printStep,
   createTimer,
+  emitJson,
 } from '../utils/format.js';
 
 // ─── Types ──────────────────────────────────────────────────────────
@@ -672,7 +673,7 @@ export default class Lint extends Command {
         const errors = issues.filter((i) => i.severity === 'error');
         const warnings = issues.filter((i) => i.severity === 'warning');
         const suggestions = issues.filter((i) => i.severity === 'suggestion');
-        console.log(JSON.stringify({
+        await emitJson({
           passed: errors.length === 0,
           total: issues.length,
           errors: errors.length,
@@ -682,8 +683,7 @@ export default class Lint extends Command {
           ...(score ? { score: score.score, grade: score.grade } : {}),
           issues,
           duration: timer.elapsed(),
-        }, null, 2));
-        if (errors.length > 0) process.exit(1);
+        }, errors.length > 0 ? 1 : 0);
         return;
       }
 

packages/cli/src/utils/format.ts

@@ -7,6 +7,31 @@ import type { ZodError } from 'zod';
 export const CLI_NAME = 'objectstack';
 export const CLI_ALIAS = 'os';
 
+// ─── Machine-readable output ────────────────────────────────────────
+
+/**
+ * Emit a `--json` payload and record the exit code, without truncating.
+ *
+ * `console.log(big)` followed by `process.exit(1)` looks correct and is not:
+ * when stdout is a **pipe**, Node buffers the write asynchronously and
+ * `process.exit` tears the process down with the buffer only partly drained.
+ * `os lint packages/platform-objects/scripts/i18n-extract.config.ts --json`
+ * came out of a pipe at exactly 65536 bytes — one pipe buffer — so every
+ * scripted consumer got invalid JSON while an interactive run (stdout is a TTY,
+ * written synchronously) looked perfect. Silent, and invisible to the author.
+ *
+ * Waiting for the write callback drains the buffer first, and setting
+ * `process.exitCode` instead of calling `process.exit` lets Node exit on its
+ * own once nothing is pending.
+ */
+export async function emitJson(payload: unknown, exitCode = 0): Promise<void> {
+  const text = JSON.stringify(payload, null, 2) + '\n';
+  await new Promise<void>((resolve, reject) => {
+    process.stdout.write(text, (err) => (err ? reject(err) : resolve()));
+  });
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+
 // ─── Banner ─────────────────────────────────────────────────────────
 
 export function printBanner(version: string) {

packages/plugins/plugin-audit/scripts/i18n-extract.config.ts

@@ -8,7 +8,7 @@
  * strings were seeded from @objectstack/platform-objects.)
  *
  *   os i18n extract packages/plugins/plugin-audit/scripts/i18n-extract.config.ts \
- *     --locales=zh-CN,ja-JP,es-ES --fill=default --objects-only \
+ *     --locales=zh-CN,ja-JP,es-ES --fill=default --objects-only --no-metadata-forms \
  *     --out=packages/plugins/plugin-audit/src/translations
  */
 

packages/plugins/plugin-audit/src/translations/en.objects.generated.ts

@@ -37,6 +37,10 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
         label: "Actor",
         help: "User who performed the action (null for system actions)"
       },
+      actor: {
+        label: "Actor",
+        help: "Principal that performed the action: a user id, svc:<name>, or null"
+      },
       object_name: {
         label: "Object",
         help: "Target object (e.g. sys_user, project_task)"
@@ -73,7 +77,11 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
     },
     _views: {
       recent: {
-        label: "Recent"
+        label: "Recent",
+        emptyState: {
+          title: "No audit events",
+          message: "Activity will appear here as users interact with the platform."
+        }
       },
       writes_only: {
         label: "Writes"
@@ -140,6 +148,14 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
         label: "Record Label",
         help: "Display label of the target record at write time"
       },
+      source_object: {
+        label: "Source Object",
+        help: "Object name of the rich source entity this activity was derived from (e.g. \"sys_email\"). Null when the activity is about the target record itself."
+      },
+      source_id: {
+        label: "Source ID",
+        help: "Record id of the rich source entity (paired with source_object) — lets the timeline drill to the full email/call/meeting record."
+      },
       url: {
         label: "URL",
         help: "Optional deep-link to the activity target"