@yumerijs/core 3.0.4 → 3.0.6

package/dist/config.d.ts

@@ -1,14 +1,17 @@
+import type { I18n } from './i18n.js';
 export declare function fallback<T>(schema: Schema<T>, config: T): T;
 export declare class Schema<T = any> {
     _type?: T;
     type: string;
     isRequired?: boolean;
     description?: string;
+    /** 说明文字对应的 i18n key，由 key() 设置 */
+    i18nKey?: string;
     defaultValue?: any;
     properties?: Record<string, Schema<any>>;
     items?: Schema<any>;
     enum?: T[];
-    constructor(definition: Omit<Schema<T>, '_type' | 'required' | 'default'> & {
+    constructor(definition: Omit<Schema<T>, '_type' | 'required' | 'default' | 'key'> & {
         enum?: T[];
     });
     static string(description?: string): Schema<string>;
@@ -23,8 +26,31 @@ export declare class Schema<T = any> {
     }, description?: string): Schema<T & U>;
     static enum<L extends string | number>(values: L[], description?: string): Schema<L>;
     required(this: this): this;
+    /**
+     * 绑定说明文字的 i18n key
+     *
+     * 绑定后该配置项的说明文字会按请求语言从内置 I18n 里解析；
+     * key 未注册或没命中任何语言时，仍然显示 description 原文，
+     * 所以不接入 i18n 的插件不受影响。
+     *
+     * @param name 翻译 key，建议用 `插件名.config.配置项` 形式的命名空间避免全局撞车
+     */
+    key(name: string): this;
     default(this: this, value: T): this;
 }
+/**
+ * 解析 schema 说明文字要显示的文本
+ *
+ * 没绑定 i18n key、或 key 没有命中任何语言时一律退回 description 原文，
+ * 因此插件的显示效果在未接入 i18n 时与之前完全一致。
+ * 绑定了 key 的配置项可以不写 description，此时直接使用译文；
+ * 译文和原文都没有时返回 undefined，由调用方回落到字段名。
+ *
+ * @param schema schema 节点
+ * @param i18n i18n 实例，未初始化时按原文处理
+ * @param langs 语言优先级列表，通常是 session.request.languages
+ */
+export declare function resolveDescription(schema: Schema<any>, i18n?: I18n, langs?: string[]): string | undefined;
 export { Schema as ConfigSchema };
 export interface Config {
     [key: string]: any;

package/dist/config.js

@@ -30,6 +30,8 @@ export class Schema {
     type;
     isRequired;
     description;
+    /** 说明文字对应的 i18n key，由 key() 设置 */
+    i18nKey;
     defaultValue;
     properties;
     items;
@@ -38,6 +40,7 @@ export class Schema {
         this.type = definition.type;
         this.isRequired = definition.isRequired;
         this.description = definition.description;
+        this.i18nKey = definition.i18nKey;
         this.defaultValue = definition.defaultValue;
         this.properties = definition.properties;
         this.items = definition.items;
@@ -70,9 +73,46 @@ export class Schema {
         this.isRequired = true;
         return this;
     }
+    /**
+     * 绑定说明文字的 i18n key
+     *
+     * 绑定后该配置项的说明文字会按请求语言从内置 I18n 里解析；
+     * key 未注册或没命中任何语言时，仍然显示 description 原文，
+     * 所以不接入 i18n 的插件不受影响。
+     *
+     * @param name 翻译 key，建议用 `插件名.config.配置项` 形式的命名空间避免全局撞车
+     */
+    key(name) {
+        this.i18nKey = name;
+        return this;
+    }
     default(value) {
         this.defaultValue = value;
         return this;
     }
 }
+/**
+ * 解析 schema 说明文字要显示的文本
+ *
+ * 没绑定 i18n key、或 key 没有命中任何语言时一律退回 description 原文，
+ * 因此插件的显示效果在未接入 i18n 时与之前完全一致。
+ * 绑定了 key 的配置项可以不写 description，此时直接使用译文；
+ * 译文和原文都没有时返回 undefined，由调用方回落到字段名。
+ *
+ * @param schema schema 节点
+ * @param i18n i18n 实例，未初始化时按原文处理
+ * @param langs 语言优先级列表，通常是 session.request.languages
+ */
+export function resolveDescription(schema, i18n, langs) {
+    if (!schema)
+        return undefined;
+    const key = schema.i18nKey;
+    if (key && i18n) {
+        const translated = i18n.get(key, langs);
+        // I18n.get 在没命中任何语言时会原样返回 key，借此判断是否真的翻译到了
+        if (translated !== key)
+            return translated;
+    }
+    return schema.description;
+}
 export { Schema as ConfigSchema };

package/dist/core.d.ts

@@ -15,6 +15,7 @@ export interface Plugin {
     apply?: (ctx: Context, config: Config) => Promise<void> | void;
     disable?: (ctx: Context) => Promise<void> | void;
     depend?: Array<string>;
+    optional?: Array<string>;
     provide?: Array<string>;
     render?: string;
     config?: Schema<any>;
@@ -25,6 +26,7 @@ type PluginModuleLike = Plugin | PluginConstructor | ((ctx: Context, config: Con
     apply?: ((ctx: Context, config: Config) => Promise<void> | void);
     disable?: (ctx: Context) => Promise<void> | void;
     depend?: Array<string>;
+    optional?: Array<string>;
     provide?: Array<string>;
     render?: string;
     config?: Schema<any>;
@@ -39,6 +41,33 @@ export interface CoreOptions {
     skipcheckUpdates?: boolean;
 }
 export declare const coreConfigSchema: Schema<CoreOptions>;
+/** 核心配置项的内置文案，随 i18n 实例初始化自动注册 */
+export declare const coreI18n: {
+    'core.config.port': {
+        zh: string;
+        en: string;
+    };
+    'core.config.host': {
+        zh: string;
+        en: string;
+    };
+    'core.config.enableCors': {
+        zh: string;
+        en: string;
+    };
+    'core.config.enableWs': {
+        zh: string;
+        en: string;
+    };
+    'core.config.lang': {
+        zh: string;
+        en: string;
+    };
+    'core.config.skipcheckUpdates': {
+        zh: string;
+        en: string;
+    };
+};
 export declare const enum PluginStatus {
     ENABLED = "enabled",
     DISABLED = "disabled",
@@ -58,11 +87,22 @@ export declare class Core {
     hooks: Record<string, Hook>;
     coreConfig: CoreOptions;
     server: CoreServer;
-    i18n: I18n;
+    private _i18n?;
     loader: any;
     storage: SessionStorageProcessor;
     renderers: Map<string, IRenderer>;
     pluginRenderers: Map<string, string>;
+    /**
+     * i18n 实例
+     *
+     * 未赋值时按 core 配置的 lang 惰性创建，赋值时自动注册核心内置文案，
+     * 这样无论 i18n 是被 loader 创建还是被直接使用 core 的场景创建，
+     * coreConfigSchema 的说明文字都能被翻译到。
+     */
+    get i18n(): I18n;
+    set i18n(value: I18n);
+    /** 设置 i18n 实例并注册核心内置文案 */
+    setI18n(i18n: I18n): void;
     constructor(loader?: any, coreConfig?: CoreOptions, loggersetCore?: boolean, splash?: boolean);
     private checkUpdate;
     addRenderer(renderer: IRenderer): void;

package/dist/core.js

@@ -4,6 +4,7 @@ import { Logger } from './logger.js';
 import { Route } from './route.js';
 import { Hook } from './hook.js';
 import { Server as CoreServer } from './server.js';
+import { I18n } from './i18n.js';
 import { SessionStorageProcessor } from './storage.js';
 import * as fs from 'fs';
 import semver from 'semver';
@@ -19,6 +20,8 @@ function mergePluginMeta(target, source) {
         return target;
     if (target.depend == null && Array.isArray(source.depend))
         target.depend = source.depend;
+    if (target.optional == null && Array.isArray(source.optional))
+        target.optional = source.optional;
     if (target.provide == null && Array.isArray(source.provide))
         target.provide = source.provide;
     if (target.render == null && typeof source.render === 'string')
@@ -51,13 +54,22 @@ export function resolvePluginModule(module, context, config) {
     return plugin;
 }
 export const coreConfigSchema = Schema.object({
-    port: Schema.number('监听端口').default(14510),
-    host: Schema.string('监听地址').default('0.0.0.0'),
-    enableCors: Schema.boolean('启用跨域').default(false),
-    enableWs: Schema.boolean('启用 WebSocket').default(false),
-    lang: Schema.array(Schema.string(), '语言列表').default(['zh', 'en']),
-    skipcheckUpdates: Schema.boolean('启动时检查更新').default(false)
+    port: Schema.number('监听端口').key('core.config.port').default(14510),
+    host: Schema.string('监听地址').key('core.config.host').default('0.0.0.0'),
+    enableCors: Schema.boolean('启用跨域').key('core.config.enableCors').default(false),
+    enableWs: Schema.boolean('启用 WebSocket').key('core.config.enableWs').default(false),
+    lang: Schema.array(Schema.string(), '语言列表').key('core.config.lang').default(['zh', 'en']),
+    skipcheckUpdates: Schema.boolean('启动时检查更新').key('core.config.skipcheckUpdates').default(false)
 });
+/** 核心配置项的内置文案，随 i18n 实例初始化自动注册 */
+export const coreI18n = {
+    'core.config.port': { zh: '监听端口', en: 'Listening port' },
+    'core.config.host': { zh: '监听地址', en: 'Listening address' },
+    'core.config.enableCors': { zh: '启用跨域', en: 'Enable CORS' },
+    'core.config.enableWs': { zh: '启用 WebSocket', en: 'Enable WebSocket' },
+    'core.config.lang': { zh: '语言列表', en: 'Language list' },
+    'core.config.skipcheckUpdates': { zh: '启动时检查更新', en: 'Check for updates on startup' }
+};
 export class Core {
     emitter = new EventEmitter();
     components = {};
@@ -68,11 +80,32 @@ export class Core {
     hooks = {};
     coreConfig;
     server;
-    i18n;
+    _i18n;
     loader;
     storage = new SessionStorageProcessor();
     renderers = new Map();
     pluginRenderers = new Map(); // Stores which plugin uses which renderer
+    /**
+     * i18n 实例
+     *
+     * 未赋值时按 core 配置的 lang 惰性创建，赋值时自动注册核心内置文案，
+     * 这样无论 i18n 是被 loader 创建还是被直接使用 core 的场景创建，
+     * coreConfigSchema 的说明文字都能被翻译到。
+     */
+    get i18n() {
+        if (!this._i18n) {
+            this.setI18n(new I18n(this.coreConfig?.lang || ['zh', 'en']));
+        }
+        return this._i18n;
+    }
+    set i18n(value) {
+        this.setI18n(value);
+    }
+    /** 设置 i18n 实例并注册核心内置文案 */
+    setI18n(i18n) {
+        this._i18n = i18n;
+        i18n.register(coreI18n);
+    }
     constructor(loader, coreConfig = {}, loggersetCore = true, splash = true) {
         this.coreConfig = fallback(coreConfigSchema, coreConfig);
         this.loader = loader;
@@ -144,9 +177,9 @@ export class Core {
         const plugin = resolvePluginModule(module, context, config);
         const shortName = this.getShortPluginName(context.pluginname);
         context.module = plugin;
-        // 自动依赖注入
-        const depend = plugin.depend || [];
-        for (const name of depend) {
+        // 自动依赖注入：必需依赖始终由 loader 保证，optional 仅在已提供时注入。
+        const dependencies = [...(plugin.depend || []), ...(plugin.optional || [])];
+        for (const name of dependencies) {
             const component = this.getComponent(name);
             if (component) {
                 context.inject(name, component);

package/dist/i18n.d.ts

@@ -10,6 +10,11 @@ export declare class I18n {
     constructor(fallback?: string[]);
     register(key: string | Record<string, any>, lang?: Record<string, string>): void;
     setFallback(fallback: string[]): void;
+    /**
+     * 判断一个值是否是语言表，即 `{ zh: '...', en: '...' }` 这种值全为字符串的对象。
+     * 这里不硬编码具体语言码，因为 fallback 列表可由 coreConfig.lang 配置。
+     */
+    private isLocaleMap;
     private flattenAndRegister;
     isRegistered(key: string): boolean;
     delete(key: string): void;

package/dist/i18n.js

@@ -22,17 +22,27 @@ export class I18n {
     setFallback(fallback) {
         this.fallback = fallback;
     }
+    /**
+     * 判断一个值是否是语言表，即 `{ zh: '...', en: '...' }` 这种值全为字符串的对象。
+     * 这里不硬编码具体语言码，因为 fallback 列表可由 coreConfig.lang 配置。
+     */
+    isLocaleMap(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return false;
+        const values = Object.values(value);
+        return values.length > 0 && values.every(v => typeof v === 'string');
+    }
     flattenAndRegister(obj, prefix = '') {
         for (const [k, v] of Object.entries(obj)) {
             const fullKey = prefix ? `${prefix}.${k}` : k;
-            if (typeof v === 'object' && !('zh' in v || 'en' in v)) {
-                this.flattenAndRegister(v, fullKey);
-            }
-            else if (typeof v === 'object') {
+            if (this.isLocaleMap(v)) {
                 if (!this.data[fullKey])
                     this.data[fullKey] = {};
                 Object.assign(this.data[fullKey], v);
             }
+            else if (v && typeof v === 'object') {
+                this.flattenAndRegister(v, fullKey);
+            }
         }
     }
     isRegistered(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yumerijs/core",
-  "version": "3.0.4",
+  "version": "3.0.6",
   "description": "Core module for yumeri",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",