@pactor-app/core 1.54.3 → 1.54.5

package/dist/index.cjs

@@ -25,6 +25,9 @@ __export(index_exports, {
   createI18nContext: () => createI18nContext,
   isDslFragmentPayload: () => isDslFragmentPayload,
   isDslSourceRef: () => isDslSourceRef,
+  isI18nDescriptor: () => isI18nDescriptor,
+  isLocalizedText: () => isLocalizedText,
+  lookupI18nMessage: () => lookupI18nMessage,
   resolveRootNodes: () => resolveRootNodes
 });
 module.exports = __toCommonJS(index_exports);
@@ -110,38 +113,55 @@ function isStringMap(value) {
   }
   return Object.values(value).every((v) => typeof v === "string");
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isI18nDescriptor(value) {
+  if (!isRecord(value) || !isRecord(value.$i18n)) {
+    return false;
+  }
+  const inner = value.$i18n;
+  if (typeof inner.key === "string") {
+    return true;
+  }
+  return isStringMap(inner.messages);
+}
+function isLocalizedText(value) {
+  return isRecord(value) && isRecord(value.$localizedText) && typeof value.$localizedText.template === "string";
+}
+function lookupI18nMessage(messages, locale, defaultLocale, key) {
+  const currentLocaleMessages = messages[locale];
+  if (isStringMap(currentLocaleMessages)) {
+    const value = currentLocaleMessages[key];
+    if (typeof value === "string") {
+      return { found: true, value, resolvedLocale: locale };
+    }
+  }
+  const flatValue = messages[key];
+  if (typeof flatValue === "string") {
+    return { found: true, value: flatValue };
+  }
+  if (locale !== defaultLocale) {
+    const defaultLocaleMessages = messages[defaultLocale];
+    if (isStringMap(defaultLocaleMessages)) {
+      const value = defaultLocaleMessages[key];
+      if (typeof value === "string") {
+        return { found: true, value, resolvedLocale: defaultLocale };
+      }
+    }
+  }
+  return { found: false, value: key };
+}
 function createI18nContext(options = {}) {
   const locale = options.locale ?? "zh-CN";
   const defaultLocale = options.defaultLocale ?? "zh-CN";
   const messages = options.messages ?? {};
   const t = (key, params) => {
-    let template;
-    const currentLocaleMessages = messages[locale];
-    if (isStringMap(currentLocaleMessages)) {
-      const value = currentLocaleMessages[key];
-      if (typeof value === "string") {
-        template = value;
-      }
-    }
-    if (template === void 0) {
-      const flatValue = messages[key];
-      if (typeof flatValue === "string") {
-        template = flatValue;
-      }
-    }
-    if (template === void 0 && locale !== defaultLocale) {
-      const defaultLocaleMessages = messages[defaultLocale];
-      if (isStringMap(defaultLocaleMessages)) {
-        const value = defaultLocaleMessages[key];
-        if (typeof value === "string") {
-          template = value;
-        }
-      }
-    }
-    if (template === void 0) {
+    const { found, value } = lookupI18nMessage(messages, locale, defaultLocale, key);
+    if (!found) {
       return key;
     }
-    return params ? interpolate(template, params) : template;
+    return params ? interpolate(value, params) : value;
   };
   return { locale, defaultLocale, t };
 }
@@ -152,5 +172,8 @@ function createI18nContext(options = {}) {
   createI18nContext,
   isDslFragmentPayload,
   isDslSourceRef,
+  isI18nDescriptor,
+  isLocalizedText,
+  lookupI18nMessage,
   resolveRootNodes
 });

package/dist/index.d.cts

@@ -285,6 +285,54 @@ type Locale = string;
 type I18nMessages = Record<string, string | Record<string, string>>;
 /** 参数插值值 */
 type I18nParams = Record<string, unknown>;
+/** 引用独立词条的可翻译描述（方式二：属性引用语言包） */
+interface I18nKeyRef {
+    key: string;
+    params?: Record<string, unknown>;
+    fallback?: string;
+}
+/** 内联多语言的可翻译描述（方式一：属性内联多语言） */
+interface I18nInlineMessages {
+    messages: Record<string, string>;
+    params?: Record<string, unknown>;
+    fallback?: string;
+}
+/**
+ * 作者态可翻译值。`$i18n` 包装对象不允许其他同级字段；
+ * 同一描述内 key 与 messages 互斥，由 schema 校验保证。
+ */
+interface I18nValueDescriptor {
+    $i18n: I18nKeyRef | I18nInlineMessages;
+}
+/** 下发态动态文本：语言选择已完成，模板插值在客户端完成 */
+interface LocalizedText {
+    $localizedText: {
+        template: string;
+        params?: Record<string, unknown>;
+    };
+}
+/** 单个语言包文件的内容 */
+interface MessageBundle {
+    version: string;
+    messages: Record<string, string>;
+}
+/** 语言包集合：服务端语言包 API 与本地 YAML 转换入口的统一输出结构 */
+interface MessageBundleSet {
+    appId: string;
+    locale: string;
+    release: string;
+    format: 'simple-v1';
+    bundles: Record<string, MessageBundle>;
+}
+/** 页面/片段下发时附带的本地化元信息 */
+interface LocalizationMeta {
+    locale: string;
+    defaultLocale: string;
+    source?: string;
+    explicit?: boolean;
+    release?: string;
+    bundleVersions?: Record<string, string>;
+}
 /**
  * i18n 上下文：暴露给 RuntimeContext 与表达式引擎。
  * `t` 为翻译函数，支持参数插值与回退。
@@ -303,6 +351,27 @@ interface CreateI18nOptions {
     defaultLocale?: Locale;
     messages?: I18nMessages;
 }
+/** 判断是否为作者态 `$i18n` 翻译描述 */
+declare function isI18nDescriptor(value: unknown): value is I18nValueDescriptor;
+/** 判断是否为下发态 `$localizedText` 动态文本 */
+declare function isLocalizedText(value: unknown): value is LocalizedText;
+/** 词条查找结果 */
+interface I18nLookupResult {
+    /** 是否命中词条（空字符串译文视为命中） */
+    found: boolean;
+    /** 命中时为译文原文（未插值），未命中时为 key 本身 */
+    value: string;
+    /** 命中的 locale 分组；扁平 key 命中或未命中时为 undefined */
+    resolvedLocale?: Locale;
+}
+/**
+ * 显式命中的词条查找。
+ *
+ * 查找顺序：当前 locale 分组 → 扁平 key → defaultLocale 分组 → 未命中。
+ * 空字符串视为命中（found=true），不能用 `value === key` 判断命中，
+ * 因为合法译文可能恰好等于 key。
+ */
+declare function lookupI18nMessage(messages: I18nMessages, locale: Locale, defaultLocale: Locale, key: string): I18nLookupResult;
 /**
  * 创建翻译函数。
  *
@@ -315,4 +384,4 @@ interface CreateI18nOptions {
  */
 declare function createI18nContext(options?: CreateI18nOptions): I18nContext;
 
-export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslFragmentPayload, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslFragmentPayload, isDslSourceRef, resolveRootNodes };
+export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslFragmentPayload, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nInlineMessages, type I18nKeyRef, type I18nLookupResult, type I18nMessages, type I18nParams, type I18nValueDescriptor, type LifecycleConfig, type LifecycleEventName, type Locale, type LocalizationMeta, type LocalizedText, type MessageBundle, type MessageBundleSet, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslFragmentPayload, isDslSourceRef, isI18nDescriptor, isLocalizedText, lookupI18nMessage, resolveRootNodes };

package/dist/index.d.ts

@@ -285,6 +285,54 @@ type Locale = string;
 type I18nMessages = Record<string, string | Record<string, string>>;
 /** 参数插值值 */
 type I18nParams = Record<string, unknown>;
+/** 引用独立词条的可翻译描述（方式二：属性引用语言包） */
+interface I18nKeyRef {
+    key: string;
+    params?: Record<string, unknown>;
+    fallback?: string;
+}
+/** 内联多语言的可翻译描述（方式一：属性内联多语言） */
+interface I18nInlineMessages {
+    messages: Record<string, string>;
+    params?: Record<string, unknown>;
+    fallback?: string;
+}
+/**
+ * 作者态可翻译值。`$i18n` 包装对象不允许其他同级字段；
+ * 同一描述内 key 与 messages 互斥，由 schema 校验保证。
+ */
+interface I18nValueDescriptor {
+    $i18n: I18nKeyRef | I18nInlineMessages;
+}
+/** 下发态动态文本：语言选择已完成，模板插值在客户端完成 */
+interface LocalizedText {
+    $localizedText: {
+        template: string;
+        params?: Record<string, unknown>;
+    };
+}
+/** 单个语言包文件的内容 */
+interface MessageBundle {
+    version: string;
+    messages: Record<string, string>;
+}
+/** 语言包集合：服务端语言包 API 与本地 YAML 转换入口的统一输出结构 */
+interface MessageBundleSet {
+    appId: string;
+    locale: string;
+    release: string;
+    format: 'simple-v1';
+    bundles: Record<string, MessageBundle>;
+}
+/** 页面/片段下发时附带的本地化元信息 */
+interface LocalizationMeta {
+    locale: string;
+    defaultLocale: string;
+    source?: string;
+    explicit?: boolean;
+    release?: string;
+    bundleVersions?: Record<string, string>;
+}
 /**
  * i18n 上下文：暴露给 RuntimeContext 与表达式引擎。
  * `t` 为翻译函数，支持参数插值与回退。
@@ -303,6 +351,27 @@ interface CreateI18nOptions {
     defaultLocale?: Locale;
     messages?: I18nMessages;
 }
+/** 判断是否为作者态 `$i18n` 翻译描述 */
+declare function isI18nDescriptor(value: unknown): value is I18nValueDescriptor;
+/** 判断是否为下发态 `$localizedText` 动态文本 */
+declare function isLocalizedText(value: unknown): value is LocalizedText;
+/** 词条查找结果 */
+interface I18nLookupResult {
+    /** 是否命中词条（空字符串译文视为命中） */
+    found: boolean;
+    /** 命中时为译文原文（未插值），未命中时为 key 本身 */
+    value: string;
+    /** 命中的 locale 分组；扁平 key 命中或未命中时为 undefined */
+    resolvedLocale?: Locale;
+}
+/**
+ * 显式命中的词条查找。
+ *
+ * 查找顺序：当前 locale 分组 → 扁平 key → defaultLocale 分组 → 未命中。
+ * 空字符串视为命中（found=true），不能用 `value === key` 判断命中，
+ * 因为合法译文可能恰好等于 key。
+ */
+declare function lookupI18nMessage(messages: I18nMessages, locale: Locale, defaultLocale: Locale, key: string): I18nLookupResult;
 /**
  * 创建翻译函数。
  *
@@ -315,4 +384,4 @@ interface CreateI18nOptions {
  */
 declare function createI18nContext(options?: CreateI18nOptions): I18nContext;
 
-export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslFragmentPayload, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslFragmentPayload, isDslSourceRef, resolveRootNodes };
+export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslFragmentPayload, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nInlineMessages, type I18nKeyRef, type I18nLookupResult, type I18nMessages, type I18nParams, type I18nValueDescriptor, type LifecycleConfig, type LifecycleEventName, type Locale, type LocalizationMeta, type LocalizedText, type MessageBundle, type MessageBundleSet, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslFragmentPayload, isDslSourceRef, isI18nDescriptor, isLocalizedText, lookupI18nMessage, resolveRootNodes };

package/dist/index.js

@@ -79,38 +79,55 @@ function isStringMap(value) {
   }
   return Object.values(value).every((v) => typeof v === "string");
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isI18nDescriptor(value) {
+  if (!isRecord(value) || !isRecord(value.$i18n)) {
+    return false;
+  }
+  const inner = value.$i18n;
+  if (typeof inner.key === "string") {
+    return true;
+  }
+  return isStringMap(inner.messages);
+}
+function isLocalizedText(value) {
+  return isRecord(value) && isRecord(value.$localizedText) && typeof value.$localizedText.template === "string";
+}
+function lookupI18nMessage(messages, locale, defaultLocale, key) {
+  const currentLocaleMessages = messages[locale];
+  if (isStringMap(currentLocaleMessages)) {
+    const value = currentLocaleMessages[key];
+    if (typeof value === "string") {
+      return { found: true, value, resolvedLocale: locale };
+    }
+  }
+  const flatValue = messages[key];
+  if (typeof flatValue === "string") {
+    return { found: true, value: flatValue };
+  }
+  if (locale !== defaultLocale) {
+    const defaultLocaleMessages = messages[defaultLocale];
+    if (isStringMap(defaultLocaleMessages)) {
+      const value = defaultLocaleMessages[key];
+      if (typeof value === "string") {
+        return { found: true, value, resolvedLocale: defaultLocale };
+      }
+    }
+  }
+  return { found: false, value: key };
+}
 function createI18nContext(options = {}) {
   const locale = options.locale ?? "zh-CN";
   const defaultLocale = options.defaultLocale ?? "zh-CN";
   const messages = options.messages ?? {};
   const t = (key, params) => {
-    let template;
-    const currentLocaleMessages = messages[locale];
-    if (isStringMap(currentLocaleMessages)) {
-      const value = currentLocaleMessages[key];
-      if (typeof value === "string") {
-        template = value;
-      }
-    }
-    if (template === void 0) {
-      const flatValue = messages[key];
-      if (typeof flatValue === "string") {
-        template = flatValue;
-      }
-    }
-    if (template === void 0 && locale !== defaultLocale) {
-      const defaultLocaleMessages = messages[defaultLocale];
-      if (isStringMap(defaultLocaleMessages)) {
-        const value = defaultLocaleMessages[key];
-        if (typeof value === "string") {
-          template = value;
-        }
-      }
-    }
-    if (template === void 0) {
+    const { found, value } = lookupI18nMessage(messages, locale, defaultLocale, key);
+    if (!found) {
       return key;
     }
-    return params ? interpolate(template, params) : template;
+    return params ? interpolate(value, params) : value;
   };
   return { locale, defaultLocale, t };
 }
@@ -120,5 +137,8 @@ export {
   createI18nContext,
   isDslFragmentPayload,
   isDslSourceRef,
+  isI18nDescriptor,
+  isLocalizedText,
+  lookupI18nMessage,
   resolveRootNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/core",
-  "version": "1.54.3",
+  "version": "1.54.5",
   "description": "Pactor core: DSL protocol types and generic Registry (React-free, zero dependencies)",
   "keywords": [
     "pactor",