mm_lang 1.0.1 → 3.0.0

package/README.md

@@ -1,148 +1,209 @@
-# mm_lang
-
-超级美眉多语言/语言包模块，提供 `Lang` 类作为国际化（i18n）核心能力：按语言字典取值、`a.b` 层级键解析、多级回退机制（当前语言 → 基础语言 → 默认语言）、复数形式、占位符参数替换，以及日期与数字的本地化格式化。行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量。
-
-## 项目信息
-
-- **当前版本**: 1.0.0
-- **更新日期**: 2026-10-04
-- **Gitee地址**: https://gitee.com/qiuwenwu91/mm_lang
-- **依赖**: 无第三方依赖（纯 Node.js 实现）
-
-## 特点
-
-- 零依赖，内置 `zh_cn` 与 `en` 两种语言的默认词条容器
-- 支持 `a.b.c` 形式的层级键取值与写入
-- 带回退机制的取值链：当前语言 → 基础语言（如 `en-US` 回退到 `en`）→ 默认语言
-- 复数形式支持：`tc` 按数量选择词条数组索引，内置英文/中文复数规则，可通过 `registerPlural` 自定义
-- 占位符替换：`get`/`t` 支持 `{0}`、`{1}` 等；`tc` 支持 `{count}` 及 `{1}`、`{2}` 等
-- 附带日期格式化（`formatDate`）与数字格式化（`formatNumber`，可配置小数位数与千分位/小数分隔符）
-
-## 安装
-
-```bash
-npm install mm_lang
-```
-
-## 基本使用
-
-```javascript
-const { Lang } = 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
-});
-
-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
-```
-
-## API 说明
-
-### 构造 `new Lang(dict)`
-
-`dict` 为语言包字典对象，各字段与默认值：
-
-| 配置项 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `zh_cn` | `Object` | `{}` | 简体中文词条字典 |
-| `en` | `Object` | `{}` | 英文词条字典 |
-| `default` | `String` | `'zh_cn'` | 默认语言代码，同时作为初始当前语言 |
-| `fallback` | `Boolean` | `true` | 是否启用回退机制 |
-| `locale` | `Object` | `{ zh: 'zh_cn', en: 'en' }` | 完整语言代码到基础语言代码的映射（与默认值合并） |
-
-实例属性：`config`（语言包配置）、`rules`（复数规则表）、`now`（当前语言代码）、`locale`（区域映射表）。
-
-### 取值与翻译
-
-| 方法 | 签名 | 返回值 | 说明 |
-| --- | --- | --- | --- |
-| get | `get(key, ...param)` | `String` | 获取翻译文本，支持 `a.b` 层级键；`param` 依次替换 `{0}`、`{1}` 等占位符；`key` 非字符串时抛 `TypeError` |
-| t | `t(key, ...param)` | `String` | `get` 的别名 |
-| tc | `tc(key, count, ...param)` | `String` | 翻译带复数形式的文本：词条值为数组时按当前语言复数规则取索引，先替换 `{count}`，再用 `param` 依次替换 `{1}`、`{2}` 等；`key` 非字符串或 `count` 非数字时抛 `TypeError` |
-
-### 语言管理
-
-| 方法 | 签名 | 返回值 | 说明 |
-| --- | --- | --- | --- |
-| 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` |
-
-### 格式化
-
-| 方法 | 签名 | 返回值 | 说明 |
-| --- | --- | --- | --- |
-| 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` |
-
-> 另有 `_getVal`、`_getFrom`、`_getBase`、`_set`、`_log` 等下划线前缀的内部私有方法，不建议外部调用。
-
-## 使用示例
-
-### 场景一：回退机制
-
-```javascript
-const { Lang } = require('mm_lang');
-
-const lang = new Lang({
-  zh_cn: { nav: { home: '首页' } },
-  en: { nav: { home: 'Home', about: 'About' } },
-  default: 'en',
-  fallback: true
-});
-
-lang.setLang('zh_cn');
-console.log(lang.get('nav.about')); // 中文缺失，回退到默认语言 en → "About"
-```
-
-### 场景二：自定义复数规则
-
-```javascript
-const { Lang } = require('mm_lang');
-
-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;
-  if (n10 >= 2 && n10 <= 4 && (n100 < 12 || n100 > 14)) return 1;
-  return 2;
-});
-
-console.log(lang.tc('apple', 1));  // яблоко
-console.log(lang.tc('apple', 3));  // яблока
-console.log(lang.tc('apple', 11)); // яблок
-```
-
-### 场景三：本地化格式化
-
-```javascript
-const { Lang } = 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
-```
+# mm_lang
+
+超级美眉多语言模块。融合了原 `mm_lang`（i18n 行为）与 `mm_langs`（语言存储）两个模块：`Lang` 负责翻译行为，`Langs` 负责键值存储与 JSON 文件持久化，两者组合实现"动作与数据分离"。
+
+> **迁移提示**：`mm_langs` 已合并至本模块，其 `Langs` 类与 `langsAdmin` 从 `mm_lang` 直接导出，API 与报错文案保持不变。原 `require('mm_langs')` 改为 `require('mm_lang')` 即可。
+
+## 项目信息
+
+- **当前版本**: 2.0.0
+- **更新日期**: 2026-10-30
+- **Gitee地址**: https://gitee.com/qiuwenwu91/mm_lang
+- **依赖**: `mm_corejs`（管理器）、`mm_kv_store`（键值存储基类）
+
+## 模块结构
+
+| 文件 | 职责 |
+|---|---|
+| `lib/lang.js` | 行为侧：扁平词条表（`语言.层级键`→文本）上的取词、回退链、复数、格式化，只接受扁平入参，**不做文件 IO** |
+| `lib/langs.js` | 数据侧：string→string 键值、JSON 文件 save/load、值类型校验，**不感知语言词条语义** |
+| `lib/langs_admin.js` | 数据侧管理器：Langs 实例按作用域（文件路径）复用，供 Lang 与 langsAdmin 共用 |
+
+## 特点
+
+- **行为侧**：零文件 IO，`zh_cn`/`en` 内置复数规则，`a.b.c` 层级键，回退链（当前语言 → 基础语言 → 默认语言），占位符替换，日期/数字本地化格式化
+- **数据侧**：键和值都只能是字符串，支持覆盖、删除、判断存在、取副本、清空、JSON 文件持久化
+- **组合使用**：`Lang` 配置 `file` 即获得持久化能力；也可注入自定义 `store` 实例替换存储后端
+
+## 安装
+
+```bash
+npm install mm_lang
+```
+
+## 快速开始
+
+```javascript
+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'
+});
+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();                 // 内存词条表即扁平形态，直接落盘（相同 file 复用同一存储实例）
+
+// 只用存储（原 mm_langs 用法）
+const langs = new Langs({ file: './data/map.json' });
+langs.set('en', 'english').save();
+```
+
+## API 说明
+
+### 行为侧 `Lang`
+
+#### 构造 `new Lang(config)`
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `zh_cn` | `Object` | `{}` | 简体中文词条字典 |
+| `en` | `Object` | `{}` | 英文词条字典 |
+| `default` | `String` | `'zh_cn'` | 默认语言代码，同时作为初始当前语言 |
+| `fallback` | `Boolean` | `true` | 是否启用回退机制 |
+| `locale` | `Object` | `{ zh: 'zh_cn', en: 'en' }` | 完整语言代码到基础语言代码的映射 |
+| `file` | `String` | `''` | 持久化文件路径，配置后自动创建 Langs 存储实例 |
+| `store` | `Langs` | `undefined` | 注入的存储实例（鸭子类型），优先于 `file` |
+| `silent` | `Boolean` | `false` | 是否静默缺失词条/存储异常日志（上层自带日志体系时开启，如 mm_tpl） |
+
+实例属性：`config`（词条字典）、`rules`（复数规则）、`now`（当前语言）、`locale`（区域映射）、`file`（持久化路径）、`store`（存储实例或 `null`）。
+
+#### 取值与翻译
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| get | `get(key, ...param)` | `String` | 取翻译文本，支持 `a.b` 层级键；`param` 依次替换 `{0}`、`{1}` 等 |
+| t | `t(key, ...param)` | `String` | `get` 的别名 |
+| tc | `tc(key, count, ...param)` | `String` | 复数形式取词：数组词条按当前语言规则取索引，先替换 `{count}`，再替换 `{1}`、`{2}` 等 |
+
+#### 语言管理
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| setLang | `setLang(lang)` | `String` | 切换语言；找不到时先尝试基础语言映射，仍失败记日志并保持当前语言 |
+| getLangs | `getLangs()` | `Array<String>` | 支持的语言列表（取词条键首段去重，无词条的语言不会出现） |
+| isSupported | `isSupported(lang)` | `Boolean` | 语言是否支持（含基础语言映射，控制键恒为 false） |
+| del | `del(lang)` | `Boolean` | 删除指定语言的全部词条 |
+| hasLang | `hasLang(lang)` | `Boolean` | 某语言是否存在词条 |
+| getDict | `getDict(lang)` | `Object|null` | 导出某语言词条为嵌套字典（形态与语言包文件一致），无词条返回 `null` |
+| set | `set(key, val)` | `any` | 向当前语言写入词条，支持 `a.b` 层级键 |
+| registerPlural | `registerPlural(lang, rule)` | `Boolean` | 注册复数规则，`rule(count)` 返回形式索引 |
+
+#### 持久化
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| save | `save(file?)` | `Boolean` | 词条扁平化后经存储实例落盘；无存储实例返回 `false`（不抛异常） |
+| load | `load(file?)` | `Boolean` | 从存储实例读取扁平键值直接合并进 `config`（结构一致无需转换），文件中的词条优先；失败返回 `false` 且不改动内存词条 |
+
+落盘格式为 `语言代码.层级键 → 文本` 的 string→string 键值，例如：
+
+```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` 实例 |
+
+## 使用示例
+
+### 场景一：回退机制
+
+```javascript
+const { Lang } = require('mm_lang');
+
+const lang = new Lang({
+  zh_cn: { nav: { home: '首页' } },
+  en: { nav: { home: 'Home', about: 'About' } },
+  default: 'en'
+});
+
+lang.setLang('zh_cn');
+console.log(lang.get('nav.about')); // 中文缺失，回退到默认语言 en → "About"
+```
+
+### 场景二：自定义复数规则
+
+```javascript
+const { Lang } = require('mm_lang');
+
+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;
+  if (n10 >= 2 && n10 <= 4 && (n100 < 12 || n100 > 14)) return 1;
+  return 2;
+});
+
+console.log(lang.tc('apple', 1));  // яблоко
+console.log(lang.tc('apple', 3));  // яблока
+console.log(lang.tc('apple', 11)); // яблок
+```
+
+### 场景三：注入自定义存储
+
+```javascript
+const { Lang, Langs } = require('mm_lang');
+
+// 任何具备 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   数据侧
+├── example/
+│   └── index.js
+├── test.js
+└── package.json
+```
+
+## 许可证
+
+ISC

package/example/index.js

@@ -11,22 +11,14 @@ const { Lang } = require('../index.js');
 function main() {
   console.log('=== 语言包翻译 ===');
 
-  // 创建语言实例，字典为 语言代码 -> 词条对象
+  // 创建语言实例，词条表为扁平结构：键为 语言.层级键，值为文本或复数数组
   var lang = new Lang({
-    zh_cn: {
-      hello: '你好, {0}!',
-      order: {
-        count: ['共 {count} 个商品']
-      },
-      greet: ['你好', '你们好']
-    },
-    en: {
-      hello: 'Hello, {0}!',
-      order: {
-        count: ['{count} item', '{count} items']
-      },
-      greet: ['Hello', 'Hello everyone']
-    },
+    'zh_cn.hello': '你好, {0}!',
+    'zh_cn.order.count': ['共 {count} 个商品'],
+    'zh_cn.greet': ['你好', '你们好'],
+    'en.hello': 'Hello, {0}!',
+    'en.order.count': ['{count} item', '{count} items'],
+    'en.greet': ['Hello', 'Hello everyone'],
     default: 'zh_cn'
   });
 

package/index.js

@@ -1,24 +1,48 @@
-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 langs_admin = require('./lib/langs_admin');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 语言实例管理器（行为侧）
+ * @type {Admin}
+ */
+let admin = new Admin();
+admin.setClass(Lang);
+
+/**
+ * 获取语言实例
+ * @param {string} scope 作用域
+ * @param {Object} config 语言配置，可含 file 持久化路径与 store 存储实例
+ * @returns {Lang} 语言实例
+ */
+function langAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  return admin.get(scope, config);
+}
+
+/**
+ * 获取语言存储实例，不存在时创建
+ * 与 Lang 内部使用同一 langs_admin 管理器：以文件路径为作用域时，
+ * 配置了相同 file 的 Lang 与 langsAdmin 取到的是同一个存储实例
+ * @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,25 +1,126 @@
 /**
  * 内置语言类
- * 国际化(i18n)核心：按语言字典取值、层级键解析、回退机制、复数形式与格式化
- * 行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量
+ * 国际化(i18n)核心：扁平词条表上的取词、回退、复数与格式化
+ * 词条表与持久化同构：内存即 `语言代码.层级键 → 文本` 的扁平形态，save/load 无需转换
+ * 只接受扁平入参（键为 `语言.层级键`，或 default/fallback/locale/silent/file/store 控制键），
+ * 嵌套语言包由调用方展开（mm_tpl 在加载语言包文件后自行扁平化）
+ * 持久化通过 langsAdmin 管理的 Langs 存储实例（this.store）完成，本类不做文件 IO
  * @class
  */
+
+const langs_admin = require('./langs_admin.js');
+
+/**
+ * 非词条的控制键，不参与取词、语言列表与持久化
+ * 词条键必含点号（`语言.键`），控制键均不含点号，二者天然可分
+ * @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;
+}
+
+/**
+ * 按点号路径向对象写入值（仅 getDict 导出单语言词条时使用）
+ * @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' || Array.isArray(cur[keys[i]])) {
+      cur[keys[i]] = {};
+    }
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = val;
+}
+
 class Lang {
   /**
    * 创建语言实例
-   * @param {Object} config - 语言包配置，键为语言代码，值可为词条对象；可含 default 与 fallback
+   * @param {Object} config - 扁平词条表：键为 `语言.层级键`，值为字符串/数字/布尔/数组；
+   *   可含控制键 default、fallback、locale、silent 及存储配置 file、store
    */
   constructor(config = {}) {
+    var cg = Object.assign({}, config);
+    var file = cg.file || '';
+    var injected = cg.store;
+    delete cg.file;
+    delete cg.store;
+
     /**
-     * 语言包配置，语言代码对应词条字典
+     * 扁平词条表，键为 `语言代码.层级键`，与持久化格式一致；控制键并存于同一层
      * @type {Object}
      */
     this.config = Object.assign({
-      zh_cn: {},
-      en: {},
       default: 'zh_cn',
       fallback: true
-    }, config);
+    }, cg);
+
+    // 词条值不能是嵌套对象，嵌套语言包需由调用方展开为扁平键
+    for (var key in this.config) {
+      if (!Object.prototype.hasOwnProperty.call(this.config, key) || isControlKey(key)) {
+        continue;
+      }
+      var val = this.config[key];
+      if (val && typeof (val) === 'object' && !Array.isArray(val)) {
+        throw new TypeError('词条 "' + key + '" 的值不能是对象，请使用扁平键（语言.层级键）');
+      }
+    }
 
     /**
      * 复数规则表，键为语言代码，值为按数量返回形式的索引的函数
@@ -48,6 +149,19 @@ class Lang {
       zh: 'zh_cn',
       en: 'en'
     }, this.config.locale);
+
+    /**
+     * 持久化文件路径
+     * @type {string}
+     */
+    this.file = file;
+
+    /**
+     * 语言存储实例（数据侧）：优先用注入实例，否则按文件路径经 langsAdmin 取共享实例，
+     * 两者都无则为 null（纯内存）
+     * @type {Langs|null}
+     */
+    this.store = injected || (file ? langs_admin.get(file, { file: file }) : null);
   }
 }
 
@@ -72,7 +186,7 @@ Lang.prototype.get = function (key, ...param) {
 };
 
 /**
- * 带回退机制获取语言值 - 内部方法
+ * 带回退机制获取词条 - 内部方法
  * 依次尝试：当前语言、基础语言、默认语言
  * @param {string} key - 键
  * @returns {any} 语言值
@@ -96,29 +210,14 @@ Lang.prototype._getVal = function (key) {
 };
 
 /**
- * 从指定语言中获取值 - 内部方法
+ * 从指定语言中获取扁平词条 - 内部方法
  * @param {string} lang - 语言代码
  * @param {string} key - 键
  * @returns {any} 值
  * @private
  */
 Lang.prototype._getFrom = function (lang, key) {
-  var lang_cg = this.config[lang];
-  if (!lang_cg) {
-    return undefined;
-  }
-  var arr = key.split('.');
-  var val = lang_cg;
-  for (var i = 0; i < arr.length; i++) {
-    if (val === undefined) {
-      break;
-    }
-    val = val[arr[i]];
-    if (val === undefined || typeof (val) === 'string') {
-      break;
-    }
-  }
-  return val;
+  return this.config[lang + '.' + key];
 };
 
 /**
@@ -145,44 +244,13 @@ Lang.prototype.set = function (key, val) {
   if (!key || typeof (key) !== 'string') {
     throw new TypeError('key必须是字符串');
   }
-  return this._set(key, val);
-};
-
-/**
- * 设置语言键值 - 内部方法
- * @param {string} key - 键名
- * @param {any} val - 值
- * @returns {any} 返回设置的值
- * @private
- */
-Lang.prototype._set = function (key, val) {
-  var lang = this.config[this.now];
-  if (!lang) {
-    this._log('error', '当前语言未初始化: ' + this.now);
-    return val;
-  }
-  var arr = key.split('.');
-  var obj = lang;
-  for (var i = 0; i < arr.length; i++) {
-    var k = arr[i];
-    var v = obj[k];
-    if (i === arr.length - 1) {
-      obj[k] = val;
-    } else if (v === undefined) {
-      obj[k] = {};
-      obj = obj[k];
-    } else if (typeof (v) === 'object' && !Array.isArray(v)) {
-      obj = v;
-    } else {
-      obj[k] = {};
-      obj = obj[k];
-    }
-  }
+  this.config[this.now + '.' + key] = val;
   return val;
 };
 
 /**
  * 切换语言
+ * 扁平结构下语言是否存在以是否有该语言前缀的词条为准
  * @param {string} lang - 语言代码
  * @returns {string} 切换后的语言代码
  */
@@ -190,12 +258,16 @@ Lang.prototype.setLang = function (lang) {
   if (!lang || typeof (lang) !== 'string') {
     throw new TypeError('lang必须是字符串');
   }
-  if (this.config[lang]) {
+  if (isControlKey(lang)) {
+    this._log('error', '语言未找到: ' + lang);
+    return this.now;
+  }
+  if (this.hasLang(lang)) {
     this.now = lang;
     return this.now;
   }
   var base_lang = this._getBase(lang);
-  if (this.config[base_lang]) {
+  if (base_lang !== lang && this.hasLang(base_lang)) {
     this.now = base_lang;
     return this.now;
   }
@@ -204,7 +276,25 @@ Lang.prototype.setLang = function (lang) {
 };
 
 /**
- * 删除语言配置
+ * 判断某语言是否存在词条
+ * @param {string} lang - 语言代码
+ * @returns {boolean} 存在该语言的词条时返回 true
+ */
+Lang.prototype.hasLang = function (lang) {
+  if (!lang || typeof (lang) !== 'string') {
+    return false;
+  }
+  var prefix = lang + '.';
+  for (var key in this.config) {
+    if (key.indexOf(prefix) === 0) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * 删除某语言的全部词条
  * @param {string} lang - 语言代码
  * @returns {boolean} 是否删除成功
  */
@@ -212,11 +302,15 @@ Lang.prototype.del = function (lang) {
   if (!lang || typeof (lang) !== 'string') {
     throw new TypeError('lang必须是字符串');
   }
-  if (this.config[lang]) {
-    delete this.config[lang];
-    return true;
+  var prefix = lang + '.';
+  var removed = false;
+  for (var key in this.config) {
+    if (key.indexOf(prefix) === 0) {
+      delete this.config[key];
+      removed = true;
+    }
   }
-  return false;
+  return removed;
 };
 
 /**
@@ -333,36 +427,132 @@ Lang.prototype.registerPlural = function (lang, rule) {
 
 /**
  * 获取支持的语言列表
+ * 取词条键的首段去重，无词条的语言不会出现（空语言字典天然不可见）
  * @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') {
-      langs.push(key);
+    if (isControlKey(key)) {
+      continue;
+    }
+    var dot = key.indexOf('.');
+    if (dot === -1) {
+      continue;
+    }
+    var lang = key.slice(0, dot);
+    if (langs.indexOf(lang) === -1) {
+      langs.push(lang);
     }
   }
   return langs;
 };
 
+/**
+ * 导出某语言的全部词条
+ * 扁平词条按前缀取出并还原为嵌套字典，形态与语言包文件一致
+ * @param {string} lang - 语言代码
+ * @returns {Object|null} 嵌套词条字典，该语言无词条时返回 null
+ */
+Lang.prototype.getDict = function (lang) {
+  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
+    return null;
+  }
+  var prefix = lang + '.';
+  var dict = null;
+  for (var key in this.config) {
+    if (key.indexOf(prefix) !== 0) {
+      continue;
+    }
+    if (!dict) {
+      dict = {};
+    }
+    setByPath(dict, key.slice(prefix.length), this.config[key]);
+  }
+  return dict;
+};
+
+/**
+ * 保存语言包到持久化文件
+ * 内存词条表即扁平 string→string 形态（数组值按标记编码），直接写入存储实例落盘
+ * @returns {boolean} 是否保存成功
+ */
+Lang.prototype.save = function () {
+  if (!this.store) {
+    this._log('error', '未配置持久化文件路径或存储实例，无法保存语言包');
+    return false;
+  }
+  try {
+    this.store.clear();
+    for (var key in this.config) {
+      if (!Object.prototype.hasOwnProperty.call(this.config, key) || isControlKey(key)) {
+        continue;
+      }
+      var str = encodeValue(this.config[key]);
+      if (str !== null) {
+        this.store.set(key, str);
+      }
+    }
+    return this.store.save() !== false;
+  } catch (e) {
+    this._log('error', '语言包保存失败: ' + e.message);
+    return false;
+  }
+};
+
+/**
+ * 从持久化文件加载语言包
+ * 存储中的扁平键值与内存结构一致，直接合并进词条表（文件中的词条优先），数组编码值还原
+ * @returns {boolean} 是否加载成功
+ */
+Lang.prototype.load = function () {
+  if (!this.store) {
+    this._log('error', '未配置持久化文件路径或存储实例，无法加载语言包');
+    return false;
+  }
+  var ok = false;
+  try {
+    ok = this.store.load();
+  } catch (e) {
+    this._log('error', '语言包加载失败: ' + e.message);
+    return false;
+  }
+  if (!ok) {
+    return false;
+  }
+  var list = this.store.list();
+  for (var key in list) {
+    if (Object.prototype.hasOwnProperty.call(list, key)) {
+      this.config[key] = decodeValue(list[key]);
+    }
+  }
+  return true;
+};
+
 /**
  * 检查语言是否支持
  * @param {string} lang - 语言代码
  * @returns {boolean} 是否支持
  */
 Lang.prototype.isSupported = function (lang) {
-  return !!this.config[lang] || !!this.config[this._getBase(lang)];
+  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
+    return false;
+  }
+  return this.hasLang(lang) || this.hasLang(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 模块融合而来，作为多语言模块的数据侧：只负责键值管理与持久化，
+ * 不感知语言词条语义（Lang 侧内存词条同为扁平 string→string 形态，两侧无需结构转换）
+ * @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/langs_admin.js

@@ -0,0 +1,13 @@
+const Admin = require('mm_corejs').Admin;
+const Langs = require('./langs.js');
+
+/**
+ * 语言存储实例管理器（数据侧）
+ * 独立成模块以便 lib/lang.js 引用而不产生循环依赖
+ * Lang 配置 file 时以文件路径为作用域键从管理器取实例，相同文件的 Lang 复用同一存储
+ * @type {Admin}
+ */
+const langs_admin = new Admin();
+langs_admin.setClass(Langs);
+
+module.exports = langs_admin;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mm_lang",
-  "version": "1.0.1",
-  "description": "超级美眉多语言/语言包模块",
+  "version": "3.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 模块测试通过');