mm_lang 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# mm_lang
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+超级美眉多语言/语言包模块，提供 `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
+```

package/example/index.js

@@ -0,0 +1,54 @@
+/**
+ * mm_lang 多语言/语言包模块示例
+ * 演示 Lang 类的翻译（get/t）、语言切换（setLang）与复数形式（tc）
+ * 运行：node example/index.js
+ */
+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']
+    },
+    default: 'zh_cn'
+  });
+
+  // 翻译并替换占位符
+  console.log('zh_cn hello ->', lang.get('hello', '张三'));
+
+  // 切换语言
+  lang.setLang('en');
+  console.log('en hello ->', lang.t('hello', 'Tom'));
+
+  // en 的复数形式按数量区分
+  console.log('en order.count(1) ->', lang.tc('order.count', 1));
+  console.log('en order.count(5) ->', lang.tc('order.count', 5));
+
+  // 切换回中文
+  lang.setLang('zh_cn');
+  console.log('zh_cn greet(1) ->', lang.tc('greet', 1));
+  console.log('支持的语言列表 ->', lang.getLangs().join(', '));
+
+  // 动态设置词条
+  lang.set('bye', '再见');
+  console.log('新词条 bye ->', lang.get('bye'));
+}
+
+main();

package/index.js

@@ -0,0 +1,24 @@
+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
+};

package/lib/lang.js

@@ -0,0 +1,372 @@
+/**
+ * 内置语言类
+ * 国际化(i18n)核心：按语言字典取值、层级键解析、回退机制、复数形式与格式化
+ * 行为对齐 mm_expand 的 Lang，但不依赖外部模块与全局变量
+ * @class
+ */
+class Lang {
+  /**
+   * 创建语言实例
+   * @param {Object} config - 语言包配置，键为语言代码，值可为词条对象；可含 default 与 fallback
+   */
+  constructor(config = {}) {
+    /**
+     * 语言包配置，语言代码对应词条字典
+     * @type {Object}
+     */
+    this.config = Object.assign({
+      zh_cn: {},
+      en: {},
+      default: 'zh_cn',
+      fallback: true
+    }, config);
+
+    /**
+     * 复数规则表，键为语言代码，值为按数量返回形式的索引的函数
+     * @type {Object}
+     */
+    this.rules = {
+      en: function (count) {
+        return count === 1 ? 0 : 1;
+      },
+      zh_cn: function () {
+        return 0;
+      }
+    };
+
+    /**
+     * 当前语言代码
+     * @type {string}
+     */
+    this.now = this.config.default || 'zh_cn';
+
+    /**
+     * 区域映射表，完整语言代码到基础语言代码
+     * @type {Object}
+     */
+    this.locale = Object.assign({
+      zh: 'zh_cn',
+      en: 'en'
+    }, this.config.locale);
+  }
+}
+
+/**
+ * 获取翻译文本
+ * @param {string} key - 键，支持 a.b 形式的层级键
+ * @param {...any} param - 参数，依次替换 {0}、{1} 等占位符
+ * @returns {string} 翻译后的文本
+ */
+Lang.prototype.get = function (key, ...param) {
+  if (!key || typeof (key) !== 'string') {
+    throw new TypeError('key必须是字符串');
+  }
+  var val = this._getVal(key);
+  if (typeof (val) === 'string' && param.length > 0) {
+    for (var i = 0; i < param.length; i++) {
+      var reg = new RegExp('\\{' + i + '\\}', 'ig');
+      val = val.replace(reg, param[i]);
+    }
+  }
+  return val;
+};
+
+/**
+ * 带回退机制获取语言值 - 内部方法
+ * 依次尝试：当前语言、基础语言、默认语言
+ * @param {string} key - 键
+ * @returns {any} 语言值
+ * @private
+ */
+Lang.prototype._getVal = function (key) {
+  var val = this._getFrom(this.now, key);
+  if (val === undefined && this.config.fallback) {
+    var lang = this._getBase(this.now);
+    if (lang && lang !== this.now) {
+      val = this._getFrom(lang, key);
+    }
+    if (val === undefined && this.config.default && this.config.default !== this.now) {
+      val = this._getFrom(this.config.default, key);
+    }
+  }
+  if (val === undefined) {
+    this._log('error', '语言包错误: ' + key + ' 未定义');
+  }
+  return val;
+};
+
+/**
+ * 从指定语言中获取值 - 内部方法
+ * @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;
+};
+
+/**
+ * 获取基础语言代码 - 内部方法
+ * @param {string} lang - 完整语言代码
+ * @returns {string} 基础语言代码
+ * @private
+ */
+Lang.prototype._getBase = function (lang) {
+  if (this.locale[lang]) {
+    return this.locale[lang];
+  }
+  var parts = lang.split('-');
+  return parts.length > 1 ? parts[0] : lang;
+};
+
+/**
+ * 设置语言键值到当前语言
+ * @param {string} key - 键名，支持 a.b 形式的层级键
+ * @param {any} val - 值
+ * @returns {any} 返回设置的值
+ */
+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];
+    }
+  }
+  return val;
+};
+
+/**
+ * 切换语言
+ * @param {string} lang - 语言代码
+ * @returns {string} 切换后的语言代码
+ */
+Lang.prototype.setLang = function (lang) {
+  if (!lang || typeof (lang) !== 'string') {
+    throw new TypeError('lang必须是字符串');
+  }
+  if (this.config[lang]) {
+    this.now = lang;
+    return this.now;
+  }
+  var base_lang = this._getBase(lang);
+  if (this.config[base_lang]) {
+    this.now = base_lang;
+    return this.now;
+  }
+  this._log('error', '语言未找到: ' + lang);
+  return this.now;
+};
+
+/**
+ * 删除语言配置
+ * @param {string} lang - 语言代码
+ * @returns {boolean} 是否删除成功
+ */
+Lang.prototype.del = function (lang) {
+  if (!lang || typeof (lang) !== 'string') {
+    throw new TypeError('lang必须是字符串');
+  }
+  if (this.config[lang]) {
+    delete this.config[lang];
+    return true;
+  }
+  return false;
+};
+
+/**
+ * 翻译
+ * @param {string} key - 键
+ * @param {...any} param - 参数
+ * @returns {string} 翻译后的文本
+ */
+Lang.prototype.t = function (key, ...param) {
+  return this.get(key, ...param);
+};
+
+/**
+ * 翻译带复数形式的文本
+ * 词条值为数组时按复数规则取索引，先替换 {count}，再依次替换 {1}、{2} 等占位符
+ * @param {string} key - 键
+ * @param {number} count - 数量，用于确定复数形式
+ * @param {...any} param - 额外参数
+ * @returns {string} 翻译后的文本
+ */
+Lang.prototype.tc = function (key, count, ...param) {
+  if (!key || typeof (key) !== 'string') {
+    throw new TypeError('key必须是字符串');
+  }
+  if (typeof (count) !== 'number') {
+    throw new TypeError('count必须是数字');
+  }
+  var lang = this.now;
+  var rule = this.rules[lang] || this.rules[this._getBase(lang)] || this.rules['en'];
+  var idx = rule(count);
+  var obj = this._getVal(key);
+  var val;
+  if (typeof (obj) === 'object' && obj !== null) {
+    val = obj[idx];
+  }
+  if (typeof (val) === 'string') {
+    val = val.replace(/\{count\}/ig, count);
+    for (var i = 0; i < param.length; i++) {
+      var reg = new RegExp('\\{' + (i + 1) + '\\}', 'ig');
+      val = val.replace(reg, param[i]);
+    }
+  }
+  return val;
+};
+
+/**
+ * 格式化日期
+ * @param {Date|number} dt - 日期对象或时间戳
+ * @param {string} format - 格式，默认 YYYY-MM-DD hh:mm:ss
+ * @returns {string} 格式化后的日期字符串
+ */
+Lang.prototype.formatDate = function (dt, format) {
+  if (!dt) {
+    throw new TypeError('date不能为空');
+  }
+  var fmt = format || 'YYYY-MM-DD hh:mm:ss';
+  var d = new Date(dt);
+  if (isNaN(d.getTime())) {
+    throw new TypeError('无效的日期');
+  }
+  var year = d.getFullYear();
+  var month = String(d.getMonth() + 1).padStart(2, '0');
+  var day = String(d.getDate()).padStart(2, '0');
+  var hours = String(d.getHours()).padStart(2, '0');
+  var minutes = String(d.getMinutes()).padStart(2, '0');
+  var seconds = String(d.getSeconds()).padStart(2, '0');
+  return fmt
+    .replace('YYYY', year)
+    .replace('yyyy', year)
+    .replace('MM', month)
+    .replace('DD', day)
+    .replace('dd', day)
+    .replace('HH', hours)
+    .replace('hh', hours)
+    .replace('mm', minutes)
+    .replace('ss', seconds);
+};
+
+/**
+ * 格式化数字
+ * @param {number} num - 要格式化的数字
+ * @param {Object} options - 选项，含 decimals、decimal_separator、thousands_separator
+ * @returns {string} 格式化后的数字字符串
+ */
+Lang.prototype.formatNumber = function (num, options) {
+  if (typeof (num) !== 'number' || isNaN(num)) {
+    throw new TypeError('num必须是有效的数字');
+  }
+  var opt = options || {};
+  var decimals = typeof (opt.decimals) === 'number' ? opt.decimals : 2;
+  var decimal_sepa = opt.decimal_separator || '.';
+  var thou_sepa = opt.thousands_separator || ',';
+  var parts = num.toFixed(decimals).split('.');
+  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, thou_sepa);
+  return parts.join(decimal_sepa);
+};
+
+/**
+ * 注册语言复数规则
+ * @param {string} lang - 语言代码
+ * @param {Function} rule - 复数规则函数，按数量返回形式的索引
+ * @returns {boolean} 是否注册成功
+ */
+Lang.prototype.registerPlural = function (lang, rule) {
+  if (!lang || typeof (lang) !== 'string') {
+    throw new TypeError('lang必须是字符串');
+  }
+  if (typeof (rule) !== 'function') {
+    throw new TypeError('rule必须是函数');
+  }
+  this.rules[lang] = rule;
+  return true;
+};
+
+/**
+ * 获取支持的语言列表
+ * @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);
+    }
+  }
+  return langs;
+};
+
+/**
+ * 检查语言是否支持
+ * @param {string} lang - 语言代码
+ * @returns {boolean} 是否支持
+ */
+Lang.prototype.isSupported = function (lang) {
+  return !!this.config[lang] || !!this.config[this._getBase(lang)];
+};
+
+/**
+ * 输出日志 - 内部方法，使用 console
+ * @param {string} level - 日志级别
+ * @param {string} message - 日志消息
+ * @param {...any} args - 附加参数
+ * @private
+ */
+Lang.prototype._log = function (level, message, ...args) {
+  var fn = console[level] || console.log;
+  if (typeof (fn) === 'function') {
+    fn.call(console, message, ...args);
+  }
+};
+
+module.exports = Lang;

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "mm_lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "超级美眉多语言/语言包模块",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_lang.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_common"
+  ],
+  "layer": "infra",
+  "group": "common",
+  "author": "邱文武",
+  "license": "ISC",
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/test.js

@@ -0,0 +1,18 @@
+'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 模块测试通过');