mm_lang 3.0.0 → 3.0.1

package/README.md

@@ -1,209 +1,218 @@
-# 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
+# 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_admin`（管理器）、`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
+
+## 工具契约（LLM 可调用）
+
+本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
+其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。
+
+| 工具名 | 标题 | 说明 |
+| --- | --- | --- |
+| `lang` | 多语言词条 | 按语言取词、写词条、语言清单 |

package/index.js

@@ -1,13 +1,13 @@
 const Lang = require('./lib/lang');
 const Langs = require('./lib/langs');
 const langs_admin = require('./lib/langs_admin');
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 
 /**
  * 语言实例管理器（行为侧）
  * @type {Admin}
  */
-let admin = new Admin();
+const admin = reg('lang');
 admin.setClass(Lang);
 
 /**
@@ -17,10 +17,7 @@ admin.setClass(Lang);
  * @returns {Lang} 语言实例
  */
 function langAdmin(scope, config) {
-  if (!scope) {
-    scope = 'os';
-  }
-  return admin.get(scope, config);
+  return admin.get(scope || 'os', config);
 }
 
 /**
@@ -32,10 +29,7 @@ function langAdmin(scope, config) {
  * @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 = {
@@ -46,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'); } });