feat(cli,spec): gate the whole declared surface for i18n; translate inline object actions (#3370) (#3753)

A zh-CN workspace localized the platform chrome but leaked English from
author-declared labels: the approval drawer rendered Approve / Reject /
Reassign beside the inbox's own 通过 / 拒绝. Two independent holes.

The lint gate could not see them. `os lint`'s coverage detector kept its own
walk of the metadata, separate from the walker `os i18n extract` uses to
scaffold bundles, and the two had drifted — coverage only walked the top-level
`actions` array, while `sys_approval_request` declares its decision actions
inline on the object. Those labels were extractable but ungated. Coverage now
derives its expected keys from `collectExpectedEntries()`, so the gated surface
and the scaffolded surface cannot disagree again. Newly gated: inline object
actions, action params and resultDialog copy, object-nested listViews, object
description, field help/placeholder, and apps/dashboards/pages. Extract output
is byte-identical against the committed plugin bundles.

It stays silent for projects that do not translate. `os lint`, `os i18n check`
and `os i18n extract` now read the stack's own `i18n.defaultLocale` /
`i18n.supportedLocales`, falling back to the locales a bundle already covers,
then to `en`. A project declaring neither is checked against its default locale
alone, which its inline labels already satisfy — zero issues. This also stops a
monolingual non-English project being told it owes `en` translations.

The server sent English regardless of locale. `translateObject` walked an
object's label/pluralLabel/description/fields but never its inline `actions`,
so the meta endpoint returned the authored literals even though
plugin-approvals ships `_actions` translations for all eight decision actions.
The Console compensated client-side; every other consumer rendered the source
language. Inline actions now run through `translateAction`.

Adds `os i18n extract --no-metadata-forms` so a package that owns only its own
objects stops being asked to commit the registry-driven Studio baseline, which
exactly one package should carry. Defaults to on: deriving it from
`--objects-only` instead took `pnpm check:i18n` from 8 bundles to 4 while still
reporting green, so the emit set is now pinned to the flags by a test.

Follow-up filed as #3762: platform-objects declares 55 inline actions across 12
objects with no objects translation bundle at all.

Author: os-zhuang

.changeset/i18n-gate-declared-labels.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/cli": minor
+"@objectstack/spec": patch
+---
+
+feat(cli,spec): gate the whole declared surface for i18n, and translate inline object actions server-side (#3370)
+
+In a zh-CN workspace the platform chrome was localized while author-declared
+labels leaked English — the approval drawer rendered **Approve / Reject /
+Reassign** right beside the inbox's own 通过 / 拒绝. Two independent holes, both
+closed here.
+
+**The lint gate could not see them.** `os lint`'s i18n coverage kept its own
+walk of the metadata, separate from the one `os i18n extract` uses to scaffold
+bundles, and the two had drifted: coverage only ever walked the *top-level*
+`actions` array, while `sys_approval_request` declares its decision actions
+**inline on the object**. Those labels were extractable but ungated, so an
+untranslated one could ship and no lint run would notice. Coverage now derives
+its expected keys from `collectExpectedEntries()` — the extractor's walker — so
+the gated surface and the scaffolded surface cannot disagree again. Newly gated
+as a result: inline object actions, action `params` and `resultDialog` copy,
+object-nested `listViews` (label / description / `emptyState`), object
+`description`, field `help` / `placeholder`, and the `apps` / `dashboards` /
+`pages` surfaces. Extract output is byte-identical — verified against the
+committed plugin bundles.
+
+**It stays silent for projects that do not translate.** Which locales get
+checked is the project's declaration, never an assumption: `os lint`,
+`os i18n check` and `os i18n extract` now read the stack's own
+`i18n.defaultLocale` / `i18n.supportedLocales`, falling back to the locales a
+bundle already exists for, and finally to `en`. A project with neither is
+checked against its default locale alone — which its inline labels already
+satisfy — so it reports zero i18n issues. That also fixes a monolingual
+*non-English* project being told it owed `en` translations it never claimed to
+speak. Locked by regression tests; the three bundled examples stay at 0 errors.
+
+**The server sent English regardless of locale.** `translateObject` walked an
+object's `label` / `pluralLabel` / `description` / `fields` but never its inline
+`actions`, so `GET /api/v1/meta/object/:name` returned the authored English
+literals even though `@objectstack/plugin-approvals` ships `_actions`
+translations for all eight decision actions in zh-CN / ja-JP / es-ES. The
+Console compensated by re-resolving labels client-side against a separately
+fetched bundle; every other consumer — mobile, plain HTTP, SDUI — rendered the
+source language. It now runs inline actions through `translateAction`, without
+stamping a synthetic `objectName` onto the response.
+
+Adds `os i18n extract --no-metadata-forms`. Whether the companion
+`<locale>.metadata-forms.generated.ts` file is written was previously implicit:
+every run emitted it, so `--check` demanded that file in packages that
+deliberately do not commit one. The Studio metadata-form baseline is
+registry-driven and identical for every stack, so exactly one package owns it
+(`platform-objects`); a plugin translating only its own objects now opts out,
+and its `--check` stops failing on a tree that is in sync. Defaults to emitting,
+so `pnpm check:i18n` keeps covering all 8 platform bundles.

content/docs/ui/translations.mdx

@@ -78,7 +78,11 @@ export default defineStack({
 
 The metadata types resolved per request are **object, view, action, app,
 dashboard, and page** — a field's labels are translated as part of its object
-document.
+document, and so are the labels of any actions the object declares inline
+(#3370). Before that, an object document went out with its authored action
+labels untouched: `sys_approval_request`'s Approve / Reject rendered in English
+in a zh-CN workspace for every consumer except the Console, which happened to
+re-resolve them client-side against its own copy of the bundle.
 
 <Callout type="info">
 **Page headers are keyed by page name (#3589).** A page's `page:header`
@@ -151,6 +155,27 @@ A missing string in the **default** locale is an error; missing strings in
 other locales are warnings until you set `--strict` / `--threshold`. The Todo
 example ships a completeness test alongside its bundles — worth copying.
 
+### Which locales get checked
+
+Your project decides, and the tooling never assumes. `os lint`, `os i18n check`
+and `os i18n extract` read the `i18n` block above — `supportedLocales` is the
+set they gate, `defaultLocale` the one that must be complete. Without that
+block they fall back to whatever locales your bundles already cover, and
+finally to `en`.
+
+The consequence worth stating plainly: **a project that does not do i18n
+reports nothing.** No `i18n` block and no bundles means one active locale, the
+default one, and your inline `label:` is already that locale's text — so there
+is no gap to report and no need to reach for `--skip-i18n`. The same holds if
+your source language isn't English: declare `defaultLocale: 'zh-CN'` and the
+tooling stops asking for English you never promised.
+
+Translating is therefore opt-in, but once you opt in it covers the **whole**
+declared surface — every row of the table above, including action labels
+declared inline on an object. That surface used to be narrower than what
+`os i18n extract` would scaffold, which is how untranslated approval buttons
+shipped without any lint noticing (#3370).
+
 The two gates answer different questions, and you want both. `os i18n check`
 asks *are the strings translated?* — a coverage number about human work.
 `os i18n extract --check` asks *are the generated bundles still what the schema

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

@@ -34,11 +34,12 @@ export default class I18nCheck extends Command {
   static override flags = {
     json: Flags.boolean({ description: 'Output as JSON' }),
     'default-locale': Flags.string({
-      description: 'Locale that must be 100% translated (errors raised against it)',
-      default: 'en',
+      description:
+        "Locale that must be 100% translated (errors raised against it). Defaults to the config's i18n.defaultLocale, else 'en'.",
     }),
     locales: Flags.string({
-      description: 'Comma-separated list of locales to check (default: every locale found)',
+      description:
+        'Comma-separated list of locales to check (default: the config\'s i18n.supportedLocales, else every locale found)',
     }),
     strict: Flags.boolean({
       description: 'Treat missing keys in non-default locales as errors (CI parity gate)',

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

@@ -55,11 +55,11 @@ export default class I18nExtract extends Command {
   static override flags = {
     json: Flags.boolean({ description: 'Output JSON instead of writing files' }),
     'default-locale': Flags.string({
-      description: 'Locale filled from schema labels',
-      default: 'en',
+      description: "Locale filled from schema labels. Defaults to the config's i18n.defaultLocale, else 'en'.",
     }),
     locales: Flags.string({
-      description: 'Comma-separated list of locales to emit (always includes default-locale)',
+      description:
+        "Comma-separated list of locales to emit (always includes default-locale). Defaults to the config's i18n.supportedLocales.",
     }),
     fill: Flags.string({
       description: 'How non-default locales are filled: empty | default | todo',
@@ -81,6 +81,12 @@ export default class I18nExtract extends Command {
       default: true,
       allowNo: true,
     }),
+    'metadata-forms': Flags.boolean({
+      description:
+        'Also write <locale>.metadata-forms.generated.ts for the Studio metadata-form baseline (default). Pass --no-metadata-forms in a package that owns only its own objects — that baseline belongs to one package, not every plugin.',
+      default: true,
+      allowNo: true,
+    }),
     'dry-run': Flags.boolean({
       description: 'Print to stdout instead of writing to --out',
       default: false,
@@ -106,12 +112,25 @@ export default class I18nExtract extends Command {
 
       const normalized = normalizeStackInput(config as Record<string, unknown>);
       const filter = flags.filter ? new RegExp(flags.filter) : undefined;
+      // The stack's own `i18n` block already names the languages it ships, so
+      // scaffolding those by default saves repeating them on every invocation.
+      const declared = (normalized as { i18n?: { defaultLocale?: unknown; supportedLocales?: unknown } }).i18n;
+      const declaredLocales = Array.isArray(declared?.supportedLocales)
+        ? declared.supportedLocales.filter((l): l is string => typeof l === 'string' && l.length > 0)
+        : [];
       const locales = flags.locales
         ? flags.locales.split(',').map((s) => s.trim()).filter(Boolean)
-        : undefined;
+        : declaredLocales.length > 0
+          ? declaredLocales
+          : undefined;
+      const defaultLocale =
+        flags['default-locale'] ??
+        (typeof declared?.defaultLocale === 'string' && declared.defaultLocale.length > 0
+          ? declared.defaultLocale
+          : 'en');
 
       const result = extractTranslations(normalized, {
-        defaultLocale: flags['default-locale'],
+        defaultLocale,
         locales,
         fill: flags.fill as FillStrategy,
         filter,
@@ -128,6 +147,16 @@ export default class I18nExtract extends Command {
         metadataFormsCounts[locale] = countLeaves(result.bundles[locale]?.metadataForms);
       }
       const anyMetadataForms = Object.values(metadataFormsCounts).some((n) => n > 0);
+      // Whether the companion `<locale>.metadata-forms.generated.ts` file is
+      // written is its own question, orthogonal to `--objects-only` (which only
+      // picks the sub-tree of the *objects* module). The Studio metadata-form
+      // baseline is registry-driven and identical for every stack, so exactly
+      // one package should own it — `platform-objects` does. A plugin that owns
+      // only its own objects passes `--no-metadata-forms`; without it, `--check`
+      // demands a baseline copy the package deliberately does not commit and
+      // fails on a tree that is in fact in sync.
+      const emitsMetadataForms = (locale: string): boolean =>
+        flags['metadata-forms'] && (metadataFormsCounts[locale] ?? 0) > 0;
 
       if (flags.json) {
         console.log(JSON.stringify({
@@ -169,7 +198,7 @@ export default class I18nExtract extends Command {
             locale,
             objectsOnly,
           }));
-          if (metadataFormsCounts[locale] > 0) {
+          if (emitsMetadataForms(locale)) {
             console.log(chalk.dim(`── ${locale} (metadataForms) ──`));
             console.log(renderTranslationModule(result.bundles[locale], {
               locale,
@@ -195,7 +224,7 @@ export default class I18nExtract extends Command {
             keys: result.counts[locale],
           });
         }
-        if (metadataFormsCounts[locale] > 0) {
+        if (emitsMetadataForms(locale)) {
           emitted.push({
             file: path.join(outDir, `${locale}.metadata-forms.generated.ts`),
             content: renderTranslationModule(result.bundles[locale], { locale, kind: 'metadataForms' }),
@@ -222,7 +251,7 @@ export default class I18nExtract extends Command {
         console.log('');
         printError(
           'Translation bundles have drifted from the schema. Regenerate and commit:\n' +
-          `  os i18n extract ${args.config ?? ''} --locales=${localesEmitted.filter((l) => l !== flags['default-locale']).join(',')} ` +
+          `  os i18n extract ${args.config ?? ''} --locales=${localesEmitted.filter((l) => l !== defaultLocale).join(',')} ` +
           `--fill=${flags.fill} --out=${flags.out}`.replace(/\s+/g, ' '),
         );
         process.exit(1);

packages/cli/src/commands/lint.ts

@@ -604,8 +604,8 @@ export default class Lint extends Command {
       description: 'Treat missing translations in non-default locales as errors',
     }),
     'default-locale': Flags.string({
-      description: 'Default locale for i18n coverage (must be 100% translated)',
-      default: 'en',
+      description:
+        "Default locale for i18n coverage (must be 100% translated). Defaults to the config's i18n.defaultLocale, else 'en'.",
     }),
   };
 
@@ -645,6 +645,11 @@ export default class Lint extends Command {
       }
 
       // ── Translation coverage ──
+      // No locale is forced here: `computeI18nCoverage` falls back to the
+      // stack's own `i18n` block and, failing that, to the locales its bundles
+      // already cover. A project that ships neither is checked against its
+      // default locale alone, which its inline labels already satisfy — so this
+      // stays silent for projects that do not translate.
       let hiddenPlatform = 0;
       if (!flags['skip-i18n']) {
         const coverage = computeI18nCoverage(normalized, {