feat: add translation completeness tooling (typegen, skeleton, validator)

Copilot · hotlong · Copilot · commit 88de57aecfbf · 2026-03-02T03:52:54.000Z
- Add StrictObjectTranslation type utility for compile-time field/option enforcement
- Add generateTranslationSkeleton() for AI-friendly translation templates
- Add validateTranslationCompleteness() for runtime completeness validation
- Make ObjectSchema.create() generic to preserve field key types
- Update zh-CN/en/ja-JP translations with missing category and recurrence_type options
- Add satisfies pattern to zh-CN.ts as reference example
- Add comprehensive unit tests (27 new tests in spec, 52 in example)

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/examples/app-todo/src/translations/en.ts b/examples/app-todo/src/translations/en.ts
@@ -35,7 +35,17 @@ export const en: TranslationData = {
             urgent: 'Urgent',
           },
         },
-        category: { label: 'Category' },
+        category: {
+          label: 'Category',
+          options: {
+            personal: 'Personal',
+            work: 'Work',
+            shopping: 'Shopping',
+            health: 'Health',
+            finance: 'Finance',
+            other: 'Other',
+          },
+        },
         due_date: { label: 'Due Date' },
         reminder_date: { label: 'Reminder Date/Time' },
         completed_date: { label: 'Completed Date' },
@@ -51,7 +61,15 @@ export const en: TranslationData = {
           },
         },
         is_recurring: { label: 'Recurring Task' },
-        recurrence_type: { label: 'Recurrence Type' },
+        recurrence_type: {
+          label: 'Recurrence Type',
+          options: {
+            daily: 'Daily',
+            weekly: 'Weekly',
+            monthly: 'Monthly',
+            yearly: 'Yearly',
+          },
+        },
         recurrence_interval: { label: 'Recurrence Interval' },
         is_completed: { label: 'Is Completed' },
         is_overdue: { label: 'Is Overdue' },
diff --git a/examples/app-todo/src/translations/ja-JP.ts b/examples/app-todo/src/translations/ja-JP.ts
@@ -34,7 +34,17 @@ export const jaJP: TranslationData = {
             urgent: '緊急',
           },
         },
-        category: { label: 'カテゴリ' },
+        category: {
+          label: 'カテゴリ',
+          options: {
+            personal: '個人',
+            work: '仕事',
+            shopping: '買い物',
+            health: '健康',
+            finance: '財務',
+            other: 'その他',
+          },
+        },
         due_date: { label: '期日' },
         reminder_date: { label: 'リマインダー日時' },
         completed_date: { label: '完了日' },
@@ -50,7 +60,15 @@ export const jaJP: TranslationData = {
           },
         },
         is_recurring: { label: '繰り返しタスク' },
-        recurrence_type: { label: '繰り返しタイプ' },
+        recurrence_type: {
+          label: '繰り返しタイプ',
+          options: {
+            daily: '毎日',
+            weekly: '毎週',
+            monthly: '毎月',
+            yearly: '毎年',
+          },
+        },
         recurrence_interval: { label: '繰り返し間隔' },
         is_completed: { label: '完了済み' },
         is_overdue: { label: '期限超過' },
diff --git a/examples/app-todo/src/translations/translation-completeness.test.ts b/examples/app-todo/src/translations/translation-completeness.test.ts
@@ -0,0 +1,50 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { Task } from '../objects/task.object';
+import { en } from './en';
+import { zhCN } from './zh-CN';
+import type { TranslationData } from '@objectstack/spec/system';
+
+/**
+ * Translation Completeness Test
+ *
+ * Validates that every field and every select option in the Task object
+ * definition has a corresponding translation in each locale.
+ */
+
+const fieldNames = Object.keys(Task.fields);
+
+const selectFields = Object.entries(Task.fields)
+  .filter(([, f]) => Array.isArray(f.options) && f.options.length > 0)
+  .map(([name, f]) => ({
+    name,
+    values: f.options!.map((o: { value: string }) => o.value),
+  }));
+
+describe.each([
+  ['en', en],
+  ['zh-CN', zhCN],
+] as [string, TranslationData][])('%s translation completeness', (locale, t) => {
+
+  it('should have task object translation', () => {
+    expect(t.objects?.task).toBeDefined();
+    expect(t.objects?.task?.label).toBeTruthy();
+  });
+
+  it.each(fieldNames)('field: %s', (name) => {
+    expect(
+      t.objects?.task?.fields?.[name]?.label,
+      `[${locale}] Missing label for field "${name}"`,
+    ).toBeTruthy();
+  });
+
+  it.each(selectFields)('options: $name', ({ name, values }) => {
+    for (const v of values) {
+      expect(
+        t.objects?.task?.fields?.[name]?.options?.[v],
+        `[${locale}] Missing option "${v}" for field "${name}"`,
+      ).toBeTruthy();
+    }
+  });
+});
diff --git a/examples/app-todo/src/translations/zh-CN.ts b/examples/app-todo/src/translations/zh-CN.ts
@@ -1,6 +1,10 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { TranslationData } from '@objectstack/spec/system';
+import type { StrictObjectTranslation } from '@objectstack/spec/system';
+import { Task } from '../objects/task.object';
+
+type TaskTranslation = StrictObjectTranslation<typeof Task>;
 
 /**
  * 简体中文 (zh-CN) — Todo App Translations
@@ -34,7 +38,17 @@ export const zhCN: TranslationData = {
             urgent: '紧急',
           },
         },
-        category: { label: '分类' },
+        category: {
+          label: '分类',
+          options: {
+            personal: '个人',
+            work: '工作',
+            shopping: '购物',
+            health: '健康',
+            finance: '财务',
+            other: '其他',
+          },
+        },
         due_date: { label: '截止日期' },
         reminder_date: { label: '提醒日期/时间' },
         completed_date: { label: '完成日期' },
@@ -50,7 +64,15 @@ export const zhCN: TranslationData = {
           },
         },
         is_recurring: { label: '周期性任务' },
-        recurrence_type: { label: '重复类型' },
+        recurrence_type: {
+          label: '重复类型',
+          options: {
+            daily: '每天',
+            weekly: '每周',
+            monthly: '每月',
+            yearly: '每年',
+          },
+        },
         recurrence_interval: { label: '重复间隔' },
         is_completed: { label: '是否完成' },
         is_overdue: { label: '是否逾期' },
@@ -60,7 +82,7 @@ export const zhCN: TranslationData = {
         notes: { label: '备注' },
         category_color: { label: '分类颜色' },
       },
-    },
+    } satisfies TaskTranslation,
   },
   apps: {
     todo_app: {
diff --git a/packages/spec/src/data/object.zod.ts b/packages/spec/src/data/object.zod.ts
@@ -378,12 +378,12 @@ export const ObjectSchema = Object.assign(ObjectSchemaBase, {
    * });
    * ```
    */
-  create: (config: z.input<typeof ObjectSchemaBase>): ServiceObject => {
+  create: <const T extends z.input<typeof ObjectSchemaBase>>(config: T): ServiceObject & Pick<T, 'fields'> => {
     const withDefaults = {
       ...config,
       label: config.label ?? snakeCaseToLabel(config.name),
     };
-    return ObjectSchemaBase.parse(withDefaults);
+    return ObjectSchemaBase.parse(withDefaults) as ServiceObject & Pick<T, 'fields'>;
   },
 });
 
diff --git a/packages/spec/src/system/index.ts b/packages/spec/src/system/index.ts
@@ -41,6 +41,9 @@ export * from './job.zod';
 export * from './worker.zod';
 export * from './notification.zod';
 export * from './translation.zod';
+export * from './translation-typegen';
+export * from './translation-skeleton';
+export * from './translation-validator';
 export * from './collaboration.zod';
 export * from './metadata-persistence.zod';
 export * from './core-services.zod';
diff --git a/packages/spec/src/system/translation-skeleton.test.ts b/packages/spec/src/system/translation-skeleton.test.ts
@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { generateTranslationSkeleton, TRANSLATE_PLACEHOLDER } from './translation-skeleton';
+import type { ServiceObject } from '../data/object.zod';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Test fixture — minimal ServiceObject
+// ────────────────────────────────────────────────────────────────────────────
+
+const mockObject = {
+  name: 'test_obj',
+  label: 'Test Object',
+  pluralLabel: 'Test Objects',
+  fields: {
+    title: { type: 'text', label: 'Title' },
+    body: { type: 'textarea', label: 'Body', description: 'Main content area' },
+    status: {
+      type: 'select',
+      label: 'Status',
+      options: [
+        { label: 'Open', value: 'open' },
+        { label: 'Closed', value: 'closed' },
+      ],
+    },
+    priority: {
+      type: 'select',
+      label: 'Priority',
+      options: [
+        { label: 'Low', value: 'low' },
+        { label: 'Normal', value: 'normal' },
+        { label: 'High', value: 'high' },
+      ],
+    },
+    plain: { type: 'number', label: 'Amount' },
+  },
+} as unknown as ServiceObject;
+
+describe('generateTranslationSkeleton', () => {
+
+  it('should output valid JSON', () => {
+    const json = generateTranslationSkeleton(mockObject);
+    expect(() => JSON.parse(json)).not.toThrow();
+  });
+
+  it('should include object label and pluralLabel', () => {
+    const skeleton = JSON.parse(generateTranslationSkeleton(mockObject));
+    expect(skeleton.label).toContain(TRANSLATE_PLACEHOLDER);
+    expect(skeleton.label).toContain('Test Object');
+    expect(skeleton.pluralLabel).toContain('Test Objects');
+  });
+
+  it('should include all field keys', () => {
+    const skeleton = JSON.parse(generateTranslationSkeleton(mockObject));
+    const fieldKeys = Object.keys(skeleton.fields);
+    expect(fieldKeys).toEqual(['title', 'body', 'status', 'priority', 'plain']);
+  });
+
+  it('should add help placeholder for fields with description', () => {
+    const skeleton = JSON.parse(generateTranslationSkeleton(mockObject));
+    expect(skeleton.fields.body.help).toContain(TRANSLATE_PLACEHOLDER);
+    expect(skeleton.fields.body.help).toContain('Main content area');
+    // Field without description should not have help
+    expect(skeleton.fields.title.help).toBeUndefined();
+  });
+
+  it('should include options map for select fields', () => {
+    const skeleton = JSON.parse(generateTranslationSkeleton(mockObject));
+    expect(skeleton.fields.status.options).toEqual({
+      open: `${TRANSLATE_PLACEHOLDER}: "Open"`,
+      closed: `${TRANSLATE_PLACEHOLDER}: "Closed"`,
+    });
+    expect(skeleton.fields.priority.options).toEqual({
+      low: `${TRANSLATE_PLACEHOLDER}: "Low"`,
+      normal: `${TRANSLATE_PLACEHOLDER}: "Normal"`,
+      high: `${TRANSLATE_PLACEHOLDER}: "High"`,
+    });
+  });
+
+  it('should not include options for non-select fields', () => {
+    const skeleton = JSON.parse(generateTranslationSkeleton(mockObject));
+    expect(skeleton.fields.title.options).toBeUndefined();
+    expect(skeleton.fields.plain.options).toBeUndefined();
+  });
+
+  it('should handle object without pluralLabel', () => {
+    const objWithoutPlural = {
+      ...mockObject,
+      pluralLabel: undefined,
+    } as unknown as ServiceObject;
+    const skeleton = JSON.parse(generateTranslationSkeleton(objWithoutPlural));
+    expect(skeleton.pluralLabel).toBeUndefined();
+  });
+});
diff --git a/packages/spec/src/system/translation-skeleton.ts b/packages/spec/src/system/translation-skeleton.ts
@@ -0,0 +1,74 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ServiceObject } from '../data/object.zod';
+
+/**
+ * Translation Skeleton Generator
+ *
+ * Generates an AI-friendly JSON "fill-in-the-blank" template from an object
+ * definition. The output contains `__TRANSLATE__` placeholders for every
+ * translatable string, ensuring AI/human translators cannot accidentally
+ * add or omit fields.
+ *
+ * @example
+ * ```typescript
+ * import { generateTranslationSkeleton } from '@objectstack/spec/system';
+ * import { Task } from './objects/task.object';
+ *
+ * const skeleton = generateTranslationSkeleton(Task);
+ * // → JSON string with __TRANSLATE__ placeholders for all 18 fields
+ * ```
+ */
+
+/** Placeholder prefix used in skeleton output */
+export const TRANSLATE_PLACEHOLDER = '__TRANSLATE__';
+
+/**
+ * Generates a translation skeleton JSON string from an object definition.
+ *
+ * The skeleton includes:
+ * - Object-level `label` and `pluralLabel`
+ * - Every field with a `label` placeholder
+ * - `help` placeholder for fields that have a `description`
+ * - `options` map for select/multiselect fields with all option values
+ *
+ * @param objectDef - A parsed ServiceObject definition
+ * @returns A formatted JSON string with `__TRANSLATE__` placeholders
+ */
+export function generateTranslationSkeleton(objectDef: ServiceObject): string {
+  const skeleton: Record<string, unknown> = {
+    label: `${TRANSLATE_PLACEHOLDER}: "${objectDef.label}"`,
+  };
+
+  if (objectDef.pluralLabel) {
+    skeleton.pluralLabel = `${TRANSLATE_PLACEHOLDER}: "${objectDef.pluralLabel}"`;
+  }
+
+  const fieldsObj: Record<string, Record<string, unknown>> = {};
+
+  for (const [fieldName, fieldDef] of Object.entries(objectDef.fields)) {
+    const fieldEntry: Record<string, unknown> = {
+      label: `${TRANSLATE_PLACEHOLDER}: "${fieldDef.label ?? fieldName}"`,
+    };
+
+    // Add help placeholder for fields with a description
+    if (fieldDef.description) {
+      fieldEntry.help = `${TRANSLATE_PLACEHOLDER}: "${fieldDef.description}"`;
+    }
+
+    // Add options map for select/multiselect fields
+    if (fieldDef.options && fieldDef.options.length > 0) {
+      const optionsMap: Record<string, string> = {};
+      for (const opt of fieldDef.options) {
+        optionsMap[opt.value] = `${TRANSLATE_PLACEHOLDER}: "${opt.label}"`;
+      }
+      fieldEntry.options = optionsMap;
+    }
+
+    fieldsObj[fieldName] = fieldEntry;
+  }
+
+  skeleton.fields = fieldsObj;
+
+  return JSON.stringify(skeleton, null, 2);
+}
diff --git a/packages/spec/src/system/translation-typegen.test.ts b/packages/spec/src/system/translation-typegen.test.ts
diff --git a/packages/spec/src/system/translation-typegen.ts b/packages/spec/src/system/translation-typegen.ts
diff --git a/packages/spec/src/system/translation-validator.test.ts b/packages/spec/src/system/translation-validator.test.ts
diff --git a/packages/spec/src/system/translation-validator.ts b/packages/spec/src/system/translation-validator.ts
