mm_lang 2.0.0 → 3.0.0

package/README.md

@@ -1,208 +1,209 @@
-# 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/store.js` | 适配层：嵌套词条字典 ↔ 扁平键值互转、存储实例装配 |
-
-## 特点
-
-- **行为侧**：零文件 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();                 // 扁平化为 "zh_cn.nav.home": "首页" 落盘
-
-// 只用存储（原 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>` | 支持的语言列表（排除 `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)` 返回形式索引 |
-
-#### 持久化
-
-| 方法 | 签名 | 返回值 | 说明 |
-| --- | --- | --- | --- |
-| 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   数据侧
-│   └── store.js   适配层
-├── example/
-│   └── index.js
-├── test.js
-└── package.json
-```
-
-## 许可证
-
-ISC
+# 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,5 +1,6 @@
 const Lang = require('./lib/lang');
 const Langs = require('./lib/langs');
+const langs_admin = require('./lib/langs_admin');
 const Admin = require('mm_corejs').Admin;
 
 /**
@@ -9,13 +10,6 @@ const Admin = require('mm_corejs').Admin;
 let admin = new Admin();
 admin.setClass(Lang);
 
-/**
- * 语言存储实例管理器（数据侧）
- * @type {Admin}
- */
-let langs_admin = new Admin();
-langs_admin.setClass(Langs);
-
 /**
  * 获取语言实例
  * @param {string} scope 作用域
@@ -31,6 +25,8 @@ function langAdmin(scope, config) {
 
 /**
  * 获取语言存储实例，不存在时创建
+ * 与 Lang 内部使用同一 langs_admin 管理器：以文件路径为作用域时，
+ * 配置了相同 file 的 Lang 与 langsAdmin 取到的是同一个存储实例
  * @param {string} [scope] 作用域名称，缺省时使用 os
  * @param {Object} [config] 配置对象，含 file 持久化文件路径
  * @returns {Langs} 语言存储实例

package/lib/lang.js

@@ -1,45 +1,127 @@
 /**
- * 持久化适配：嵌套词条字典与 Langs 扁平键值互转、存储实例装配
+ * 内置语言类
+ * 国际化(i18n)核心：扁平词条表上的取词、回退、复数与格式化
+ * 词条表与持久化同构：内存即 `语言代码.层级键 → 文本` 的扁平形态，save/load 无需转换
+ * 只接受扁平入参（键为 `语言.层级键`，或 default/fallback/locale/silent/file/store 控制键），
+ * 嵌套语言包由调用方展开（mm_tpl 在加载语言包文件后自行扁平化）
+ * 持久化通过 langsAdmin 管理的 Langs 存储实例（this.store）完成，本类不做文件 IO
+ * @class
  */
-const {
-  flatten,
-  unflatten,
-  assignDeep,
-  isControlKey,
-  createStore
-} = require('./store.js');
+
+const langs_admin = require('./langs_admin.js');
 
 /**
- * 内置语言类
- * 国际化(i18n)核心：按语言字典取值、层级键解析、回退机制、复数形式与格式化
- * 行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量
- * 持久化能力通过组合的 Langs 存储实例（this.store）提供，本类不做文件 IO
- * @class
+ * 非词条的控制键，不参与取词、语言列表与持久化
+ * 词条键必含点号（`语言.键`），控制键均不含点号，二者天然可分
+ * @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、locale、file、store
+   * @param {Object} config - 扁平词条表：键为 `语言.层级键`，值为字符串/数字/布尔/数组；
+   *   可含控制键 default、fallback、locale、silent 及存储配置 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}
      */
     this.config = Object.assign({
-      zh_cn: {},
-      en: {},
       default: 'zh_cn',
       fallback: true
     }, 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 + '" 的值不能是对象，请使用扁平键（语言.层级键）');
+      }
+    }
+
     /**
      * 复数规则表，键为语言代码，值为按数量返回形式的索引的函数
      * @type {Object}
@@ -75,10 +157,11 @@ class Lang {
     this.file = file;
 
     /**
-     * 语言存储实例（数据侧，来自 langs.js），未配置 file 且未注入时为 null
+     * 语言存储实例（数据侧）：优先用注入实例，否则按文件路径经 langsAdmin 取共享实例，
+     * 两者都无则为 null（纯内存）
      * @type {Langs|null}
      */
-    this.store = createStore(injected, file);
+    this.store = injected || (file ? langs_admin.get(file, { file: file }) : null);
   }
 }
 
@@ -103,7 +186,7 @@ Lang.prototype.get = function (key, ...param) {
 };
 
 /**
- * 带回退机制获取语言值 - 内部方法
+ * 带回退机制获取词条 - 内部方法
  * 依次尝试：当前语言、基础语言、默认语言
  * @param {string} key - 键
  * @returns {any} 语言值
@@ -127,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];
 };
 
 /**
@@ -176,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} 切换后的语言代码
  */
@@ -225,12 +262,12 @@ Lang.prototype.setLang = function (lang) {
     this._log('error', '语言未找到: ' + lang);
     return this.now;
   }
-  if (this.config[lang]) {
+  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;
   }
@@ -239,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} 是否删除成功
  */
@@ -247,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;
 };
 
 /**
@@ -368,61 +427,73 @@ 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 (!isControlKey(key) && 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} [file] 本次调用的持久化文件路径
- * @returns {Langs|null} 存储实例
- * @private
+ * 导出某语言的全部词条
+ * 扁平词条按前缀取出并还原为嵌套字典，形态与语言包文件一致
+ * @param {string} lang - 语言代码
+ * @returns {Object|null} 嵌套词条字典，该语言无词条时返回 null
  */
-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;
+Lang.prototype.getDict = function (lang) {
+  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
+    return null;
   }
-  var target = file || this.file;
-  if (target) {
-    this.store = createStore(null, target);
-    this.file = target;
-    return this.store;
+  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 null;
+  return dict;
 };
 
 /**
  * 保存语言包到持久化文件
- * 词条扁平化为 `语言代码.层级键 → 文本` 后写入存储实例，再由存储实例落盘
- * @param {string} [file] 持久化文件路径，缺省时用实例的 file 配置
+ * 内存词条表即扁平 string→string 形态（数组值按标记编码），直接写入存储实例落盘
  * @returns {boolean} 是否保存成功
  */
-Lang.prototype.save = function (file) {
-  var store = this._getStore(file);
-  if (!store) {
+Lang.prototype.save = function () {
+  if (!this.store) {
     this._log('error', '未配置持久化文件路径或存储实例，无法保存语言包');
     return false;
   }
-  var flat = flatten(this.config);
   try {
-    store.clear();
-    for (var key in flat) {
-      store.set(key, flat[key]);
+    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 store.save() !== false;
+    return this.store.save() !== false;
   } catch (e) {
     this._log('error', '语言包保存失败: ' + e.message);
     return false;
@@ -431,19 +502,17 @@ Lang.prototype.save = function (file) {
 
 /**
  * 从持久化文件加载语言包
- * 扁平键值还原为嵌套字典后合并进当前配置，文件中的词条优先
- * @param {string} [file] 持久化文件路径，缺省时用实例的 file 配置
+ * 存储中的扁平键值与内存结构一致，直接合并进词条表（文件中的词条优先），数组编码值还原
  * @returns {boolean} 是否加载成功
  */
-Lang.prototype.load = function (file) {
-  var store = this._getStore(file);
-  if (!store || typeof (store.load) !== 'function') {
+Lang.prototype.load = function () {
+  if (!this.store) {
     this._log('error', '未配置持久化文件路径或存储实例，无法加载语言包');
     return false;
   }
   var ok = false;
   try {
-    ok = store.load();
+    ok = this.store.load();
   } catch (e) {
     this._log('error', '语言包加载失败: ' + e.message);
     return false;
@@ -451,7 +520,12 @@ Lang.prototype.load = function (file) {
   if (!ok) {
     return false;
   }
-  assignDeep(this.config, unflatten(store.list()));
+  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;
 };
 
@@ -464,7 +538,7 @@ Lang.prototype.isSupported = function (lang) {
   if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
     return false;
   }
-  return !!this.config[lang] || !!this.config[this._getBase(lang)];
+  return this.hasLang(lang) || this.hasLang(this._getBase(lang));
 };
 
 /**

package/lib/langs.js

@@ -1,32 +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;
+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,6 +1,6 @@
 {
   "name": "mm_lang",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "超级美眉多语言模块：融合 i18n 行为（Lang）与语言存储持久化（Langs），支持层级键、回退链、复数、格式化与 JSON 文件落盘",
   "main": "index.js",
   "repository": {

package/lib/store.js

@@ -1,190 +0,0 @@
-/**
- * 语言词条持久化适配层
- * @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
-};