mm_lang 2.0.0 → 3.0.1

package/README.md

@@ -9,15 +9,15 @@
 - **当前版本**: 2.0.0
 - **更新日期**: 2026-10-30
 - **Gitee地址**: https://gitee.com/qiuwenwu91/mm_lang
-- **依赖**: `mm_corejs`（管理器）、`mm_kv_store`（键值存储基类）
+- **依赖**: `mm_admin`（管理器）、`mm_kv_store`（键值存储基类）
 
 ## 模块结构
 
 | 文件 | 职责 |
 |---|---|
-| `lib/lang.js` | 行为侧：取词、回退链、复数、格式化，**不做文件 IO** |
-| `lib/langs.js` | 数据侧：string→string 键值、JSON 文件 save/load、值类型校验，**不感知词条嵌套语义** |
-| `lib/store.js` | 适配层：嵌套词条字典 ↔ 扁平键值互转、存储实例装配 |
+| `lib/lang.js` | 行为侧：扁平词条表（`语言.层级键`→文本）上的取词、回退链、复数、格式化，只接受扁平入参，**不做文件 IO** |
+| `lib/langs.js` | 数据侧：string→string 键值、JSON 文件 save/load、值类型校验，**不感知语言词条语义** |
+| `lib/langs_admin.js` | 数据侧管理器：Langs 实例按作用域（文件路径）复用，供 Lang 与 langsAdmin 共用 |
 
 ## 特点
 
@@ -51,7 +51,7 @@ console.log(lang.tc('apple', 3));               // 3 apples
 const persisted = langAdmin('shop', { file: './data/lang.json', default: 'zh_cn' });
 persisted.load();                 // 启动时从文件恢复词条
 persisted.set('nav.home', '首页');
-persisted.save();                 // 扁平化为 "zh_cn.nav.home": "首页" 落盘
+persisted.save();                 // 内存词条表即扁平形态，直接落盘（相同 file 复用同一存储实例）
 
 // 只用存储（原 mm_langs 用法）
 const langs = new Langs({ file: './data/map.json' });
@@ -90,9 +90,11 @@ langs.set('en', 'english').save();
 | 方法 | 签名 | 返回值 | 说明 |
 | --- | --- | --- | --- |
 | setLang | `setLang(lang)` | `String` | 切换语言；找不到时先尝试基础语言映射，仍失败记日志并保持当前语言 |
-| getLangs | `getLangs()` | `Array<String>` | 支持的语言列表（排除 `default`、`fallback`、`locale`、`options`、`file`、`store`） |
+| getLangs | `getLangs()` | `Array<String>` | 支持的语言列表（取词条键首段去重，无词条的语言不会出现） |
 | isSupported | `isSupported(lang)` | `Boolean` | 语言是否支持（含基础语言映射，控制键恒为 false） |
-| del | `del(lang)` | `Boolean` | 删除指定语言配置 |
+| 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)` 返回形式索引 |
 
@@ -101,7 +103,7 @@ langs.set('en', 'english').save();
 | 方法 | 签名 | 返回值 | 说明 |
 | --- | --- | --- | --- |
 | save | `save(file?)` | `Boolean` | 词条扁平化后经存储实例落盘；无存储实例返回 `false`（不抛异常） |
-| load | `load(file?)` | `Boolean` | 从存储实例读取并还原为嵌套字典合并进 `config`，文件中的词条优先；失败返回 `false` 且不改动内存词条 |
+| load | `load(file?)` | `Boolean` | 从存储实例读取扁平键值直接合并进 `config`（结构一致无需转换），文件中的词条优先；失败返回 `false` 且不改动内存词条 |
 
 落盘格式为 `语言代码.层级键 → 文本` 的 string→string 键值，例如：
 
@@ -195,8 +197,7 @@ mm_lang/
 ├── index.js       入口：导出 Lang / Langs / admin / langs_admin / langAdmin / langsAdmin
 ├── lib/
 │   ├── lang.js    行为侧
-│   ├── langs.js   数据侧
-│   └── store.js   适配层
+│   └── langs.js   数据侧
 ├── example/
 │   └── index.js
 ├── test.js
@@ -206,3 +207,12 @@ mm_lang/
 ## 许可证
 
 ISC
+
+## 工具契约（LLM 可调用）
+
+本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
+其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。
+
+| 工具名 | 标题 | 说明 |
+| --- | --- | --- |
+| `lang` | 多语言词条 | 按语言取词、写词条、语言清单 |

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,21 +1,15 @@
 const Lang = require('./lib/lang');
 const Langs = require('./lib/langs');
-const Admin = require('mm_corejs').Admin;
+const langs_admin = require('./lib/langs_admin');
+const { reg } = require('mm_admin');
 
 /**
  * 语言实例管理器（行为侧）
  * @type {Admin}
  */
-let admin = new Admin();
+const admin = reg('lang');
 admin.setClass(Lang);
 
-/**
- * 语言存储实例管理器（数据侧）
- * @type {Admin}
- */
-let langs_admin = new Admin();
-langs_admin.setClass(Langs);
-
 /**
  * 获取语言实例
  * @param {string} scope 作用域
@@ -23,23 +17,19 @@ langs_admin.setClass(Langs);
  * @returns {Lang} 语言实例
  */
 function langAdmin(scope, config) {
-  if (!scope) {
-    scope = 'os';
-  }
-  return admin.get(scope, config);
+  return admin.get(scope || 'os', 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);
+  return langs_admin.get(scope || 'os', config);
 }
 
 module.exports = {
@@ -50,3 +40,7 @@ module.exports = {
   langAdmin,
   langsAdmin
 };
+
+/* mm-tool-logic-export 工具能力层：其它模块可 require("mm_lang").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });