feat(spec): resolve page metadata i18n — page:header title/subtitle (#3589)

Custom system pages authored as metadata (Installed Apps, Cloud Connection,
Connect an Agent) hard-code their `page:header` copy in `properties.title` /
`properties.subtitle`. Every other metadata type is localized at the REST
boundary, but `page` was not, so those headers stayed English in every locale
while the matching nav labels translated correctly.

The `pages` namespace existed only on `AppTranslationBundleSchema` — a schema
no runtime reads — with no resolver behind it. This wires the read side and
the schema together rather than adding another namespace nothing consumes.

- `TranslationDataSchema` (the shape the i18n service actually serves) gains
  `pages.<name>.{label,description,title,subtitle}`.
- `translatePage` translates a page's own label/description and overlays
  title/subtitle onto every `page:header` in its regions; registered in
  `translateMetadataDocument` so it rides the existing read path.
- `page` added to the REST boundary's TRANSLATABLE_META_TYPES. Locale
  extraction, the locale-keyed ETag and `Vary: Accept-Language` already
  covered every metadata type, so there is no new plumbing.
- `objectstack i18n extract` emits page entries, so the new namespace is not
  invisible to the tooling.
- zh-CN / ja-JP / es-ES copy for the three Setup pages, plus the missing
  `nav_cloud_connection` / `nav_connect_agent` labels (zh-CN-only until now).

Header copy is keyed by page name, not component id: `page:header` instances
carry no stable id. `title` falls back to `pages.<name>.label`, since a page's
header title and its nav label are normally the same string.

English literals stay in metadata as the fallback — a page with no `pages`
entry renders exactly as before — and the console needs no change, since
pages arrive already localized from the server.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TubWYdWquVkS9dj733sDmC

Author: claude

.changeset/page-header-i18n-3589.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": minor
+"@objectstack/platform-objects": minor
+"@objectstack/cli": minor
+"@objectstack/rest": patch
+---
+
+feat(spec): resolve page metadata i18n — `page:header` title/subtitle (#3589)
+
+Custom system pages authored as metadata (Installed Apps, Cloud Connection,
+Connect an Agent) hard-code their `page:header` copy in
+`properties.title` / `properties.subtitle`. Every other metadata type is
+localized at the REST boundary, but `page` was not: the `pages` namespace
+existed only on `AppTranslationBundleSchema` — a schema no runtime reads —
+with no resolver behind it, so those headers stayed English in every locale
+while the matching nav labels translated correctly.
+
+- `TranslationDataSchema` (the shape the i18n service actually serves) gains a
+  `pages` namespace: `pages.<name>.{label,description,title,subtitle}`.
+- New `translatePage` in `@objectstack/spec/system` translates a page's own
+  `label` / `description` and overlays `title` / `subtitle` onto every
+  `page:header` in the page's regions. Registered in
+  `translateMetadataDocument`, so it rides the existing read path.
+- `page` added to the REST boundary's `TRANSLATABLE_META_TYPES`. Locale
+  extraction, the locale-keyed ETag, and `Vary: Accept-Language` already
+  covered every metadata type — no new plumbing.
+- `objectstack i18n extract` now emits page entries, including the
+  `page:header` copy, so the new namespace is not invisible to the tooling.
+- zh-CN / ja-JP / es-ES translations shipped for the three Setup pages, plus
+  the missing `nav_cloud_connection` / `nav_connect_agent` nav labels (these
+  existed only in zh-CN).
+
+Header copy is keyed by **page name**, not by component id: `page:header`
+instances carry no stable id. `title` falls back to `pages.<name>.label`, since
+a page's header title and its nav label are normally the same string.
+
+Authoring is unchanged and English literals stay in metadata as the fallback —
+a page with no `pages` entry renders exactly as before. Consumers of
+`@object-ui` need no change: pages arrive already localized from the server.

packages/cli/src/utils/i18n-extract.ts

@@ -35,6 +35,8 @@
  *   apps.<app>.navigation.<id>.label
  *   dashboards.<dash>.label / .description
  *   dashboards.<dash>.widgets.<w>.title / .description
+ *   pages.<page>.label / .description
+ *   pages.<page>.title / .subtitle   (from the page's `page:header` component)
  *   metadataForms.<type>.label / .description
  *   metadataForms.<type>.sections.<section>.label / .description
  *   metadataForms.<type>.fields.<dotPath>.label / .helpText / .placeholder
@@ -72,6 +74,7 @@ export interface ExpectedEntry {
     | 'navigation'
     | 'dashboard'
     | 'widget'
+    | 'page'
     | 'metadataType'
     | 'metadataFormSection'
     | 'metadataFormField';
@@ -396,6 +399,36 @@ export function collectExpectedEntries(config: any): ExpectedEntry[] {
     }
   }
 
+  // ── Pages + their `page:header` copy ──────────────────────────────
+  const pages: any[] = Array.isArray(config?.pages) ? config.pages : [];
+  for (const page of pages) {
+    if (!page?.name) continue;
+    const name = page.name as string;
+    if (page.label) pushEntry(out, ['pages', name, 'label'], page.label, 'page');
+    if (page.description) {
+      pushEntry(out, ['pages', name, 'description'], page.description, 'page');
+    }
+    // Header copy is authored inside the page's `page:header` component but
+    // is addressed by page name — `translatePage` overlays it back onto every
+    // header in the page's regions.
+    const regions: any[] = Array.isArray(page.regions) ? page.regions : [];
+    for (const region of regions) {
+      const components: any[] = Array.isArray(region?.components) ? region.components : [];
+      for (const component of components) {
+        if (component?.type !== 'page:header') continue;
+        const props = component.properties ?? {};
+        // `title` duplicating `label` is the common case and resolves via the
+        // label fallback — only emit it when the two genuinely differ.
+        if (typeof props.title === 'string' && props.title && props.title !== page.label) {
+          pushEntry(out, ['pages', name, 'title'], props.title, 'page');
+        }
+        if (typeof props.subtitle === 'string' && props.subtitle) {
+          pushEntry(out, ['pages', name, 'subtitle'], props.subtitle, 'page');
+        }
+      }
+    }
+  }
+
   // ── Metadata configuration forms (Studio admin UI) ────────────────
   // Registry-driven: always included, independent of stack config. These
   // emit under `metadataForms.<type>.*` so the generic renderer can pick

packages/cli/test/i18n-extract.test.ts

@@ -171,6 +171,61 @@ describe('collectExpectedEntries', () => {
     // Fields without a label emit nothing.
     expect(byPath[`${base}.fields.unlabeled`]).toBeUndefined();
   });
+
+  it('walks pages and their page:header copy (objectstack#3589)', () => {
+    const pageConfig: any = {
+      pages: [
+        {
+          name: 'connect_agent',
+          label: 'Connect an Agent',
+          description: 'Agent onboarding',
+          regions: [
+            {
+              name: 'header',
+              components: [
+                {
+                  type: 'page:header',
+                  // `title` duplicates `label` — resolved by the label
+                  // fallback, so it must NOT emit its own entry.
+                  properties: { title: 'Connect an Agent', subtitle: 'Governed MCP access.', icon: 'bot' },
+                },
+              ],
+            },
+            { name: 'main', components: [{ type: 'mcp:connect-agent', properties: {} }] },
+          ],
+        },
+        {
+          name: 'renamed_header',
+          label: 'Nav Label',
+          regions: [
+            { name: 'header', components: [{ type: 'page:header', properties: { title: 'Different Title' } }] },
+          ],
+        },
+        { name: 'bare_page', label: 'Bare' },
+      ],
+    };
+    const entries = collectExpectedEntries(pageConfig);
+    const byPath = Object.fromEntries(entries.map((e) => [e.path.join('.'), e.sourceValue]));
+
+    expect(byPath['pages.connect_agent.label']).toBe('Connect an Agent');
+    expect(byPath['pages.connect_agent.description']).toBe('Agent onboarding');
+    expect(byPath['pages.connect_agent.subtitle']).toBe('Governed MCP access.');
+    // title === label → no redundant entry for translators to fill twice.
+    expect(byPath['pages.connect_agent.title']).toBeUndefined();
+    // A header title that genuinely differs from the label does emit.
+    expect(byPath['pages.renamed_header.title']).toBe('Different Title');
+    // Non-header components and non-translatable props (icon) contribute
+    // nothing — the page namespace holds only the four translatable keys.
+    const pagePaths = Object.keys(byPath).filter((p) => p.startsWith('pages.'));
+    expect(pagePaths.sort()).toEqual([
+      'pages.bare_page.label',
+      'pages.connect_agent.description',
+      'pages.connect_agent.label',
+      'pages.connect_agent.subtitle',
+      'pages.renamed_header.label',
+      'pages.renamed_header.title',
+    ]);
+  });
 });
 
 describe('extractTranslations', () => {

packages/platform-objects/src/apps/translations/en.ts

@@ -60,6 +60,7 @@ export const en: TranslationData = {
         // Apps / Marketplace
         nav_marketplace_browse: { label: 'Browse Marketplace' },
         nav_marketplace_installed: { label: 'Installed Apps' },
+        nav_cloud_connection: { label: 'Cloud Connection' },
 
         // People & Organization
         nav_users: { label: 'Users' },
@@ -75,6 +76,7 @@ export const en: TranslationData = {
         nav_sharing_rules: { label: 'Sharing Rules' },
         nav_record_shares: { label: 'Record Shares' },
         nav_api_keys: { label: 'API Keys' },
+        nav_connect_agent: { label: 'Connect an Agent' },
 
         // Approvals
         nav_approval_processes: { label: 'Processes' },
@@ -195,4 +197,27 @@ export const en: TranslationData = {
       },
     },
   },
+
+  // Setup pages contributed as metadata by capability plugins. The English
+  // entries mirror the literals authored in the plugins' page metadata
+  // (@objectstack/cloud-connection, @objectstack/mcp) and exist so the other
+  // locales have a complete key set to translate against.
+  pages: {
+    marketplace_installed: {
+      label: 'Installed Apps',
+      subtitle: "Marketplace packages currently installed into this runtime's kernel.",
+    },
+    cloud_connection_settings: {
+      label: 'Cloud Connection',
+      subtitle:
+        'Connect this runtime to an ObjectStack control plane to browse your '
+        + "organization's private packages and install them here.",
+    },
+    connect_agent: {
+      label: 'Connect an Agent',
+      subtitle:
+        'Give any MCP-capable AI client governed access to this environment — '
+        + "every call runs under the caller's own permissions and row-level security.",
+    },
+  },
 };

packages/platform-objects/src/apps/translations/es-ES.ts

@@ -34,6 +34,7 @@ export const esES: TranslationData = {
         group_apps: { label: 'Aplicaciones' },
         nav_marketplace_browse: { label: 'Explorar Marketplace' },
         nav_marketplace_installed: { label: 'Aplicaciones instaladas' },
+        nav_cloud_connection: { label: 'Conexión a la nube' },
         group_people_org: { label: 'Personas y Organización' },
         group_access_control: { label: 'Control de Acceso' },
         group_approvals: { label: 'Aprobaciones' },
@@ -56,6 +57,7 @@ export const esES: TranslationData = {
         nav_sharing_rules: { label: 'Reglas de Compartición' },
         nav_record_shares: { label: 'Registros Compartidos' },
         nav_api_keys: { label: 'Claves API' },
+        nav_connect_agent: { label: 'Conectar un agente' },
 
         nav_approval_processes: { label: 'Procesos' },
         nav_approval_requests: { label: 'Solicitudes' },
@@ -141,4 +143,23 @@ export const esES: TranslationData = {
       },
     },
   },
+
+  pages: {
+    marketplace_installed: {
+      label: 'Aplicaciones instaladas',
+      subtitle: 'Paquetes del marketplace instalados actualmente en el kernel de este runtime.',
+    },
+    cloud_connection_settings: {
+      label: 'Conexión a la nube',
+      subtitle:
+        'Conecta este runtime a un plano de control de ObjectStack para explorar los paquetes '
+        + 'privados de tu organización e instalarlos aquí.',
+    },
+    connect_agent: {
+      label: 'Conectar un agente',
+      subtitle:
+        'Concede a cualquier cliente de IA compatible con MCP acceso controlado a este entorno: '
+        + 'cada llamada se ejecuta con los permisos propios de quien la realiza y con seguridad a nivel de fila.',
+    },
+  },
 };

packages/platform-objects/src/apps/translations/ja-JP.ts

@@ -34,6 +34,7 @@ export const jaJP: TranslationData = {
         group_apps: { label: 'アプリ' },
         nav_marketplace_browse: { label: 'マーケットプレイスを閲覧' },
         nav_marketplace_installed: { label: 'インストール済みアプリ' },
+        nav_cloud_connection: { label: 'クラウド接続' },
         group_people_org: { label: 'ユーザーと組織' },
         group_access_control: { label: 'アクセス制御' },
         group_approvals: { label: '承認' },
@@ -56,6 +57,7 @@ export const jaJP: TranslationData = {
         nav_sharing_rules: { label: '共有ルール' },
         nav_record_shares: { label: 'レコード共有' },
         nav_api_keys: { label: 'API キー' },
+        nav_connect_agent: { label: 'エージェントを接続' },
 
         nav_approval_processes: { label: 'プロセス' },
         nav_approval_requests: { label: 'リクエスト' },
@@ -141,4 +143,21 @@ export const jaJP: TranslationData = {
       },
     },
   },
+
+  pages: {
+    marketplace_installed: {
+      label: 'インストール済みアプリ',
+      subtitle: 'このランタイムのカーネルに現在インストールされているマーケットプレイスパッケージ。',
+    },
+    cloud_connection_settings: {
+      label: 'クラウド接続',
+      subtitle:
+        'このランタイムを ObjectStack コントロールプレーンに接続すると、組織のプライベートパッケージを閲覧してここにインストールできます。',
+    },
+    connect_agent: {
+      label: 'エージェントを接続',
+      subtitle:
+        'MCP 対応の AI クライアントにこの環境への統制されたアクセスを許可します。すべての呼び出しは、呼び出し元自身の権限と行レベルセキュリティのもとで実行されます。',
+    },
+  },
 };

packages/platform-objects/src/apps/translations/zh-CN.ts

@@ -146,4 +146,19 @@ export const zhCN: TranslationData = {
       },
     },
   },
+
+  pages: {
+    marketplace_installed: {
+      label: '已安装应用',
+      subtitle: '当前已安装到此运行时内核的应用市场包。',
+    },
+    cloud_connection_settings: {
+      label: '云连接',
+      subtitle: '将此运行时连接到 ObjectStack 控制平面，即可浏览并安装组织的私有包。',
+    },
+    connect_agent: {
+      label: '连接智能体',
+      subtitle: '让任意支持 MCP 的 AI 客户端受控访问此环境——每次调用都在调用者自身的权限与行级安全范围内执行。',
+    },
+  },
 };

packages/rest/src/rest-server.ts

@@ -48,7 +48,7 @@ const logWarn = (...args: unknown[]) => ((globalThis as any).console?.warn ?? (g
  * via `translateMetadataDocument`. Keep in sync with the type dispatch in
  * `@objectstack/spec/system`'s `translateMetadataDocument`.
  */
-const TRANSLATABLE_META_TYPES = new Set(['view', 'action', 'object', 'app', 'dashboard']);
+const TRANSLATABLE_META_TYPES = new Set(['view', 'action', 'object', 'app', 'dashboard', 'page']);
 
 
 /**

packages/rest/src/rest.test.ts

@@ -2535,6 +2535,65 @@ describe('RestServer metadata translation — envelope unwrap', () => {
   });
 });
 
+// ──────────────────────────────────────────────────────────────────────────
+// Page metadata translation (objectstack#3589)
+//
+// Plugin-carried Setup pages hard-code their `page:header` copy in metadata.
+// `page` was missing from TRANSLATABLE_META_TYPES, so the REST boundary
+// returned those pages untranslated no matter what the bundle held.
+// ──────────────────────────────────────────────────────────────────────────
+describe('RestServer metadata translation — page documents', () => {
+  const fakeI18n = {
+    getLocales: () => ['zh-CN'],
+    getDefaultLocale: () => 'zh-CN',
+    getTranslations: (locale: string) =>
+      locale === 'zh-CN'
+        ? {
+            pages: {
+              connect_agent: {
+                label: '连接智能体',
+                subtitle: '让任意支持 MCP 的 AI 客户端受控访问此环境。',
+              },
+            },
+          }
+        : undefined,
+  };
+  const zhReq = { headers: { 'accept-language': 'zh-CN' } };
+  const makePage = () => ({
+    name: 'connect_agent',
+    label: 'Connect an Agent',
+    regions: [
+      {
+        name: 'header',
+        components: [
+          {
+            type: 'page:header',
+            properties: { title: 'Connect an Agent', subtitle: 'Give any MCP-capable client…', icon: 'bot' },
+          },
+        ],
+      },
+    ],
+  });
+
+  it('translates the page:header copy inside a getMetaItem envelope', async () => {
+    const rest = new RestServer(createMockServer() as any, createMockProtocol() as any, ANON_API as any);
+    const envelope = { type: 'page', name: 'connect_agent', item: makePage(), lock: null };
+    const out = await (rest as any).translateMetaItem(zhReq, 'page', undefined, envelope, fakeI18n);
+    expect(out.name).toBe('connect_agent');
+    expect(out.item.label).toBe('连接智能体');
+    expect(out.item.regions[0].components[0].properties.title).toBe('连接智能体');
+    expect(out.item.regions[0].components[0].properties.subtitle).toBe('让任意支持 MCP 的 AI 客户端受控访问此环境。');
+    expect(out.item.regions[0].components[0].properties.icon).toBe('bot');
+  });
+
+  it('translates page documents in a list response', async () => {
+    const rest = new RestServer(createMockServer() as any, createMockProtocol() as any, ANON_API as any);
+    (rest as any).resolveI18nService = async () => fakeI18n;
+    const out = await (rest as any).translateMetaItems(zhReq, 'page', undefined, [makePage()]);
+    expect(out[0].regions[0].components[0].properties.title).toBe('连接智能体');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // ADR-0045 — hidden-app visibility gate (filterAppForUser)
 // ---------------------------------------------------------------------------