From d727c0137632d94e71793d926d68c963d3c37251 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8C=85=E5=91=A8=E6=B6=9B?= <baozhoutao@hotoa.com>
Date: Tue, 14 Jul 2026 06:48:02 -0700
Subject: [PATCH 1/2] feat(rest,spec): localized export filenames + built-in
 system-field label fallback

- rest: GET /data/:object/export Content-Disposition now uses the object's
  display label + timestamp via RFC 5987/6266 (ASCII api-name fallback in
  filename=, localized label in filename*=UTF-8''). New exportContentDisposition().
- spec: translateObject gains built-in en/zh-CN/ja-JP/es-ES labels for the
  five registry-injected system fields (owner_id/created_at/created_by/
  updated_at/updated_by), applied only when the label is still the injected
  English default; works without a translation bundle. REST meta translation
  no longer bails out when the bundle is missing (ETag is already locale-keyed).
- plugin-reports: attachment filename sanitizer keeps Unicode letters/digits
  instead of flattening CJK to underscores.
- showcase: enable exportOptions on the task In Progress view so export is
  demonstrated (and UI-testable) in the example app.
---
 .../export-filename-and-system-field-i18n.md  | 13 +++
 .../app-showcase/src/ui/views/task.view.ts    |  1 +
 .../plugin-reports/src/report-service.ts      |  4 +-
 packages/rest/src/export-format.test.ts       | 36 ++++++++-
 packages/rest/src/export-format.ts            | 36 +++++++++
 packages/rest/src/rest-server.ts              | 24 ++++--
 packages/rest/src/rest.test.ts                |  4 +-
 .../spec/src/system/i18n-resolver.test.ts     | 79 +++++++++++++++++++
 packages/spec/src/system/i18n-resolver.ts     | 50 +++++++++++-
 9 files changed, 232 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/export-filename-and-system-field-i18n.md

diff --git a/.changeset/export-filename-and-system-field-i18n.md b/.changeset/export-filename-and-system-field-i18n.md
new file mode 100644
index 0000000000..bbc19b808e
--- /dev/null
+++ b/.changeset/export-filename-and-system-field-i18n.md
@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': patch
+'@objectstack/rest': patch
+'@objectstack/plugin-reports': patch
+---
+
+导出文件名本地化 + 系统字段标签内置多语言回退。
+
+**`@objectstack/rest` — 导出下载文件名**:`GET /data/:object/export` 的 `Content-Disposition` 不再是裸的 `<对象名>.<扩展名>`,改为「对象显示名-时间戳」:ASCII 兜底用 API 名(`filename="contracts-20260714-153045.xlsx"`),本地化标签(如中文)按 RFC 5987/6266 编码进 `filename*=UTF-8''…`(浏览器直接下载得到 `合同-20260714-153045.xlsx`)。新增导出 `exportContentDisposition(objectName, label, ext, now?)`。
+
+**`@objectstack/spec` — 系统字段标签回退**:ObjectQL 注册表给每个对象注入的系统字段(`owner_id`/`created_at`/`created_by`/`updated_at`/`updated_by`)只带英文标签,自定义对象又没有对应的翻译条目,导致中文界面的列表表头、导出文件、导入模板里漏出 "Owner"/"Created At" 等英文。`translateObject` 现内置这五个字段的 en/zh-CN/ja-JP/es-ES 标签表(措辞与平台生成的翻译包一致),仅当字段仍是注入的英文默认值时套用——作者自定义的标签绝不覆盖;无翻译包时也生效(`translateObject` 不再因缺 bundle 而提前返回,REST 元数据翻译路径同步放宽,缓存 ETag 本就按 locale 分键,无缓存串味风险)。
+
+**`@objectstack/plugin-reports` — 附件文件名**:定时报表附件的文件名清洗从「非 ASCII 全部替换成 `_`」改为按 Unicode 字母/数字保留(`\p{L}\p{N}`),中文计划名不再变成一串下划线。
diff --git a/examples/app-showcase/src/ui/views/task.view.ts b/examples/app-showcase/src/ui/views/task.view.ts
index 43b66171cc..f477616df2 100644
--- a/examples/app-showcase/src/ui/views/task.view.ts
+++ b/examples/app-showcase/src/ui/views/task.view.ts
@@ -66,6 +66,7 @@ export const TaskViews = defineView({
       data,
       columns: [{ field: 'title' }, { field: 'project' }, { field: 'assignee' }, { field: 'status' }, { field: 'priority' }, { field: 'due_date' }],
       filter: [{ field: 'status', operator: 'equals', value: 'in_progress' }],
+      exportOptions: ['csv', 'xlsx', 'json'],
     },
     urgent: {
       label: 'Urgent',
diff --git a/packages/plugins/plugin-reports/src/report-service.ts b/packages/plugins/plugin-reports/src/report-service.ts
index de9c9cc037..fb7ec6718d 100644
--- a/packages/plugins/plugin-reports/src/report-service.ts
+++ b/packages/plugins/plugin-reports/src/report-service.ts
@@ -438,7 +438,9 @@ export class ReportService implements IReportService {
               subject,
               text: `Attached: ${result.rowCount} row(s).`,
               attachments: [{
-                filename: `${(schedule.name ?? report.name).replace(/[^\w.-]+/g, '_')}-${ts.slice(0, 10)}.csv`,
+                // Keep unicode letters (CJK schedule names) — only strip
+                // filesystem-hostile characters, else 周报 becomes `__`.
+                filename: `${(schedule.name ?? report.name).replace(/[^\p{L}\p{N}._-]+/gu, '_').replace(/^_+|_+$/g, '') || 'report'}-${ts.slice(0, 10)}.csv`,
                 content: result.body,
                 contentType: 'text/csv',
               }],
diff --git a/packages/rest/src/export-format.test.ts b/packages/rest/src/export-format.test.ts
index 0e3e7ad3d8..e454041602 100644
--- a/packages/rest/src/export-format.test.ts
+++ b/packages/rest/src/export-format.test.ts
@@ -8,7 +8,41 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { toArgb, cellFontColor, type ExportFieldMeta } from './export-format';
+import { toArgb, cellFontColor, exportContentDisposition, type ExportFieldMeta } from './export-format';
+
+describe('exportContentDisposition', () => {
+  const NOW = new Date(2026, 6, 14, 15, 30, 45); // 2026-07-14 15:30:45 local
+
+  it('uses the localized label in filename* and the API name as ASCII fallback', () => {
+    expect(exportContentDisposition('contracts', '合同', 'xlsx', NOW)).toBe(
+      `attachment; filename="contracts-20260714-153045.xlsx"; filename*=UTF-8''${encodeURIComponent('合同-20260714-153045.xlsx')}`,
+    );
+  });
+
+  it('falls back to the API name when no label is available', () => {
+    expect(exportContentDisposition('contracts', undefined, 'csv', NOW)).toBe(
+      `attachment; filename="contracts-20260714-153045.csv"; filename*=UTF-8''contracts-20260714-153045.csv`,
+    );
+  });
+
+  it('sanitizes hostile characters in both names', () => {
+    const header = exportContentDisposition('a/b', '合 同: v2?', 'csv', NOW);
+    expect(header).toContain('filename="a_b-20260714-153045.csv"');
+    expect(header).toContain(`filename*=UTF-8''${encodeURIComponent('合 同_ v2-20260714-153045.csv')}`);
+  });
+
+  it('percent-encodes RFC 5987 non-attr-chars that encodeURIComponent leaves alone', () => {
+    const header = exportContentDisposition('obj', "a'b(c)", 'csv', NOW);
+    expect(header).toContain("filename*=UTF-8''a%27b%28c%29-20260714-153045.csv");
+  });
+
+  it('zero-pads date and time parts', () => {
+    const early = new Date(2026, 0, 5, 9, 8, 7);
+    expect(exportContentDisposition('obj', undefined, 'json', early)).toContain(
+      'filename="obj-20260105-090807.json"',
+    );
+  });
+});
 
 describe('toArgb', () => {
   it('expands 3-digit hex to opaque ARGB', () => {
diff --git a/packages/rest/src/export-format.ts b/packages/rest/src/export-format.ts
index dccdf4732e..e649bb16d2 100644
--- a/packages/rest/src/export-format.ts
+++ b/packages/rest/src/export-format.ts
@@ -37,6 +37,42 @@ export interface ExportFieldMeta {
   hasDefault?: boolean;
 }
 
+/**
+ * Build the `Content-Disposition` header for an export download.
+ *
+ * The suggested filename is `<label>-<YYYYMMDD>-<HHMMSS>.<ext>` where the
+ * label is the object's (locale-translated) display label — so a browser
+ * saves e.g. `合同-20260714-153045.xlsx` instead of `contracts-2026-07-14.xlsx`.
+ * Non-ASCII labels ride the RFC 5987/6266 `filename*` parameter; the plain
+ * `filename` keeps an ASCII-safe fallback derived from the object API name
+ * for clients that don't understand `filename*`.
+ */
+export function exportContentDisposition(
+  objectName: string,
+  label: string | undefined,
+  ext: string,
+  now: Date = new Date(),
+): string {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const stamp =
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+    `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const asciiBase = objectName.replace(/[^A-Za-z0-9_.-]/g, '_') || 'export';
+  // Keep unicode letters (CJK labels) but drop filesystem-hostile characters.
+  // eslint-disable-next-line no-control-regex
+  const utf8Base = String(label ?? '')
+    .replace(/[\\/:*?"<>|\u0000-\u001f]+/g, '_')
+    .replace(/^[\s._-]+|[\s._-]+$/g, '')
+    .slice(0, 80) || asciiBase;
+  const asciiName = `${asciiBase}-${stamp}.${ext}`;
+  const utf8Name = `${utf8Base}-${stamp}.${ext}`;
+  // RFC 5987 pct-encoding: encodeURIComponent leaves `'()*` unescaped but
+  // they are not attr-chars, so escape them explicitly.
+  const encoded = encodeURIComponent(utf8Name)
+    .replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+  return `attachment; filename="${asciiName}"; filename*=UTF-8''${encoded}`;
+}
+
 /** Field types whose stored value points at another record. */
 const REFERENCE_TYPES = new Set(['lookup', 'master_detail', 'user', 'reference', 'tree']);
 
diff --git a/packages/rest/src/rest-server.ts b/packages/rest/src/rest-server.ts
index b2f5fc33d7..57dcec20b3 100644
--- a/packages/rest/src/rest-server.ts
+++ b/packages/rest/src/rest-server.ts
@@ -12,6 +12,7 @@ import {
     formatRowCells,
     formatRowForJson,
     cellFontColor,
+    exportContentDisposition,
     type ExportFieldMeta,
 } from './export-format.js';
 import { runImport } from './import-runner.js';
@@ -1405,8 +1406,11 @@ export class RestServer {
         // locale-aware ETag) and passes it here so we don't repeat the
         // potentially registry-hitting lookup on every request.
         const i18n = i18nService !== undefined ? i18nService : await this.resolveI18nService(environmentId, req);
+        // A missing bundle is NOT a bail-out: `translateMetadataDocument`
+        // still applies built-in fallbacks (e.g. the injected system-field
+        // labels `owner_id`/`created_*`/`updated_*` on custom objects, which
+        // ship no per-object translation entries).
         const bundle = this.buildTranslationBundle(i18n);
-        if (!bundle) return item;
         const locale = this.extractLocale(req, i18n);
         if (!locale) return item;
         const { translateMetadataDocument } = await import('@objectstack/spec/system');
@@ -1436,8 +1440,8 @@ export class RestServer {
             : (items && typeof items === 'object' && Array.isArray(items.items) ? items.items : null);
         if (!arr) return items;
         const i18n = await this.resolveI18nService(environmentId, req);
+        // Missing bundle ≠ bail-out — see `translateMetaItem`.
         const bundle = this.buildTranslationBundle(i18n);
-        if (!bundle) return items;
         const locale = this.extractLocale(req, i18n);
         if (!locale) return items;
         const { translateMetadataDocument } = await import('@objectstack/spec/system');
@@ -3920,7 +3924,9 @@ export class RestServer {
         //
         // Streams the response so 50k-row exports do not buffer in memory; the
         // xlsx path pipes exceljs' streaming writer straight onto the response.
-        // Filename suggests `${object}-${YYYY-MM-DD}.${ext}` for browsers.
+        // Filename suggests `${objectLabel}-${YYYYMMDD}-${HHMMSS}.${ext}` for
+        // browsers (localized label via RFC 5987 `filename*`, ASCII fallback
+        // from the API name — see exportContentDisposition).
         //
         // xlsx only: select / radio cells are coloured with their option's
         // `color` as the font colour (white cell background) when the effective
@@ -4000,6 +4006,9 @@ export class RestServer {
                     // references. Best-effort: when the schema is unavailable the export
                     // falls back to raw values, byte-identical to the un-formatted path.
                     let metaMap = new Map<string, ExportFieldMeta>();
+                    // Localized object display label (e.g. 合同) — drives the
+                    // suggested download filename below.
+                    let objectLabel: string | undefined;
                     try {
                         // Field metadata comes from the same place `findData` resolves
                         // the object: `getMetaItem` is registry-first (DB fallback), so
@@ -4021,6 +4030,9 @@ export class RestServer {
                         // export header row matches the UI column headers instead of
                         // leaking the raw, untranslated `field.label` values.
                         schema = await this.translateMetaItem(req, 'object', environmentId, schema);
+                        if (typeof schema?.label === 'string' && schema.label.length > 0) {
+                            objectLabel = schema.label;
+                        }
                         metaMap = buildFieldMetaMap(schema);
                         if (!fields || fields.length === 0) {
                             const names = [...metaMap.keys()];
@@ -4033,18 +4045,14 @@ export class RestServer {
                     const expandFields = referenceFieldNames(metaMap);
 
                     // Prepare streaming response. Set headers BEFORE first write.
-                    const stamp = new Date().toISOString().slice(0, 10);
-                    const safeObj = objectName.replace(/[^A-Za-z0-9_.-]/g, '_');
                     if (format === 'csv') {
                         res.header('Content-Type', 'text/csv; charset=utf-8');
-                        res.header('Content-Disposition', `attachment; filename="${safeObj}-${stamp}.csv"`);
                     } else if (format === 'xlsx') {
                         res.header('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
-                        res.header('Content-Disposition', `attachment; filename="${safeObj}-${stamp}.xlsx"`);
                     } else {
                         res.header('Content-Type', 'application/json; charset=utf-8');
-                        res.header('Content-Disposition', `attachment; filename="${safeObj}-${stamp}.json"`);
                     }
+                    res.header('Content-Disposition', exportContentDisposition(objectName, objectLabel, format));
                     res.header('X-Export-Format', format);
                     res.header('X-Export-Limit', String(limit));
                     // Signal whether select-option colours were applied. Only
diff --git a/packages/rest/src/rest.test.ts b/packages/rest/src/rest.test.ts
index 3579f2655a..909f3583ab 100644
--- a/packages/rest/src/rest.test.ts
+++ b/packages/rest/src/rest.test.ts
@@ -997,7 +997,7 @@ describe('RestServer', () => {
       await route!.handler(req as any, res);
 
       expect(headers['Content-Type']).toBe('text/csv; charset=utf-8');
-      expect(headers['Content-Disposition']).toMatch(/attachment; filename="account-\d{4}-\d{2}-\d{2}\.csv"/);
+      expect(headers['Content-Disposition']).toMatch(/attachment; filename="account-\d{8}-\d{6}\.csv"; filename\*=UTF-8''/);
       const text = chunks.join('');
       expect(text.startsWith('id,name,note\r\n')).toBe(true);
       expect(text).toContain('1,"Acme, Inc.","line1\nline2"');
@@ -1179,7 +1179,7 @@ describe('RestServer', () => {
       await route!.handler({ params: { object: 'task' }, query: { format: 'xlsx' } } as any, res);
 
       expect(headers['Content-Type']).toBe('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
-      expect(headers['Content-Disposition']).toMatch(/attachment; filename="task-\d{4}-\d{2}-\d{2}\.xlsx"/);
+      expect(headers['Content-Disposition']).toMatch(/attachment; filename="task-\d{8}-\d{6}\.xlsx"; filename\*=UTF-8''/);
       expect(headers['X-Export-Format']).toBe('xlsx');
       expect(res.end).toHaveBeenCalled();
 
diff --git a/packages/spec/src/system/i18n-resolver.test.ts b/packages/spec/src/system/i18n-resolver.test.ts
index ab5da56709..934385cfca 100644
--- a/packages/spec/src/system/i18n-resolver.test.ts
+++ b/packages/spec/src/system/i18n-resolver.test.ts
@@ -632,3 +632,82 @@ describe('translateDashboard', () => {
     expect(out.label).toBe('系统概览');
   });
 });
+
+// ────────────────────────────────────────────────────────────────────────────
+// translateObject — built-in system-field label fallback
+// ────────────────────────────────────────────────────────────────────────────
+
+import { translateObject } from './i18n-resolver';
+
+describe('translateObject system-field label fallback', () => {
+  const contract = {
+    name: 'contracts',
+    label: 'Contract',
+    fields: {
+      title: { name: 'title', type: 'text', label: '合同名称' },
+      owner_id: { name: 'owner_id', type: 'lookup', label: 'Owner' },
+      created_at: { name: 'created_at', type: 'datetime', label: 'Created At' },
+      created_by: { name: 'created_by', type: 'lookup', label: 'Created By' },
+      updated_at: { name: 'updated_at', type: 'datetime', label: 'Last Modified At' },
+      updated_by: { name: 'updated_by', type: 'lookup', label: 'Last Modified By' },
+    },
+  };
+
+  it('localizes injected system-field labels even without a bundle', () => {
+    const out = translateObject(contract, undefined, { locale: 'zh-CN' });
+    const fields = out.fields as Record<string, any>;
+    expect(fields.owner_id.label).toBe('所有者');
+    expect(fields.created_at.label).toBe('创建时间');
+    expect(fields.created_by.label).toBe('创建人');
+    expect(fields.updated_at.label).toBe('更新时间');
+    expect(fields.updated_by.label).toBe('更新人');
+    // Authored labels stay untouched.
+    expect(fields.title.label).toBe('合同名称');
+    // Input not mutated.
+    expect((contract.fields as any).owner_id.label).toBe('Owner');
+  });
+
+  it('applies BCP-47 fallback for base-language and variant locales', () => {
+    const zh = translateObject(contract, undefined, { locale: 'zh' });
+    expect((zh.fields as any).owner_id.label).toBe('所有者');
+    const ja = translateObject(contract, undefined, { locale: 'ja' });
+    expect((ja.fields as any).created_by.label).toBe('作成者');
+  });
+
+  it('keeps English labels for en and unknown locales', () => {
+    const en = translateObject(contract, undefined, { locale: 'en' });
+    expect((en.fields as any).owner_id.label).toBe('Owner');
+    const fr = translateObject(contract, undefined, { locale: 'fr-FR', fallbackChain: [] });
+    expect((fr.fields as any).owner_id.label).toBe('Owner');
+  });
+
+  it('never overrides an author-customized system-field label', () => {
+    const custom = {
+      name: 'contracts',
+      fields: { owner_id: { name: 'owner_id', type: 'lookup', label: '负责人' } },
+    };
+    const out = translateObject(custom, undefined, { locale: 'zh-CN' });
+    expect((out.fields as any).owner_id.label).toBe('负责人');
+  });
+
+  it('prefers an explicit bundle entry over the built-in fallback', () => {
+    const withBundle: TranslationBundle = {
+      'zh-CN': {
+        objects: {
+          contracts: { fields: { owner_id: { label: '合同负责人' } } },
+        },
+      } as any,
+    };
+    const out = translateObject(contract, withBundle, { locale: 'zh-CN' });
+    expect((out.fields as any).owner_id.label).toBe('合同负责人');
+  });
+
+  it('handles the array field shape', () => {
+    const arrayDoc = {
+      name: 'contracts',
+      fields: [{ name: 'owner_id', type: 'lookup', label: 'Owner' }],
+    };
+    const out = translateObject(arrayDoc, undefined, { locale: 'zh-CN' });
+    expect((out.fields as any)[0].label).toBe('所有者');
+  });
+});
diff --git a/packages/spec/src/system/i18n-resolver.ts b/packages/spec/src/system/i18n-resolver.ts
index 50647edbc6..f0f2442d12 100644
--- a/packages/spec/src/system/i18n-resolver.ts
+++ b/packages/spec/src/system/i18n-resolver.ts
@@ -71,7 +71,7 @@ export interface ResolveOptions {
  * Returns the matched bundle key, or `undefined` when nothing matches.
  */
 function resolveBundleLocale(
-  bundle: TranslationBundle,
+  bundle: Record<string, unknown>,
   requested: string,
 ): string | undefined {
   // 1. Exact match (fast path).
@@ -552,6 +552,46 @@ function lookupObjectFieldOption(
   return undefined;
 }
 
+/**
+ * Built-in labels for the platform-injected system fields (the ObjectQL
+ * registry stamps `owner_id` / `created_*` / `updated_*` onto every object
+ * with English labels). Custom objects carry no per-object translation
+ * entries for these, so without a fallback every localized surface — list
+ * headers, export files, import templates — leaks the English default (e.g.
+ * an otherwise fully-Chinese import template with an `Owner` column).
+ *
+ * Wording matches the generated platform bundles (`*.objects.generated.ts`)
+ * so a system field reads the same on custom and platform objects.
+ */
+const SYSTEM_FIELD_LABELS: Record<string, Record<string, string>> = {
+  owner_id: { en: 'Owner', 'zh-CN': '所有者', 'ja-JP': '所有者', 'es-ES': 'Propietario' },
+  created_at: { en: 'Created At', 'zh-CN': '创建时间', 'ja-JP': '作成日時', 'es-ES': 'Creado el' },
+  created_by: { en: 'Created By', 'zh-CN': '创建人', 'ja-JP': '作成者', 'es-ES': 'Creado por' },
+  updated_at: { en: 'Last Modified At', 'zh-CN': '更新时间', 'ja-JP': '更新日時', 'es-ES': 'Actualizado el' },
+  updated_by: { en: 'Last Modified By', 'zh-CN': '更新人', 'ja-JP': '更新者', 'es-ES': 'Actualizado por' },
+};
+
+/**
+ * Fallback label for a platform-injected system field, honouring the same
+ * locale-matching rules as bundle lookup (exact → case-insensitive → base
+ * language → variant). Applied only when the field still carries its injected
+ * English default — an author's custom label is never overridden.
+ */
+function builtinSystemFieldLabel(
+  fieldName: string,
+  currentLabel: string | undefined,
+  opts?: ResolveOptions,
+): string | undefined {
+  const entry = SYSTEM_FIELD_LABELS[fieldName];
+  if (!entry) return undefined;
+  if (currentLabel !== undefined && currentLabel !== entry.en) return undefined;
+  for (const code of localeChain(opts)) {
+    const resolved = resolveBundleLocale(entry, code);
+    if (resolved !== undefined) return entry[resolved];
+  }
+  return undefined;
+}
+
 /**
  * Apply the active locale to an object metadata document. Translates the
  * object's `label` / `pluralLabel` / `description` and walks each field to
@@ -570,7 +610,9 @@ export function translateObject<T extends ObjectLike>(
 ): T {
   if (!doc || typeof doc !== 'object') return doc;
   const objectName = doc.name;
-  if (!objectName || !bundle) return doc;
+  // Proceed even without a bundle: the built-in system-field labels below
+  // still apply (custom objects typically ship no translation entries).
+  if (!objectName) return doc;
 
   const label = lookupObjectField(bundle, objectName, 'label', opts) ?? doc.label;
   const pluralLabel =
@@ -580,7 +622,9 @@ export function translateObject<T extends ObjectLike>(
 
   const translateField = (name: string, def: ObjectFieldLike): ObjectFieldLike => {
     const next: ObjectFieldLike = { ...def };
-    const translatedLabel = lookupObjectFieldAttr(bundle, objectName, name, 'label', opts);
+    const translatedLabel =
+      lookupObjectFieldAttr(bundle, objectName, name, 'label', opts) ??
+      builtinSystemFieldLabel(name, def.label, opts);
     if (translatedLabel) next.label = translatedLabel;
     const translatedHelp = lookupObjectFieldAttr(bundle, objectName, name, 'help', opts);
     if (translatedHelp) next.help = translatedHelp;

From 6ab3e7c20d30eda574685480ccb1b3c3299b971b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8C=85=E5=91=A8=E6=B6=9B?= <baozhoutao@hotoa.com>
Date: Tue, 14 Jul 2026 07:53:43 -0700
Subject: [PATCH 2/2] =?UTF-8?q?fix(rest):=20accept=20locale-translated=20o?=
 =?UTF-8?q?ption=20labels=20on=20import=20(export=E2=86=94import=20round-t?=
 =?UTF-8?q?rip)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The localized export and the import template surface translated option
labels (e.g. 待规划 for backlog), but import coercion only knew the
authored schema labels — re-importing your own localized export failed
every select field with invalid_option.

- prepareImportRequest gains a localizeSchema hook; both REST import
  routes pass translateMetaItem so the request locale's labels merge
  into the field metaMap as matching synonyms (authored labels and
  option codes keep working; unknown values still fail; a throwing
  hook degrades to authored-only matching)
- new mergeLocalizedOptionSynonyms export + import-prepare tests
- app-showcase: complete the showcase_task en/zh-CN translation bundle
  (done/labels/sync_status/sync_error labels, status/priority/sync
  option maps) so templates and exports render fully localized
---
 .../export-filename-and-system-field-i18n.md  |   2 +
 .../src/system/translations/index.ts          |  34 +++++-
 packages/rest/src/import-prepare.test.ts      | 101 ++++++++++++++++++
 packages/rest/src/import-prepare.ts           |  62 ++++++++++-
 packages/rest/src/rest-server.ts              |  13 ++-
 5 files changed, 204 insertions(+), 8 deletions(-)
 create mode 100644 packages/rest/src/import-prepare.test.ts

diff --git a/.changeset/export-filename-and-system-field-i18n.md b/.changeset/export-filename-and-system-field-i18n.md
index bbc19b808e..f46f425e34 100644
--- a/.changeset/export-filename-and-system-field-i18n.md
+++ b/.changeset/export-filename-and-system-field-i18n.md
@@ -11,3 +11,5 @@
 **`@objectstack/spec` — 系统字段标签回退**:ObjectQL 注册表给每个对象注入的系统字段(`owner_id`/`created_at`/`created_by`/`updated_at`/`updated_by`)只带英文标签,自定义对象又没有对应的翻译条目,导致中文界面的列表表头、导出文件、导入模板里漏出 "Owner"/"Created At" 等英文。`translateObject` 现内置这五个字段的 en/zh-CN/ja-JP/es-ES 标签表(措辞与平台生成的翻译包一致),仅当字段仍是注入的英文默认值时套用——作者自定义的标签绝不覆盖;无翻译包时也生效(`translateObject` 不再因缺 bundle 而提前返回,REST 元数据翻译路径同步放宽,缓存 ETag 本就按 locale 分键,无缓存串味风险)。
 
 **`@objectstack/plugin-reports` — 附件文件名**:定时报表附件的文件名清洗从「非 ASCII 全部替换成 `_`」改为按 Unicode 字母/数字保留(`\p{L}\p{N}`),中文计划名不再变成一串下划线。
+
+**`@objectstack/rest` — 导入接受翻译后的选项标签(导出↔导入闭环)**:导出与导入模板写出的是*翻译后*的选项标签(如 `待规划`),但导入强制转换只认作者原始 schema 的标签/值,导致用户把自己刚导出的本地化文件原样导回时 select 字段全部报 `invalid_option`。`prepareImportRequest` 新增 `localizeSchema` 钩子(REST 导入路由传入 `translateMetaItem`),把当前 locale 的翻译标签合并进字段选项作为匹配同义词——作者标签与选项 code 照常匹配,非法值照常报错,翻译失败时降级为仅作者标签匹配。新增导出 `mergeLocalizedOptionSynonyms(metaMap, localizedMetaMap)`。
diff --git a/examples/app-showcase/src/system/translations/index.ts b/examples/app-showcase/src/system/translations/index.ts
index d33d9d01f5..ff88e5e478 100644
--- a/examples/app-showcase/src/system/translations/index.ts
+++ b/examples/app-showcase/src/system/translations/index.ts
@@ -33,17 +33,30 @@ export const ShowcaseTranslationBundle = {
           title: { label: 'Title' },
           project: { label: 'Project' },
           assignee: { label: 'Assignee' },
-          status: { label: 'Status' },
-          priority: { label: 'Priority' },
+          status: {
+            label: 'Status',
+            options: { backlog: 'Backlog', todo: 'To Do', in_progress: 'In Progress', in_review: 'In Review', done: 'Done' },
+          },
+          priority: {
+            label: 'Priority',
+            options: { low: 'Low', medium: 'Medium', high: 'High', urgent: 'Urgent' },
+          },
           due_date: { label: 'Due Date' },
           progress: { label: 'Progress' },
           estimate_hours: { label: 'Estimate (h)' },
+          done: { label: 'Done' },
           start_date: { label: 'Start Date' },
           end_date: { label: 'End Date' },
           created_at: { label: 'Created' },
           location: { label: 'Work Location' },
           cover: { label: 'Cover' },
+          labels: { label: 'Labels' },
           notes: { label: 'Notes' },
+          sync_status: {
+            label: 'Sync Status',
+            options: { synced: 'Synced', failed: 'Failed' },
+          },
+          sync_error: { label: 'Sync Error' },
         },
       },
       showcase_account: {
@@ -150,17 +163,30 @@ export const ShowcaseTranslationBundle = {
           title: { label: '标题' },
           project: { label: '项目' },
           assignee: { label: '负责人' },
-          status: { label: '状态' },
-          priority: { label: '优先级' },
+          status: {
+            label: '状态',
+            options: { backlog: '待规划', todo: '待办', in_progress: '进行中', in_review: '评审中', done: '已完成' },
+          },
+          priority: {
+            label: '优先级',
+            options: { low: '低', medium: '中', high: '高', urgent: '紧急' },
+          },
           due_date: { label: '截止日期' },
           progress: { label: '进度' },
           estimate_hours: { label: '预计工时' },
+          done: { label: '已完成' },
           start_date: { label: '开始日期' },
           end_date: { label: '结束日期' },
           created_at: { label: '创建时间' },
           location: { label: '工作地点' },
           cover: { label: '封面' },
+          labels: { label: '标签' },
           notes: { label: '备注' },
+          sync_status: {
+            label: '同步状态',
+            options: { synced: '已同步', failed: '同步失败' },
+          },
+          sync_error: { label: '同步错误' },
         },
       },
       showcase_account: {
diff --git a/packages/rest/src/import-prepare.test.ts b/packages/rest/src/import-prepare.test.ts
new file mode 100644
index 0000000000..2068327720
--- /dev/null
+++ b/packages/rest/src/import-prepare.test.ts
@@ -0,0 +1,101 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Round-trip i18n for import coercion: the localized export and the import
+ * template surface *translated* option labels (e.g. 待规划 for `backlog`), so
+ * `prepareImportRequest` folds those labels into the field metaMap as matching
+ * synonyms — while the authored label and the option code keep working.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { prepareImportRequest, mergeLocalizedOptionSynonyms } from './import-prepare';
+import { matchOption } from './import-coerce';
+import { buildFieldMetaMap } from './export-format';
+
+const SCHEMA = {
+  name: 'task',
+  fields: {
+    title: { name: 'title', type: 'text', label: 'Title' },
+    status: {
+      name: 'status', type: 'select', label: 'Status',
+      options: [
+        { label: 'Backlog', value: 'backlog' },
+        { label: 'Done', value: 'done' },
+      ],
+    },
+  },
+};
+
+/** What `translateMetaItem` returns for SCHEMA under a zh-CN request. */
+const localizeSchema = (schema: any) => ({
+  ...schema,
+  fields: {
+    ...schema.fields,
+    status: {
+      ...schema.fields.status,
+      label: '状态',
+      options: [
+        { label: '待规划', value: 'backlog' },
+        { label: '已完成', value: 'done' },
+      ],
+    },
+  },
+});
+
+const p = { getMetaItem: async () => ({ type: 'object', name: 'task', item: SCHEMA }) };
+
+describe('mergeLocalizedOptionSynonyms', () => {
+  it('appends translated labels as extra options without touching authored ones', () => {
+    const metaMap = buildFieldMetaMap(SCHEMA);
+    mergeLocalizedOptionSynonyms(metaMap, buildFieldMetaMap(localizeSchema(SCHEMA)));
+    const options = metaMap.get('status')!.options!;
+    expect(matchOption('待规划', options)).toBe('backlog');
+    expect(matchOption('Backlog', options)).toBe('backlog');
+    expect(matchOption('backlog', options)).toBe('backlog');
+    expect(matchOption('已完成', options)).toBe('done');
+  });
+
+  it('is a no-op when the locale leaves labels unchanged (en request)', () => {
+    const metaMap = buildFieldMetaMap(SCHEMA);
+    const before = metaMap.get('status')!.options!.length;
+    mergeLocalizedOptionSynonyms(metaMap, buildFieldMetaMap(SCHEMA));
+    expect(metaMap.get('status')!.options!.length).toBe(before);
+  });
+});
+
+describe('prepareImportRequest — locale-translated option synonyms', () => {
+  it('folds the localizeSchema labels into the prepared metaMap', async () => {
+    const prep = await prepareImportRequest(
+      { format: 'json', rows: [{ title: 'a', status: '待规划' }] },
+      { p, objectName: 'task', maxRows: 10, localizeSchema },
+    );
+    expect(prep.ok).toBe(true);
+    if (!prep.ok) return;
+    const options = prep.prepared.metaMap.get('status')!.options!;
+    expect(matchOption('待规划', options)).toBe('backlog');
+    expect(matchOption('Backlog', options)).toBe('backlog');
+  });
+
+  it('without localizeSchema the authored-only matching is unchanged', async () => {
+    const prep = await prepareImportRequest(
+      { format: 'json', rows: [{ title: 'a', status: 'Backlog' }] },
+      { p, objectName: 'task', maxRows: 10 },
+    );
+    expect(prep.ok).toBe(true);
+    if (!prep.ok) return;
+    const options = prep.prepared.metaMap.get('status')!.options!;
+    expect(options).toHaveLength(2);
+    // The translated label is unknown to the authored options → no match.
+    expect(matchOption('待规划', options)).toBeUndefined();
+  });
+
+  it('a throwing localizeSchema degrades to authored-only matching', async () => {
+    const prep = await prepareImportRequest(
+      { format: 'json', rows: [{ title: 'a', status: 'Backlog' }] },
+      { p, objectName: 'task', maxRows: 10, localizeSchema: () => { throw new Error('no i18n'); } },
+    );
+    expect(prep.ok).toBe(true);
+    if (!prep.ok) return;
+    expect(matchOption('Backlog', prep.prepared.metaMap.get('status')!.options!)).toBe('backlog');
+  });
+});
diff --git a/packages/rest/src/import-prepare.ts b/packages/rest/src/import-prepare.ts
index 4e6ce72066..fa7ed65e3c 100644
--- a/packages/rest/src/import-prepare.ts
+++ b/packages/rest/src/import-prepare.ts
@@ -193,11 +193,58 @@ export type PrepareImportResult =
  * 50k async). Returns a discriminated result; the caller maps `!ok` to an HTTP
  * error using the returned status/code/error.
  */
+/**
+ * Fold a locale-translated schema's option labels into the authored metaMap as
+ * matching synonyms. The export route and the import-template both surface the
+ * *translated* option label (e.g. 待规划 for `backlog`), so a re-imported file
+ * carries those strings — but `matchOption` compares against the schema the
+ * registry serves, which only knows the authored label. Appending each
+ * translated label as an extra `{ label, value }` entry keeps the authored
+ * label and code working while also accepting what the localized UI displays.
+ */
+export function mergeLocalizedOptionSynonyms(
+    metaMap: Map<string, ExportFieldMeta>,
+    localized: Map<string, ExportFieldMeta>,
+): void {
+    for (const [name, meta] of metaMap) {
+        const loc = localized.get(name);
+        if (!meta.options?.length || !loc?.options?.length) continue;
+        const known = new Set(
+            meta.options
+                .map((o) => (typeof o?.label === 'string' ? o.label.trim().toLowerCase() : ''))
+                .filter(Boolean),
+        );
+        const synonyms = loc.options.filter(
+            (o) =>
+                o
+                && typeof o.label === 'string'
+                && o.label.trim().length > 0
+                && o.value !== undefined
+                && !known.has(o.label.trim().toLowerCase()),
+        );
+        if (synonyms.length > 0) {
+            meta.options = [...meta.options, ...synonyms.map((o) => ({ label: o.label, value: o.value }))];
+        }
+    }
+}
+
 export async function prepareImportRequest(
     body: any,
-    opts: { p: any; objectName: string; environmentId?: string; maxRows: number },
+    opts: {
+        p: any;
+        objectName: string;
+        environmentId?: string;
+        maxRows: number;
+        /**
+         * Optional hook applying the request locale to a schema document (the
+         * REST server passes `translateMetaItem` bound to the request). Used to
+         * accept locale-translated option labels — the strings the localized
+         * export / import template actually contain — as select-cell synonyms.
+         */
+        localizeSchema?: (schema: any) => Promise<any> | any;
+    },
 ): Promise<PrepareImportResult> {
-    const { p, objectName, environmentId, maxRows } = opts;
+    const { p, objectName, environmentId, maxRows, localizeSchema } = opts;
     const dryRun = body?.dryRun === true;
 
     let writeMode: 'insert' | 'update' | 'upsert' =
@@ -325,6 +372,17 @@ export async function prepareImportRequest(
             schema = await p.getObjectSchema(objectName, environmentId);
         }
         metaMap = buildFieldMetaMap(schema);
+        // Round-trip i18n: also accept the locale-translated option labels the
+        // localized export / import template display (merged as synonyms; the
+        // authored label and option code keep working).
+        if (schema && typeof localizeSchema === 'function') {
+            try {
+                const localized = await localizeSchema(schema);
+                if (localized && localized !== schema) {
+                    mergeLocalizedOptionSynonyms(metaMap, buildFieldMetaMap(localized));
+                }
+            } catch { /* authored-only option matching */ }
+        }
     } catch { /* pass-through coercion */ }
 
     return {
diff --git a/packages/rest/src/rest-server.ts b/packages/rest/src/rest-server.ts
index 57dcec20b3..8d0555396d 100644
--- a/packages/rest/src/rest-server.ts
+++ b/packages/rest/src/rest-server.ts
@@ -3547,7 +3547,12 @@ export class RestServer {
                     // Parse + validate the payload (shared with the async job route).
                     // The synchronous path caps at 5k rows; larger files must use the
                     // async import-job endpoint.
-                    const prep = await prepareImportRequest(body, { p, objectName, environmentId, maxRows: 5000 });
+                    const prep = await prepareImportRequest(body, {
+                        p, objectName, environmentId, maxRows: 5000,
+                        // Accept locale-translated option labels (what the localized
+                        // export / import template contain) as select-cell synonyms.
+                        localizeSchema: (schema: any) => this.translateMetaItem(req, 'object', environmentId, schema),
+                    });
                     if (!prep.ok) {
                         if (prep.status === 413) prep.error += ' Use an async import job for larger files.';
                         res.status(prep.status).json({ code: prep.code, error: prep.error });
@@ -3611,7 +3616,11 @@ export class RestServer {
                     }
                     if (await this.enforceApiAccess(req, res, p, environmentId, 'import')) return;
 
-                    const prep = await prepareImportRequest(req.body ?? {}, { p, objectName, environmentId, maxRows: IMPORT_JOB_MAX_ROWS });
+                    const prep = await prepareImportRequest(req.body ?? {}, {
+                        p, objectName, environmentId, maxRows: IMPORT_JOB_MAX_ROWS,
+                        // Same round-trip i18n synonyms as the synchronous route.
+                        localizeSchema: (schema: any) => this.translateMetaItem(req, 'object', environmentId, schema),
+                    });
                     if (!prep.ok) {
                         if (prep.status === 413) prep.error += ` This is the async import ceiling; split the file into batches of ${IMPORT_JOB_MAX_ROWS}.`;
                         res.status(prep.status).json({ code: prep.code, error: prep.error });