mm_lang 1.0.1 → 2.0.0

package/README.md

@@ -1,22 +1,29 @@
 # mm_lang
 
-超级美眉多语言/语言包模块，提供 `Lang` 类作为国际化（i18n）核心能力：按语言字典取值、`a.b` 层级键解析、多级回退机制（当前语言 → 基础语言 → 默认语言）、复数形式、占位符参数替换，以及日期与数字的本地化格式化。行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量。
+超级美眉多语言模块。融合了原 `mm_lang`（i18n 行为）与 `mm_langs`（语言存储）两个模块：`Lang` 负责翻译行为，`Langs` 负责键值存储与 JSON 文件持久化，两者组合实现"动作与数据分离"。
+
+> **迁移提示**：`mm_langs` 已合并至本模块，其 `Langs` 类与 `langsAdmin` 从 `mm_lang` 直接导出，API 与报错文案保持不变。原 `require('mm_langs')` 改为 `require('mm_lang')` 即可。
 
 ## 项目信息
 
-- **当前版本**: 1.0.0
-- **更新日期**: 2026-10-04
+- **当前版本**: 2.0.0
+- **更新日期**: 2026-10-30
 - **Gitee地址**: https://gitee.com/qiuwenwu91/mm_lang
-- **依赖**: 无第三方依赖（纯 Node.js 实现）
+- **依赖**: `mm_corejs`（管理器）、`mm_kv_store`（键值存储基类）
+
+## 模块结构
+
+| 文件 | 职责 |
+|---|---|
+| `lib/lang.js` | 行为侧：取词、回退链、复数、格式化，**不做文件 IO** |
+| `lib/langs.js` | 数据侧：string→string 键值、JSON 文件 save/load、值类型校验，**不感知词条嵌套语义** |
+| `lib/store.js` | 适配层：嵌套词条字典 ↔ 扁平键值互转、存储实例装配 |
 
 ## 特点
 
-- 零依赖，内置 `zh_cn` 与 `en` 两种语言的默认词条容器
-- 支持 `a.b.c` 形式的层级键取值与写入
-- 带回退机制的取值链：当前语言 → 基础语言（如 `en-US` 回退到 `en`）→ 默认语言
-- 复数形式支持：`tc` 按数量选择词条数组索引，内置英文/中文复数规则，可通过 `registerPlural` 自定义
-- 占位符替换：`get`/`t` 支持 `{0}`、`{1}` 等；`tc` 支持 `{count}` 及 `{1}`、`{2}` 等
-- 附带日期格式化（`formatDate`）与数字格式化（`formatNumber`，可配置小数位数与千分位/小数分隔符）
+- **行为侧**：零文件 IO，`zh_cn`/`en` 内置复数规则，`a.b.c` 层级键，回退链（当前语言 → 基础语言 → 默认语言），占位符替换，日期/数字本地化格式化
+- **数据侧**：键和值都只能是字符串，支持覆盖、删除、判断存在、取副本、清空、JSON 文件持久化
+- **组合使用**：`Lang` 配置 `file` 即获得持久化能力；也可注入自定义 `store` 实例替换存储后端
 
 ## 安装
 
@@ -24,35 +31,38 @@
 npm install mm_lang
 ```
 
-## 基本使用
+## 快速开始
 
 ```javascript
-const { Lang } = require('mm_lang');
+const { Lang, Langs, langAdmin } = require('mm_lang');
 
+// 纯内存翻译
 const lang = new Lang({
-  zh_cn: {
-    common: { hello: '你好，{0}！' },
-    apple: ['一个苹果', '{count}个苹果']
-  },
-  en: {
-    common: { hello: 'Hello, {0}!' },
-    apple: ['one apple', '{count} apples']
-  },
-  default: 'zh_cn',
-  fallback: true
+  zh_cn: { common: { hello: '你好，{0}！' }, apple: ['一个苹果', '{count}个苹果'] },
+  en: { common: { hello: 'Hello, {0}!' }, apple: ['one apple', '{count} apples'] },
+  default: 'zh_cn'
 });
-
-console.log(lang.get('common.hello', '美眉'));   // 你好，美眉！
-console.log(lang.setLang('en'));                  // en
-console.log(lang.t('common.hello', 'MM'));        // Hello, MM!
-console.log(lang.tc('apple', 3));                 // 3 apples
+console.log(lang.get('common.hello', '美眉'));  // 你好，美眉！
+lang.setLang('en');
+console.log(lang.t('common.hello', 'MM'));      // Hello, MM!
+console.log(lang.tc('apple', 3));               // 3 apples
+
+// 带持久化：配置 file 后自动创建 Langs 存储实例
+const persisted = langAdmin('shop', { file: './data/lang.json', default: 'zh_cn' });
+persisted.load();                 // 启动时从文件恢复词条
+persisted.set('nav.home', '首页');
+persisted.save();                 // 扁平化为 "zh_cn.nav.home": "首页" 落盘
+
+// 只用存储（原 mm_langs 用法）
+const langs = new Langs({ file: './data/map.json' });
+langs.set('en', 'english').save();
 ```
 
 ## API 说明
 
-### 构造 `new Lang(dict)`
+### 行为侧 `Lang`
 
-`dict` 为语言包字典对象，各字段与默认值：
+#### 构造 `new Lang(config)`
 
 | 配置项 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -60,37 +70,77 @@ console.log(lang.tc('apple', 3));                 // 3 apples
 | `en` | `Object` | `{}` | 英文词条字典 |
 | `default` | `String` | `'zh_cn'` | 默认语言代码，同时作为初始当前语言 |
 | `fallback` | `Boolean` | `true` | 是否启用回退机制 |
-| `locale` | `Object` | `{ zh: 'zh_cn', en: 'en' }` | 完整语言代码到基础语言代码的映射（与默认值合并） |
+| `locale` | `Object` | `{ zh: 'zh_cn', en: 'en' }` | 完整语言代码到基础语言代码的映射 |
+| `file` | `String` | `''` | 持久化文件路径，配置后自动创建 Langs 存储实例 |
+| `store` | `Langs` | `undefined` | 注入的存储实例（鸭子类型），优先于 `file` |
+| `silent` | `Boolean` | `false` | 是否静默缺失词条/存储异常日志（上层自带日志体系时开启，如 mm_tpl） |
 
-实例属性：`config`（语言包配置）、`rules`（复数规则表）、`now`（当前语言代码）、`locale`（区域映射表）。
+实例属性：`config`（词条字典）、`rules`（复数规则）、`now`（当前语言）、`locale`（区域映射）、`file`（持久化路径）、`store`（存储实例或 `null`）。
 
-### 取值与翻译
+#### 取值与翻译
 
 | 方法 | 签名 | 返回值 | 说明 |
 | --- | --- | --- | --- |
-| get | `get(key, ...param)` | `String` | 获取翻译文本，支持 `a.b` 层级键；`param` 依次替换 `{0}`、`{1}` 等占位符；`key` 非字符串时抛 `TypeError` |
+| get | `get(key, ...param)` | `String` | 取翻译文本，支持 `a.b` 层级键；`param` 依次替换 `{0}`、`{1}` 等 |
 | t | `t(key, ...param)` | `String` | `get` 的别名 |
-| tc | `tc(key, count, ...param)` | `String` | 翻译带复数形式的文本：词条值为数组时按当前语言复数规则取索引，先替换 `{count}`，再用 `param` 依次替换 `{1}`、`{2}` 等；`key` 非字符串或 `count` 非数字时抛 `TypeError` |
+| tc | `tc(key, count, ...param)` | `String` | 复数形式取词：数组词条按当前语言规则取索引，先替换 `{count}`，再替换 `{1}`、`{2}` 等 |
 
-### 语言管理
+#### 语言管理
 
 | 方法 | 签名 | 返回值 | 说明 |
 | --- | --- | --- | --- |
-| setLang | `setLang(lang)` | `String` | 切换语言；找不到时先尝试基础语言映射，仍失败则输出错误日志并返回当前语言 |
-| getLangs | `getLangs()` | `Array<String>` | 获取支持的语言代码列表（排除 `default`、`fallback`、`options` 等非词条键） |
-| isSupported | `isSupported(lang)` | `Boolean` | 检查语言是否支持（含基础语言映射） |
-| del | `del(lang)` | `Boolean` | 删除指定语言配置，删除成功返回 `true` |
-| set | `set(key, val)` | `any` | 向当前语言写入键值，支持 `a.b` 层级键（中间层自动创建），返回设置的值 |
-| registerPlural | `registerPlural(lang, rule)` | `Boolean` | 注册语言复数规则；`rule(count)` 需返回形式索引（数字），参数类型不符时抛 `TypeError` |
+| setLang | `setLang(lang)` | `String` | 切换语言；找不到时先尝试基础语言映射，仍失败记日志并保持当前语言 |
+| getLangs | `getLangs()` | `Array<String>` | 支持的语言列表（排除 `default`、`fallback`、`locale`、`options`、`file`、`store`） |
+| isSupported | `isSupported(lang)` | `Boolean` | 语言是否支持（含基础语言映射，控制键恒为 false） |
+| del | `del(lang)` | `Boolean` | 删除指定语言配置 |
+| set | `set(key, val)` | `any` | 向当前语言写入词条，支持 `a.b` 层级键 |
+| registerPlural | `registerPlural(lang, rule)` | `Boolean` | 注册复数规则，`rule(count)` 返回形式索引 |
 
-### 格式化
+#### 持久化
 
 | 方法 | 签名 | 返回值 | 说明 |
 | --- | --- | --- | --- |
-| formatDate | `formatDate(dt, format)` | `String` | 格式化日期；`dt` 为 `Date` 或时间戳，`format` 默认 `YYYY-MM-DD hh:mm:ss`，支持 `YYYY/yyyy`、`MM`、`DD/dd`、`HH/hh`、`mm`、`ss` 标记；`dt` 为空或无效日期时抛 `TypeError` |
-| formatNumber | `formatNumber(num, options)` | `String` | 格式化数字；`options` 支持 `decimals`（小数位数，默认 2）、`decimal_separator`（小数分隔符，默认 `.`）、`thousands_separator`（千分位分隔符，默认 `,`）；`num` 非有效数字时抛 `TypeError` |
+| save | `save(file?)` | `Boolean` | 词条扁平化后经存储实例落盘；无存储实例返回 `false`（不抛异常） |
+| load | `load(file?)` | `Boolean` | 从存储实例读取并还原为嵌套字典合并进 `config`，文件中的词条优先；失败返回 `false` 且不改动内存词条 |
+
+落盘格式为 `语言代码.层级键 → 文本` 的 string→string 键值，例如：
 
-> 另有 `_getVal`、`_getFrom`、`_getBase`、`_set`、`_log` 等下划线前缀的内部私有方法，不建议外部调用。
+```json
+{
+  "zh_cn.nav.home": "首页",
+  "zh_cn.apple": "\u0001[\"一个苹果\",\"{count}个苹果\"]"
+}
+```
+
+> 复数等数组词条以 `\u0001` 前缀 + JSON 文本编码，仍满足存储的 string→string 约束，加载时自动还原为数组。`default`、`fallback`、`locale` 等控制键不参与持久化。
+
+#### 格式化
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| formatDate | `formatDate(dt, format)` | `String` | 默认格式 `YYYY-MM-DD hh:mm:ss`，支持 `YYYY/yyyy`、`MM`、`DD/dd`、`HH/hh`、`mm`、`ss` |
+| formatNumber | `formatNumber(num, options)` | `String` | `options` 支持 `decimals`（默认 2）、`decimal_separator`、`thousands_separator` |
+
+### 数据侧 `Langs`
+
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| set | 设置键值（值必须为字符串） | key, value | Langs |
+| get | 获取值 | key | string\|undefined |
+| del | 删除键 | key | boolean |
+| has | 判断键是否存在 | key | boolean |
+| list | 获取键值表副本 | - | object |
+| clear | 清空所有键 | - | Langs |
+| save | 保存到持久化文件 | - | boolean |
+| load | 从持久化文件加载（逐项校验值类型） | - | boolean |
+
+### 管理器
+
+| 方法 | 说明 |
+|---|---|
+| langAdmin(scope, config) | 按作用域获取 `Lang` 实例（相同作用域返回同一实例），缺省 `os` |
+| langsAdmin(scope, config) | 按作用域获取 `Langs` 实例，缺省 `os` |
+| admin / langs_admin | 对应的 `Admin` 实例 |
 
 ## 使用示例
 
@@ -102,8 +152,7 @@ const { Lang } = require('mm_lang');
 const lang = new Lang({
   zh_cn: { nav: { home: '首页' } },
   en: { nav: { home: 'Home', about: 'About' } },
-  default: 'en',
-  fallback: true
+  default: 'en'
 });
 
 lang.setLang('zh_cn');
@@ -115,12 +164,7 @@ console.log(lang.get('nav.about')); // 中文缺失，回退到默认语言 en
 ```javascript
 const { Lang } = require('mm_lang');
 
-const lang = new Lang({
-  ru: { apple: ['яблоко', 'яблока', 'яблок'] },
-  default: 'ru'
-});
-
-// 俄语复数规则：按数量返回三种形式之一的索引
+const lang = new Lang({ ru: { apple: ['яблоко', 'яблока', 'яблок'] }, default: 'ru' });
 lang.registerPlural('ru', function (count) {
   const n10 = count % 10, n100 = count % 100;
   if (n10 === 1 && n100 !== 11) return 0;
@@ -133,16 +177,32 @@ console.log(lang.tc('apple', 3));  // яблока
 console.log(lang.tc('apple', 11)); // яблок
 ```
 
-### 场景三：本地化格式化
+### 场景三：注入自定义存储
 
 ```javascript
-const { Lang } = require('mm_lang');
+const { Lang, Langs } = require('mm_lang');
 
-const lang = new Lang();
-console.log(lang.formatDate(new Date(2026, 9, 4), 'YYYY年MM月DD日')); // 2026年10月04日
-console.log(lang.formatNumber(1234567.891, {
-  decimals: 2,
-  decimal_separator: ',',
-  thousands_separator: '.'
-})); // 1.234.567,89
+// 任何具备 set/get/list/save/load 的对象都可作为存储
+const store = new Langs({ file: './data/custom.json' });
+const lang = new Lang({ store, zh_cn: { hello: '你好' } });
+lang.save();
 ```
+
+## 目录结构
+
+```
+mm_lang/
+├── index.js       入口：导出 Lang / Langs / admin / langs_admin / langAdmin / langsAdmin
+├── lib/
+│   ├── lang.js    行为侧
+│   ├── langs.js   数据侧
+│   └── store.js   适配层
+├── example/
+│   └── index.js
+├── test.js
+└── package.json
+```
+
+## 许可证
+
+ISC

package/index.js

@@ -1,24 +1,52 @@
-const Lang = require('./lib/lang');
-const Admin = require('mm_corejs').Admin;
-
-let admin = new Admin();
-admin.setClass(Lang);
-
-/**
- * 获取语言实例
- * @param {string} scope 作用域
- * @param {Object} config 语言配置
- * @returns {Lang} 语言实例
- */
-function langAdmin(scope, config) {
-  if (!scope) {
-    scope = 'os';
-  }
-  return admin.get(scope, config);
-}
-
-module.exports = {
-  Lang,
-  admin,
-  langAdmin
-};
+const Lang = require('./lib/lang');
+const Langs = require('./lib/langs');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 语言实例管理器（行为侧）
+ * @type {Admin}
+ */
+let admin = new Admin();
+admin.setClass(Lang);
+
+/**
+ * 语言存储实例管理器（数据侧）
+ * @type {Admin}
+ */
+let langs_admin = new Admin();
+langs_admin.setClass(Langs);
+
+/**
+ * 获取语言实例
+ * @param {string} scope 作用域
+ * @param {Object} config 语言配置，可含 file 持久化路径与 store 存储实例
+ * @returns {Lang} 语言实例
+ */
+function langAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  return admin.get(scope, config);
+}
+
+/**
+ * 获取语言存储实例，不存在时创建
+ * @param {string} [scope] 作用域名称，缺省时使用 os
+ * @param {Object} [config] 配置对象，含 file 持久化文件路径
+ * @returns {Langs} 语言存储实例
+ */
+function langsAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  return langs_admin.get(scope, config);
+}
+
+module.exports = {
+  Lang,
+  Langs,
+  admin,
+  langs_admin,
+  langAdmin,
+  langsAdmin
+};

package/lib/lang.js

@@ -1,15 +1,34 @@
+/**
+ * 持久化适配：嵌套词条字典与 Langs 扁平键值互转、存储实例装配
+ */
+const {
+  flatten,
+  unflatten,
+  assignDeep,
+  isControlKey,
+  createStore
+} = require('./store.js');
+
 /**
  * 内置语言类
  * 国际化(i18n)核心：按语言字典取值、层级键解析、回退机制、复数形式与格式化
  * 行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量
+ * 持久化能力通过组合的 Langs 存储实例（this.store）提供，本类不做文件 IO
  * @class
  */
 class Lang {
   /**
    * 创建语言实例
-   * @param {Object} config - 语言包配置，键为语言代码，值可为词条对象；可含 default 与 fallback
+   * @param {Object} config - 语言包配置，键为语言代码，值可为词条对象；可含 default、fallback、locale、file、store
    */
   constructor(config = {}) {
+    var cg = Object.assign({}, config);
+    var file = cg.file || '';
+    var injected = cg.store;
+    // file / store 属于存储配置，不进入词条字典，避免被当作语言代码
+    delete cg.file;
+    delete cg.store;
+
     /**
      * 语言包配置，语言代码对应词条字典
      * @type {Object}
@@ -19,7 +38,7 @@ class Lang {
       en: {},
       default: 'zh_cn',
       fallback: true
-    }, config);
+    }, cg);
 
     /**
      * 复数规则表，键为语言代码，值为按数量返回形式的索引的函数
@@ -48,6 +67,18 @@ class Lang {
       zh: 'zh_cn',
       en: 'en'
     }, this.config.locale);
+
+    /**
+     * 持久化文件路径
+     * @type {string}
+     */
+    this.file = file;
+
+    /**
+     * 语言存储实例（数据侧，来自 langs.js），未配置 file 且未注入时为 null
+     * @type {Langs|null}
+     */
+    this.store = createStore(injected, file);
   }
 }
 
@@ -190,6 +221,10 @@ Lang.prototype.setLang = function (lang) {
   if (!lang || typeof (lang) !== 'string') {
     throw new TypeError('lang必须是字符串');
   }
+  if (isControlKey(lang)) {
+    this._log('error', '语言未找到: ' + lang);
+    return this.now;
+  }
   if (this.config[lang]) {
     this.now = lang;
     return this.now;
@@ -333,36 +368,117 @@ Lang.prototype.registerPlural = function (lang, rule) {
 
 /**
  * 获取支持的语言列表
+ * 过滤掉 default、fallback、locale、options、file、store 等非词条键
  * @returns {Array<string>} 语言代码数组
  */
 Lang.prototype.getLangs = function () {
   var langs = [];
   for (var key in this.config) {
-    if (key !== 'default' && key !== 'fallback' && key !== 'options'
-      && typeof (this.config[key]) === 'object') {
+    if (!isControlKey(key) && typeof (this.config[key]) === 'object') {
       langs.push(key);
     }
   }
   return langs;
 };
 
+/**
+ * 获取或初始化存储实例 - 内部方法
+ * 已注入存储实例时优先复用；仅有文件路径时按路径新建并缓存
+ * @param {string} [file] 本次调用的持久化文件路径
+ * @returns {Langs|null} 存储实例
+ * @private
+ */
+Lang.prototype._getStore = function (file) {
+  if (this.store) {
+    if (file && this.store.config && !this.store.config.file) {
+      this.store.config.file = file;
+    }
+    return this.store;
+  }
+  var target = file || this.file;
+  if (target) {
+    this.store = createStore(null, target);
+    this.file = target;
+    return this.store;
+  }
+  return null;
+};
+
+/**
+ * 保存语言包到持久化文件
+ * 词条扁平化为 `语言代码.层级键 → 文本` 后写入存储实例，再由存储实例落盘
+ * @param {string} [file] 持久化文件路径，缺省时用实例的 file 配置
+ * @returns {boolean} 是否保存成功
+ */
+Lang.prototype.save = function (file) {
+  var store = this._getStore(file);
+  if (!store) {
+    this._log('error', '未配置持久化文件路径或存储实例，无法保存语言包');
+    return false;
+  }
+  var flat = flatten(this.config);
+  try {
+    store.clear();
+    for (var key in flat) {
+      store.set(key, flat[key]);
+    }
+    return store.save() !== false;
+  } catch (e) {
+    this._log('error', '语言包保存失败: ' + e.message);
+    return false;
+  }
+};
+
+/**
+ * 从持久化文件加载语言包
+ * 扁平键值还原为嵌套字典后合并进当前配置，文件中的词条优先
+ * @param {string} [file] 持久化文件路径，缺省时用实例的 file 配置
+ * @returns {boolean} 是否加载成功
+ */
+Lang.prototype.load = function (file) {
+  var store = this._getStore(file);
+  if (!store || typeof (store.load) !== 'function') {
+    this._log('error', '未配置持久化文件路径或存储实例，无法加载语言包');
+    return false;
+  }
+  var ok = false;
+  try {
+    ok = store.load();
+  } catch (e) {
+    this._log('error', '语言包加载失败: ' + e.message);
+    return false;
+  }
+  if (!ok) {
+    return false;
+  }
+  assignDeep(this.config, unflatten(store.list()));
+  return true;
+};
+
 /**
  * 检查语言是否支持
  * @param {string} lang - 语言代码
  * @returns {boolean} 是否支持
  */
 Lang.prototype.isSupported = function (lang) {
+  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
+    return false;
+  }
   return !!this.config[lang] || !!this.config[this._getBase(lang)];
 };
 
 /**
  * 输出日志 - 内部方法，使用 console
+ * 配置 silent 为 true 时静默（供上层自带日志体系的场景使用，如 mm_tpl）
  * @param {string} level - 日志级别
  * @param {string} message - 日志消息
  * @param {...any} args - 附加参数
  * @private
  */
 Lang.prototype._log = function (level, message, ...args) {
+  if (this.config.silent) {
+    return;
+  }
   var fn = console[level] || console.log;
   if (typeof (fn) === 'function') {
     fn.call(console, message, ...args);

package/lib/langs.js

@@ -0,0 +1,32 @@
+const KvStore = require('mm_kv_store').KvStore;
+
+/**
+ * 语言存储类，键和值都只能是字符串
+ * 由原 mm_langs 模块融合而来，作为多语言模块的数据侧：只负责键值管理与持久化，
+ * 不感知语言词条的嵌套语义（嵌套结构的适配由 lib/store.js 承担）
+ * @class
+ * @augments {KvStore}
+ */
+class Langs extends KvStore {
+  /**
+   * 获取存储项名称，用于覆盖冲突提示
+   * @returns {string} 存储项名称
+   */
+  _getName() {
+    return 'langs';
+  }
+
+  /**
+   * 校验值是否为字符串
+   * @param {*} value 值
+   * @returns {void}
+   * @throws {TypeError} 值不是字符串时抛出
+   */
+  _checkValue(value) {
+    if (typeof value !== 'string') {
+      throw new TypeError('langs 的值必须是字符串');
+    }
+  }
+}
+
+module.exports = Langs;

package/lib/store.js

@@ -0,0 +1,190 @@
+/**
+ * 语言词条持久化适配层
+ * @description 承担"动作侧适配"职责：把 Lang 的嵌套词条字典与 Langs 的
+ * string→string 扁平键值互相转换。文件读写、键值校验等存储细节全部由 Langs 负责，
+ * 本文件不触碰 fs。
+ */
+
+const Langs = require('./langs');
+
+/**
+ * 非词条的控制键，不参与扁平化与持久化
+ * @type {Array<string>}
+ */
+const CONTROL_KEYS = ['default', 'fallback', 'locale', 'options', 'file', 'store', 'silent'];
+
+/**
+ * 非字符串词条（复数数组等）的标记前缀
+ * 落盘后仍是字符串，满足 Langs 的 string→string 约束；读取时按前缀还原
+ * @type {string}
+ */
+const MARK = '\u0001';
+
+/**
+ * 判断是否为控制键
+ * @param {string} key 键名
+ * @returns {boolean} 是控制键返回 true
+ */
+function isControlKey(key) {
+  return CONTROL_KEYS.indexOf(key) !== -1;
+}
+
+/**
+ * 将词条值序列化为存储字符串
+ * @param {*} val 词条值
+ * @returns {string|null} 存储字符串，不可序列化的值返回 null
+ */
+function encodeValue(val) {
+  if (typeof (val) === 'string') {
+    return val;
+  }
+  if (Array.isArray(val)) {
+    return MARK + JSON.stringify(val);
+  }
+  if (typeof (val) === 'number' || typeof (val) === 'boolean') {
+    return String(val);
+  }
+  return null;
+}
+
+/**
+ * 将存储字符串还原为词条值
+ * @param {string} val 存储字符串
+ * @returns {*} 词条值
+ */
+function decodeValue(val) {
+  if (typeof (val) !== 'string') {
+    return val;
+  }
+  if (val.charAt(0) === MARK) {
+    try {
+      return JSON.parse(val.slice(1));
+    } catch (e) {
+      return val;
+    }
+  }
+  return val;
+}
+
+/**
+ * 嵌套词条字典扁平化为 string→string 键值
+ * 键形如 `语言代码.层级键`，复数数组等非字符串值按 MARK 前缀编码
+ * @param {Object} dict 嵌套词条字典
+ * @param {string} [prefix] 键前缀
+ * @param {Object} [out] 输出容器
+ * @returns {Object} 扁平键值表
+ */
+function flatten(dict, prefix, out) {
+  var flat = out || {};
+  if (!dict || typeof (dict) !== 'object') {
+    return flat;
+  }
+  for (var key in dict) {
+    if (!Object.prototype.hasOwnProperty.call(dict, key)) {
+      continue;
+    }
+    if (!prefix && isControlKey(key)) {
+      continue;
+    }
+    var val = dict[key];
+    var path = prefix ? prefix + '.' + key : key;
+    if (val && typeof (val) === 'object' && !Array.isArray(val)) {
+      flatten(val, path, flat);
+    } else {
+      var str = encodeValue(val);
+      if (str !== null) {
+        flat[path] = str;
+      }
+    }
+  }
+  return flat;
+}
+
+/**
+ * 按点号路径向对象写入值
+ * @param {Object} obj 目标对象
+ * @param {string} path 点号路径
+ * @param {*} val 值
+ * @returns {void}
+ */
+function setByPath(obj, path, val) {
+  var keys = path.split('.');
+  var cur = obj;
+  for (var i = 0; i < keys.length - 1; i++) {
+    if (!cur[keys[i]] || typeof (cur[keys[i]]) !== 'object') {
+      cur[keys[i]] = {};
+    }
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = val;
+}
+
+/**
+ * 扁平键值还原为嵌套词条字典
+ * @param {Object} flat 扁平键值表
+ * @returns {Object} 嵌套词条字典
+ */
+function unflatten(flat) {
+  var dict = {};
+  if (!flat || typeof (flat) !== 'object') {
+    return dict;
+  }
+  for (var path in flat) {
+    if (!Object.prototype.hasOwnProperty.call(flat, path)) {
+      continue;
+    }
+    setByPath(dict, path, decodeValue(flat[path]));
+  }
+  return dict;
+}
+
+/**
+ * 深度合并词条字典，来源值覆盖目标值
+ * @param {Object} target 目标字典
+ * @param {Object} source 来源字典
+ * @returns {Object} 合并后的目标字典
+ */
+function assignDeep(target, source) {
+  for (var key in source) {
+    if (!Object.prototype.hasOwnProperty.call(source, key)) {
+      continue;
+    }
+    var val = source[key];
+    if (val && typeof (val) === 'object' && !Array.isArray(val)
+      && target[key] && typeof (target[key]) === 'object' && !Array.isArray(target[key])) {
+      assignDeep(target[key], val);
+    } else {
+      target[key] = val;
+    }
+  }
+  return target;
+}
+
+/**
+ * 创建语言存储实例
+ * 优先复用外部注入的实例（动作与数据解耦），其次按文件路径新建，都没有则返回 null
+ * @param {Langs} [injected] 注入的存储实例
+ * @param {string} [file] 持久化文件路径
+ * @returns {Langs|null} 存储实例
+ */
+function createStore(injected, file) {
+  if (injected && typeof (injected.set) === 'function' && typeof (injected.save) === 'function') {
+    return injected;
+  }
+  if (file) {
+    return new Langs({ file: file });
+  }
+  return null;
+}
+
+module.exports = {
+  CONTROL_KEYS,
+  MARK,
+  isControlKey,
+  encodeValue,
+  decodeValue,
+  flatten,
+  unflatten,
+  assignDeep,
+  createStore
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mm_lang",
-  "version": "1.0.1",
-  "description": "超级美眉多语言/语言包模块",
+  "version": "2.0.0",
+  "description": "超级美眉多语言模块：融合 i18n 行为（Lang）与语言存储持久化（Langs），支持层级键、回退链、复数、格式化与 JSON 文件落盘",
   "main": "index.js",
   "repository": {
     "type": "git",
@@ -10,13 +10,31 @@
   "keywords": [
     "mm_mod",
     "mm_infra",
-    "mm_common"
+    "mm_data",
+    "lang",
+    "i18n",
+    "locale",
+    "langs",
+    "多语言",
+    "语言包"
   ],
   "layer": "infra",
-  "group": "common",
+  "group": "data",
   "author": "邱文武",
   "license": "ISC",
   "scripts": {
-    "test": "node test.js"
-  }
+    "test": "node test.js",
+    "example": "node example/index.js"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.6",
+    "mm_kv_store": "^1.0.1"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "example",
+    "README.md",
+    "package.json"
+  ]
 }

package/test.js

@@ -1,18 +0,0 @@
-'use strict';
-const assert = require('assert');
-const mod = require('./index.js');
-
-// 验证导出结构
-assert.ok(mod.Lang, '应导出 Lang');
-assert.ok(mod.admin, '应导出 admin');
-assert.strictEqual(typeof mod.langAdmin, 'function', '应导出 langAdmin 函数');
-
-// 验证通过工厂函数获取实例
-const inst = mod.langAdmin('test');
-assert.ok(inst instanceof mod.Lang, 'langAdmin 返回的实例应为 Lang 类型');
-
-// 验证通过 admin 获取实例
-const inst2 = mod.admin.get('test2');
-assert.ok(inst2 instanceof mod.Lang, 'admin.get 返回的实例应为 Lang 类型');
-
-console.log('mm_lang 模块测试通过');