schema-dsl 1.0.8 → 1.1.0

package/docs/dsl-syntax.md

@@ -649,5 +649,5 @@ dsl.match('vipLevel', { gold: 'number:0-50', silver: 'number:0-20' })
 ---
 
 **最后更新**: 2025-12-29  
-**作者**: SchemaIO Team
+**作者**: SchemaI-DSL Team
 

package/docs/dynamic-locale.md

@@ -18,7 +18,7 @@
 
 ## 基本原理
 
-SchemaIO 的 `Validator` 支持在验证时动态指定语言，无需全局切换。
+SchemaI-DSL 的 `Validator` 支持在验证时动态指定语言，无需全局切换。
 
 ### 核心方法
 
@@ -34,67 +34,113 @@ validator.validate(schema, data, {
 
 这是**最推荐**的方案，无需修改全局状态，支持并发请求。
 
-### 1.1 全局配置
+### 1.1 应用启动时配置（一次性加载所有语言）
 
-使用 `dsl.config` 可以方便地加载自定义语言包。
+使用 `dsl.config` 在应用启动时一次性加载所有自定义语言包。
 
 ```javascript
-const { dsl, Validator } = require('schema-dsl');
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
 
-// 方式一：直接传入对象
+// ========== 应用启动时配置（只执行一次）==========
+
+// 方式一：传入目录路径（推荐）⭐
+// 自动扫描目录下的所有 .js 和 .json 文件
+dsl.config({
+  i18n: path.join(__dirname, 'locales')
+});
+
+// 方式二：直接传入对象
 dsl.config({
-  locales: {
+  i18n: {
     'fr-FR': {
       'required': '{{#label}} est requis',
-      'pattern.phone.cn': 'Numéro de téléphone invalide'
+      'string.minLength': '{{#label}} doit contenir au moins {{#limit}} caractères'
+    },
+    'de-DE': {
+      'required': '{{#label}} ist erforderlich',
+      'string.minLength': '{{#label}} muss mindestens {{#limit}} Zeichen lang sein'
     }
   }
 });
 
-// 方式二：传入目录路径
-// 目录下应包含 zh-CN.js, en-US.js 等文件
-dsl.config({
-  locales: './locales'
-});
+// 说明：
+// - 只在应用启动时执行一次
+// - 自动与系统内置语言包合并（用户自定义的优先）
+// - 运行时无需重新加载，直接切换
 ```
 
-### 1.2 基础用法
+### 1.2 运行时直接切换语言（无需重新加载）
 
 ```javascript
-// 定义Schema
+const { dsl, validate } = require('schema-dsl');
+
+// 定义 Schema
 const schema = dsl({
-  username: 'string:3-32!'.label('用户名'),
-  email: 'email!'.label('邮箱地址')
+  username: 'string:3-32!',
+  email: 'email!'
 });
 
-// 创建验证器
-const validator = new Validator();
+// 测试数据
+const data = { username: 'ab', email: 'invalid' };
+
+// ========== 运行时直接切换语言 ==========
+
+// 使用中文
+const result1 = validate(schema, data, { locale: 'zh-CN' });
+// 错误: "username长度不能少于3个字符"
+
+// 使用法语
+const result2 = validate(schema, data, { locale: 'fr-FR' });
+// 错误: "username doit contenir au moins 3 caractères"
 
-// 验证时动态指定语言
-const result1 = validator.validate(schema, data, { locale: 'zh-CN' });
-const result2 = validator.validate(schema, data, { locale: 'fr-FR' });
+// 使用德语
+const result3 = validate(schema, data, { locale: 'de-DE' });
+// 错误: "username muss mindestens 3 Zeichen lang sein"
+
+// 说明：
+// - 无需重新加载语言包
+// - 每次验证可以使用不同语言
+// - 支持高并发（无全局状态修改）
 ```
 
-### 1.3 从请求头获取语言
+### 1.3 从请求头获取语言（实际应用场景）
 
 ```javascript
-// Express 示例
+const express = require('express');
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
+
+const app = express();
+
+// ========== 应用启动时配置（只执行一次）==========
+dsl.config({
+  i18n: path.join(__dirname, 'locales')
+});
+
+// 定义 Schema
+const userSchema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  password: 'string:8-32!'
+});
+
+// ========== Express 路由 ==========
 app.post('/api/user/register', (req, res) => {
-  // 从请求头获取语言
+  // 从请求头获取语言偏好
   const locale = req.headers['accept-language'] || 'en-US';
   
-  // 验证数据
-  const result = validator.validate(schema, req.body, { 
-    locale: locale 
-  });
+  // 验证数据（直接切换语言，无需重新加载）
+  const result = validate(userSchema, req.body, { locale });
   
   if (!result.valid) {
     return res.status(400).json({
-      errors: result.errors  // 自动使用对应语言的错误消息
+      errors: result.errors  // 自动使用用户偏好的语言
     });
   }
   
   // 处理成功...
+  res.json({ message: 'User registered successfully' });
 });
 ```
 
@@ -547,6 +593,6 @@ const schema = dsl({
 ---
 
 **最后更新**: 2025-12-25  
-**作者**: SchemaIO Team
+**作者**: SchemaI-DSL Team
 
 

package/docs/error-handling.md

@@ -23,7 +23,7 @@
 
 ### 基础结构
 
-SchemaIO 验证返回的错误对象结构：
+SchemaI-DSL 验证返回的错误对象结构：
 
 ```javascript
 const { dsl, validate } = require('schema-dsl');
@@ -165,7 +165,7 @@ Locale.setMessages({
 
 ### 内置错误码（简化版）
 
-SchemaIO 对 ajv 的错误关键字进行了简化映射，使其更易用：
+SchemaI-DSL 对 ajv 的错误关键字进行了简化映射，使其更易用：
 
 #### 字符串错误码
 

package/docs/export-guide.md

@@ -3,7 +3,7 @@
 > **用途**: Schema 到数据库 DDL 的完整导出指南  
 > **阅读时间**: 10分钟
 
-> ⚠️ **重要提示**: 并非所有 SchemaIO 特性都能导出到数据库。请先阅读 [导出限制说明](export-limitations.md) 了解哪些特性不支持导出。
+> ⚠️ **重要提示**: 并非所有 SchemaI-DSL 特性都能导出到数据库。请先阅读 [导出限制说明](export-limitations.md) 了解哪些特性不支持导出。
 
 ---
 
@@ -21,7 +21,7 @@
 
 ## 概述
 
-SchemaIO 支持将 JSON Schema 导出为多种数据库的 DDL 语句，实现"一次定义，多处使用"。
+SchemaI-DSL 支持将 JSON Schema 导出为多种数据库的 DDL 语句，实现"一次定义，多处使用"。
 
 ### 支持的数据库
 

package/docs/export-limitations.md

@@ -49,7 +49,7 @@ const schema = dsl({
 
 **替代方案**:
 - 导出为最宽松的类型（`VARCHAR(255)`）
-- 验证逻辑保留在应用层（使用 SchemaIO 验证器）
+- 验证逻辑保留在应用层（使用 SchemaI-DSL 验证器）
 
 ---
 
@@ -331,7 +331,7 @@ const schema = dsl('string!')
 
 ```
 ┌─────────────────────────────────────────┐
-│  应用层（SchemaIO 完整验证）             │
+│  应用层（SchemaI-DSL 完整验证）             │
 │  - 条件逻辑（match/if）                 │
 │  - 自定义验证器                         │
 │  - 复杂约束（正则、范围等）              │
@@ -449,7 +449,7 @@ module.exports = {
 ```markdown
 ## 数据验证说明
 
-### 应用层验证（SchemaIO）
+### 应用层验证（SchemaI-DSL）
 - ✅ `contact` 字段根据 `contactType` 动态验证
 - ✅ 用户名正则验证（`^[a-zA-Z0-9_]+$`）
 - ✅ 自定义业务规则验证

package/docs/faq.md

@@ -20,12 +20,12 @@
 
 ## 基础问题
 
-### Q: SchemaIO 和 Joi、Yup 有什么区别？
+### Q: SchemaI-DSL 和 Joi、Yup 有什么区别？
 
-**A**: SchemaIO 采用 DSL 语法，更简洁：
+**A**: SchemaI-DSL 采用 DSL 语法，更简洁：
 
 ```javascript
-// SchemaIO - 简洁
+// SchemaI-DSL - 简洁
 const schema = dsl({
   username: 'string:3-32!',
   email: 'email!'
@@ -46,7 +46,7 @@ const schema = Joi.object({
 
 ---
 
-### Q: 如何安装 SchemaIO？
+### Q: 如何安装 SchemaI-DSL？
 
 ```bash
 npm install schema-dsl
@@ -299,7 +299,7 @@ app.post('/api/users', (req, res) => {
 
 ### Q: 缓存如何工作？
 
-**A**: SchemaIO 内置 LRU 缓存：
+**A**: SchemaI-DSL 内置 LRU 缓存：
 
 ```javascript
 const validator = new Validator({
@@ -523,7 +523,7 @@ MySQL 会生成 `COMMENT`，PostgreSQL 会生成 `COMMENT ON COLUMN`。
 
 ## TypeScript 支持
 
-### Q: SchemaIO 支持 TypeScript 吗？
+### Q: SchemaI-DSL 支持 TypeScript 吗？
 
 **A**: 支持，类型定义在 `index.d.ts`：
 

package/docs/frontend-i18n-guide.md

@@ -21,23 +21,16 @@
 // server.js
 const express = require('express');
 const cors = require('cors');
-const { Validator, dsl } = require('schema-dsl');
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
 
 const app = express();
 app.use(cors());
 app.use(express.json());
 
-// 语言中间件
-app.use((req, res, next) => {
-  const acceptLanguage = req.headers['accept-language'] || 'en-US';
-  const locale = acceptLanguage.split(',')[0].trim();
-  
-  req.validator = new Validator({ 
-    locale,
-    allErrors: true  // 返回所有错误
-  });
-  
-  next();
+// ========== 应用启动时配置（只执行一次）==========
+dsl.config({
+  i18n: path.join(__dirname, 'locales')  // 一次性加载所有语言包
 });
 
 // Schema 定义
@@ -66,18 +59,27 @@ app.post('/api/validate/:type', (req, res) => {
     return res.status(404).json({ error: 'Schema not found' });
   }
   
-  const result = req.validator.validate(schema, req.body);
+  // 从请求头获取语言偏好
+  const locale = req.headers['accept-language'] || 'en-US';
+  
+  // 验证（直接切换语言，无需重新加载）
+  const result = validate(schema, req.body, { locale });
+  
   res.json(result);
 });
 
 // 用户注册（带验证）
 app.post('/api/register', (req, res) => {
-  const result = req.validator.validate(schemas.user, req.body);
+  // 从请求头获取语言偏好
+  const locale = req.headers['accept-language'] || 'en-US';
+  
+  // 验证数据
+  const result = validate(schemas.user, req.body, { locale });
   
   if (!result.valid) {
     return res.status(400).json({
       success: false,
-      errors: result.errors
+      errors: result.errors  // 自动使用用户偏好的语言
     });
   }
   
@@ -87,6 +89,7 @@ app.post('/api/register', (req, res) => {
 
 app.listen(3000, () => {
   console.log('Server running on http://localhost:3000');
+  console.log('语言包已加载，支持动态切换');
 });
 ```
 
@@ -247,7 +250,7 @@ Locale.addLocale('de-DE', {
 **A**: 后端返回错误消息已经是本地化的，前端无需处理。如果需要前端验证：
 
 ```javascript
-// 前端可以使用相同的 SchemaIO（浏览器版）
+// 前端可以使用相同的 SchemaI-DSL（浏览器版）
 import { dsl, validate } from 'schema-dsl/browser';
 
 const schema = dsl({ /* ... */ });

package/docs/i18n-user-guide.md

@@ -25,15 +25,13 @@ const { dsl, validate } = require('schema-dsl');
 // 1. 配置用户语言包
 dsl.config({
   i18n: {
-    locales: {
-      'zh-CN': {
-        'username': '用户名',
-        'email': '邮箱地址'
-      },
-      'en-US': {
-        'username': 'Username',
-        'email': 'Email Address'
-      }
+    'zh-CN': {
+      'username': '用户名',
+      'email': '邮箱地址'
+    },
+    'en-US': {
+      'username': 'Username',
+      'email': 'Email Address'
     }
   }
 });

package/docs/i18n.md

@@ -1,7 +1,19 @@
 # 多语言配置指南
 
-**版本**: v1.0.1  
-**最后更新**: 2025-12-31
+**版本**: v1.0.9  
+**最后更新**: 2026-01-04
+
+---
+
+## 📚 多语言文档导航
+
+根据你的需求选择合适的文档：
+
+- 🚀 **新手快速上手**: [i18n.md](./i18n.md)（当前文档）- 5分钟学会基础用法
+- 📖 **完整使用指南**: [i18n-user-guide.md](./i18n-user-guide.md) - 详细的用户指南和最佳实践
+- 🎯 **添加新语言**: [add-custom-locale.md](./add-custom-locale.md) - 添加自定义语言包教程
+- 🔄 **动态切换语言**: [dynamic-locale.md](./dynamic-locale.md) - API开发中的动态语言切换
+- 🌐 **前端集成**: [frontend-i18n-guide.md](./frontend-i18n-guide.md) - 前后端分离项目集成指南
 
 ---
 
@@ -9,10 +21,61 @@
 
 schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错误消息的翻译。
 
+**v1.0.9 新增**：
+- ✅ 支持参数化语言切换（无需修改全局状态）
+- ✅ 支持自定义错误消息（三种格式）
+- ✅ TypeScript 类型定义完整
+
 ---
 
 ## 🚀 快速开始
 
+### 方式1：验证时动态指定语言（推荐）⭐
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const schema = dsl({ username: 'string:3-32!' });
+
+// 使用中文错误消息
+const result = validate(schema, { username: 'ab' }, { locale: 'zh-CN' });
+// message: "username长度不能少于3个字符"
+
+// 使用英文错误消息
+const result2 = validate(schema, { username: 'ab' }, { locale: 'en-US' });
+// message: "username length must be at least 3"
+```
+
+### 方式2：使用全局配置（向后兼容）
+
+```javascript
+const { Locale } = require('schema-dsl');
+
+// 设置默认语言
+Locale.setLocale('zh-CN');
+
+// 后续验证会使用中文错误消息
+const result = validate(schema, data);
+```
+
+---
+
+## 📝 内置语言支持
+
+schema-dsl 内置了以下语言包：
+
+| 语言代码 | 语言名称 | 支持状态 |
+|---------|---------|---------|
+| `zh-CN` | 简体中文 | ✅ 完整支持 |
+| `en-US` | 英语（美国）| ✅ 完整支持 |
+| `ja-JP` | 日语 | ✅ 完整支持 |
+| `es-ES` | 西班牙语 | ✅ 完整支持 |
+| `fr-FR` | 法语 | ✅ 完整支持 |
+
+---
+
+## 🎯 高级用法
+
 ### 基础配置
 
 ```javascript

package/docs/mongodb-exporter.md

@@ -19,7 +19,7 @@
 
 ## 概述
 
-`MongoDBExporter` 将 SchemaIO 生成的 JSON Schema 转换为 MongoDB 的 `$jsonSchema` 验证格式，可直接用于创建集合时的文档验证。
+`MongoDBExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 MongoDB 的 `$jsonSchema` 验证格式，可直接用于创建集合时的文档验证。
 
 ### 核心功能
 
@@ -104,7 +104,7 @@ const mongoSchema = exporter.export(jsonSchema);
 ```
 
 **参数**：
-- `jsonSchema` (Object): SchemaIO 生成的 JSON Schema 对象
+- `jsonSchema` (Object): SchemaI-DSL 生成的 JSON Schema 对象
 
 **返回值**：
 - `Object`: 包含 `$jsonSchema` 的 MongoDB 验证对象
@@ -272,7 +272,7 @@ async function createValidatedCollection() {
 
 ## 导出限制
 
-⚠️ **重要提示**: 并非所有 SchemaIO 特性都能导出到数据库 Schema。
+⚠️ **重要提示**: 并非所有 SchemaI-DSL 特性都能导出到数据库 Schema。
 
 **不支持导出的特性**:
 - ❌ 条件验证逻辑（`dsl.match()`, `dsl.if()`）

package/docs/multi-type-support.md

@@ -1,8 +1,17 @@
 # 多类型支持设计说明
 
+---
+
+## 📖 快速导航
+
+- **单一类型验证**（本文档）
+- **[联合类型验证](./union-type-guide.md)** - 一个字段支持多种类型（使用 `.pattern()` 正则匹配）
+
+---
+
 ## 🎯 设计原理
 
-SchemaIO通过**类型无关的Builder模式**实现多类型支持。
+schema-dsl通过**类型无关的Builder模式**实现多类型支持。
 
 ### 核心设计
 
@@ -21,6 +30,7 @@ class DslBuilder {
 
 ---
 
+
 ## 📊 类型支持矩阵
 
 | DSL字符串 | 解析类型 | 支持的方法 |
@@ -307,7 +317,7 @@ amount: 'number:0-10000'
 
 ## 💡 总结
 
-SchemaIO的多类型支持采用**类型无关Builder + 方法智能适配**设计：
+SchemaI-DSL的多类型支持采用**类型无关Builder + 方法智能适配**设计：
 
 1. **统一入口**: 所有类型都通过DslBuilder
 2. **类型感知**: 方法内部检查类型兼容性

package/docs/mysql-exporter.md

@@ -19,7 +19,7 @@
 
 ## 概述
 
-`MySQLExporter` 将 SchemaIO 生成的 JSON Schema 转换为 MySQL 的 DDL 语句，包括 `CREATE TABLE` 和索引创建语句。
+`MySQLExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 MySQL 的 DDL 语句，包括 `CREATE TABLE` 和索引创建语句。
 
 ### 核心功能
 

package/docs/plugin-system.md

@@ -20,7 +20,7 @@
 
 ## 概述
 
-SchemaIO 插件系统允许你扩展核心功能，添加自定义验证器、格式化器、导出器等。
+SchemaI-DSL 插件系统允许你扩展核心功能，添加自定义验证器、格式化器、导出器等。
 
 ### 特性
 
@@ -342,7 +342,7 @@ pluginManager.register({
 安装插件。
 
 **参数**:
-- `schema-dsl` (Object) - SchemaIO 实例
+- `schema-dsl` (Object) - SchemaI-DSL 实例
 - `pluginName` (String, optional) - 插件名称
 - `options` (Object, optional) - 安装选项
 
@@ -354,7 +354,7 @@ pluginManager.register({
 
 **参数**:
 - `pluginName` (String) - 插件名称
-- `schema-dsl` (Object) - SchemaIO 实例
+- `schema-dsl` (Object) - SchemaI-DSL 实例
 
 **返回**: `this`
 
@@ -398,7 +398,7 @@ pluginManager.register({
 清空所有插件。
 
 **参数**:
-- `schema-dsl` (Object) - SchemaIO 实例
+- `schema-dsl` (Object) - SchemaI-DSL 实例
 
 **返回**: `this`
 

package/docs/postgresql-exporter.md

@@ -20,7 +20,7 @@
 
 ## 概述
 
-`PostgreSQLExporter` 将 SchemaIO 生成的 JSON Schema 转换为 PostgreSQL 的 DDL 语句，支持丰富的 PostgreSQL 特性。
+`PostgreSQLExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 PostgreSQL 的 DDL 语句，支持丰富的 PostgreSQL 特性。
 
 ### 核心功能
 

package/docs/quick-start.md

@@ -413,13 +413,13 @@ uninstallStringExtensions();
 
 ### Q: 支持TypeScript吗？
 
-**A**: 支持！SchemaIO提供完整的TypeScript类型定义。
+**A**: 支持！SchemaI-DSL提供完整的TypeScript类型定义。
 
 ---
 
 ## 🎉 恭喜！
 
-你已经掌握了SchemaIO的核心用法！
+你已经掌握了SchemaI-DSL的核心用法！
 
 **核心要点**:
 1. ✅ DSL语法简洁直观
@@ -737,13 +737,13 @@ uninstallStringExtensions();
 
 ### Q: 支持TypeScript吗？
 
-**A**: 支持！SchemaIO提供完整的TypeScript类型定义。
+**A**: 支持！SchemaI-DSL提供完整的TypeScript类型定义。
 
 ---
 
 ## 🎉 恭喜！
 
-你已经掌握了SchemaIO的核心用法！
+你已经掌握了SchemaI-DSL的核心用法！
 
 **核心要点**:
 1. ✅ DSL语法简洁直观

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # 常见问题排查指南
 
-> **用途**: 快速解决 SchemaIO 使用中的常见问题  
+> **用途**: 快速解决 SchemaI-DSL 使用中的常见问题  
 > **更新**: 2025-12-26  
 
 ---
@@ -378,7 +378,7 @@ db.createCollection('users', {
 
 **解决方案**:
 ```javascript
-// SchemaIO 默认会自动安装 String 扩展
+// SchemaI-DSL 默认会自动安装 String 扩展
 // 如果未生效，手动安装：
 const { installStringExtensions } = require('schema-dsl');
 installStringExtensions();

package/docs/type-reference.md

@@ -8,7 +8,7 @@
 
 ### 基本类型
 
-| 类型 | SchemaIO | JSON Schema | 说明 |
+| 类型 | SchemaI-DSL | JSON Schema | 说明 |
 |------|----------|-------------|------|
 | 字符串 | `string` | `{ type: 'string' }` | 文本类型 |
 | 数字 | `number` | `{ type: 'number' }` | 浮点数 |
@@ -23,7 +23,7 @@
 
 ### 格式类型（基于 string）
 
-| 类型 | SchemaIO | JSON Schema format | 说明 |
+| 类型 | SchemaI-DSL | JSON Schema format | 说明 |
 |------|----------|-------------------|------|
 | 邮箱 | `email` | `email` | 邮箱地址 |
 | URL | `url` | `uri` | 网址 |
@@ -38,7 +38,7 @@
 
 ### 特殊类型
 
-| 类型 | SchemaIO | JSON Schema | 说明 |
+| 类型 | SchemaI-DSL | JSON Schema | 说明 |
 |------|----------|-------------|------|
 | 二进制 | `binary` | `contentEncoding: base64` | Base64编码 |
 | ObjectId | `objectId` | `pattern: ^[0-9a-fA-F]{24}$` | MongoDB ObjectId |
@@ -156,7 +156,7 @@ const schema = dsl({
 
 ### 完整对照表
 
-| joi | SchemaIO DSL | 说明 |
+| joi | SchemaI-DSL | 说明 |
 |-----|--------------|------|
 | `Joi.string()` | `'string'` | 字符串 |
 | `Joi.string().email()` | `'email'` | 邮箱 |
@@ -206,7 +206,7 @@ const schema = dsl({
 
 ### Q2: 为什么 `integer` 不是 `number().integer()`？
 
-A: SchemaIO 使用 JSON Schema 标准，`integer` 是独立类型。
+A: SchemaI-DSL 使用 JSON Schema 标准，`integer` 是独立类型。
 
 ### Q3: 不支持简写吗？