多语言配置指南

📚 多语言文档导航

根据你的需求选择合适的文档：

🚀 新手快速上手: i18n.md（当前文档）- 5分钟学会基础用法
📖 完整使用指南: i18n-user-guide.md - 详细的用户指南和最佳实践
🎯 添加新语言: add-custom-locale.md - 添加自定义语言包教程
🔄 动态切换语言: dynamic-locale.md - API开发中的动态语言切换
🌐 前端集成: frontend-i18n-guide.md - 前后端分离项目集成指南

📖 概述

schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错误消息的翻译。

Node.js 要求：>=18.0.0

目录加载（Node >=18）默认支持的语言文件格式：

.js（CommonJS 语言包）
.cjs
.json
.jsonc
.json5

推荐：如果你的应用是 type: module / ESM 项目，优先使用 .cjs、.json、.jsonc、.json5；.js 更适合 CommonJS 语言包文件。

v2 当前能力：

✅ 支持参数化语言切换（无需修改全局状态）
✅ 支持自定义错误消息（三种格式）
✅ TypeScript 类型定义完整
✅ 目录递归加载 .js/.cjs/.json/.jsonc/.json5

🚀 快速开始

方式1：验证时动态指定语言（推荐）⭐

import { s, validate } from 'schema-dsl/pure';

const schema = s({ 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：使用全局配置（向后兼容）

import { Locale } from 'schema-dsl/pure';

// 设置默认语言
Locale.setLocale('zh-CN');

// 后续验证会使用中文错误消息
const result = validate(schema, data);

📝 内置语言支持

schema-dsl 内置了以下语言包：

语言代码	语言名称	支持状态
`zh-CN`	简体中文	✅ 完整支持
`en-US`	英语（美国）	✅ 完整支持
`ja-JP`	日语	✅ 完整支持
`es-ES`	西班牙语	✅ 完整支持
`fr-FR`	法语	✅ 完整支持

🎯 高级用法

基础配置

import { s, validate } from 'schema-dsl/pure';
import path from 'path';
import zhCN from './i18n/dsl/zh-CN.cjs';
import enUS from './i18n/dsl/en-US.cjs';

// ✅ 方式 1: 从目录加载（推荐）
s.config({
  i18n: path.join(__dirname, 'i18n/dsl')  // Node >=18：支持 .js/.cjs/.json/.jsonc/.json5
});

// ✅ 方式 2: 直接传入对象
s.config({
  i18n: {
    'zh-CN': zhCN,
    'en-US': enUS
  }
});

目录加载为了兼容默认保留 .js / .cjs 支持。这些文件会被 Node 执行，因此只应来自可信 locale 目录；如果目录不可信，设置 codeLocaleFiles: 'deny'，仅加载 .json、.jsonc、.json5。

目录结构

project/
├── i18n/
│   └── dsl/              # schema-dsl 语言包目录
│       ├── zh-CN.cjs     # CommonJS / ESM 项目都稳定
│       ├── en-US.jsonc   # 带注释/末尾逗号
│       └── ja-JP.json5   # JSON5 风格（可选）

📝 语言包格式

完整示例 (`i18n/dsl/zh-CN.cjs`)

module.exports = {
  // ========== 字段标签 ==========
  'field.username': '用户名',
  'field.email': '邮箱地址',
  'field.password': '密码',
  'field.age': '年龄',
  
  // ========== 覆盖默认错误消息 ==========
  'required': '{{#label}}是必填项',
  'string.minLength': '{{#label}}长度不能少于{{#limit}}个字符',
  'string.maxLength': '{{#label}}长度不能超过{{#limit}}个字符',
  'string.enum': '{{#label}}必须是以下值之一: {{#valids}}',
  'number.base': '{{#label}}必须是数字类型',
  'number.min': '{{#label}}不能小于{{#limit}}',
  'number.max': '{{#label}}不能大于{{#limit}}',
  'boolean.base': '{{#label}}必须是布尔类型',
  'enum': '{{#label}}必须是以下值之一: {{#allowed}}',
  
  // ========== 自定义错误消息 ==========
  'custom.invalidEmail': '邮箱格式不正确，请重新输入',
  'custom.emailTaken': '该邮箱已被注册',
  'custom.passwordWeak': '密码强度不够'
};

🎯 使用方法

1. 字段标签翻译

const schema = s({
  username: s('string:3-32!').label('field.username'),
  email: s('email!').label('field.email')
});

const result = validate(schema, { username: 'ab' });
// 错误消息: "用户名长度不能少于3个字符"

2. 覆盖默认错误消息

// 语言包
module.exports = {
  'required': '{{#label}}必须填写'
};

// Schema
const schema = s({ username: 'string!' });

validate(schema, {});
// 错误消息: "username必须填写"

3. 自定义错误消息

const schema = s({
  status: s('active|inactive').messages({
    'enum': '状态必须是 active 或 inactive'
  })
});

4. 动态语言切换

s.config({
  i18n: {
    'zh-CN': { 'required': '{{#label}}是必填项' },
    'en-US': { 'required': '{{#label}} is required' }
  }
});

// 默认语言（en-US）
validate(schema, data);

// 切换到英文
validate(schema, data, { locale: 'en-US' });

📋 内置错误消息键

通用错误

错误键	说明	中文消息示例
`required`	必填字段缺失	{{#label}}是必填项
`enum`	枚举值不在范围	{{#label}}必须是以下值之一: {{#allowed}}
`pattern`	格式不正确	{{#label}}格式不正确

String 错误

错误键	说明
`string.minLength`	最小长度
`string.maxLength`	最大长度
`string.pattern`	正则不匹配
`string.enum`	字符串枚举

Number 错误

错误键	说明
`number.base`	类型不是数字
`number.min`	小于最小值
`number.max`	大于最大值
`number.integer`	不是整数

Boolean 错误

错误键	说明
`boolean.base`	类型不是布尔值

Array 错误

错误键	说明
`array.base`	类型不是数组
`array.min`	元素数量不足
`array.max`	元素数量过多
`array.unique`	包含重复元素

Format 错误

错误键	说明
`format.email`	邮箱格式错误
`format.url`	URL格式错误
`format.uuid`	UUID格式错误
`format.date`	日期格式错误
`format.binary`	Base64编码错误

Pattern 错误

错误键	说明
`pattern.phone`	手机号格式错误
`pattern.idCard`	身份证格式错误
`pattern.objectId`	ObjectId格式错误

完整列表请参考: src/locales/zh-CN.ts

🔧 高级用法

嵌套字段标签

// 语言包
module.exports = {
  'field.address.city': '城市',
  'field.address.street': '街道'
};

// Schema
const schema = s({
  address: {
    city: s('string!').label('field.address.city'),
    street: s('string!').label('field.address.street')
  }
});

错误消息优先级

字段级自定义消息 - .messages() 方法
Schema级标签 - .label() 方法
语言包自定义消息 - i18n 配置
默认错误消息 - 内置语言包

// 优先级示例
s.config({
  i18n: {
    'zh-CN': {
      'required': '全局必填消息'  // 优先级 3
    }
  }
});

const schema = s({
  username: s('string!')
    .label('用户名')                    // 优先级 2
    .messages({ 'required': '必须填' }) // 优先级 1（最高）
});

多语言最佳实践

1. 目录结构

project/
├── i18n/
│   └── dsl/
│       ├── zh-CN.cjs     # 中文
│       ├── en-US.cjs     # 英文
│       ├── ja-JP.cjs     # 日语
│       └── index.js      # 导出工具

2. 导出工具 (`i18n/dsl/index.js`)

import zhCN from './zh-CN.cjs';
import enUS from './en-US.cjs';
import jaJP from './ja-JP.cjs';

export default {
  'zh-CN': zhCN,
  'en-US': enUS,
  'ja-JP': jaJP
};

// 使用
import localeMessages from './i18n/dsl/index.js';

s.config({
  i18n: localeMessages
});

3. 消息复用

// i18n/dsl/common.cjs
module.exports = {
  required: '{{#label}}是必填项',
  minLength: '{{#label}}长度不能少于{{#limit}}个字符'
};

// i18n/dsl/zh-CN.cjs
import common from './common.cjs';

module.exports = {
  ...common,
  'field.username': '用户名',
  'field.email': '邮箱'
};

📊 完整示例

用户管理系统

import { s, validate } from 'schema-dsl/pure';
import path from 'path';

// 配置多语言
s.config({
  i18n: path.join(__dirname, 'i18n/dsl')
});

// 定义 Schema
const userSchema = s({
  username: s('string:3-32!').label('field.username'),
  email: s('email!').label('field.email'),
  password: s('string:8-32!').label('field.password'),
  age: s('number:18-120').label('field.age'),
  role: s('admin|user|guest!').label('field.role')
});

// 验证（中文）
let result = validate(userSchema, {
  username: 'ab',
  email: 'invalid',
  role: 'admin'
});

console.log(result.errors);
// [
//   { path: 'username', message: '用户名长度不能少于3个字符' },
//   { path: 'email', message: '邮箱地址必须是有效的邮箱地址' },
//   { path: 'password', message: '密码是必填项' }
// ]

// 验证（英文）
result = validate(userSchema, {
  username: 'ab'
}, { locale: 'en-US' });

console.log(result.errors[0].message);
// "username must be at least 3 characters"

🐛 常见问题

1. 语言包不生效？

先检查这些常见原因：

配置键应为 i18n，不是 locales。
目录路径应指向实际存放语言包文件的目录。
文件名应是 locale code，例如 zh-CN.cjs 或 zh-CN.jsonc。
.js 语言包应使用 CommonJS（module.exports）。ESM 项目优先使用 .cjs 或 .json*。

2. 错误消息仍然是英文？

原因: 当前请求没有显式传入 locale，或全局默认语言尚未切到你期望的语言

// 方法 1: 全局设置
import { Locale } from 'schema-dsl/pure';
Locale.setLocale('zh-CN');

// 方法 2: 验证时指定
validate(schema, data, { locale: 'zh-CN' });

3. 自定义消息不显示？

检查优先级:

.messages()s( > ).label() > 语言包 > 默认

// 错误：label 会被 messages 覆盖
s('string!')
  .label('用户名')
  .messages({ 'required': '必填' })  // 这个生效

📚 相关文档

对应示例文件

示例入口: i18n.ts
说明: 覆盖内置 locale 切换、字段级消息优先级，以及自定义 locale 的最小工作路径。

#多语言配置指南

#📚 多语言文档导航

#📖 概述

#🚀 快速开始

#方式1：验证时动态指定语言（推荐）⭐

#方式2：使用全局配置（向后兼容）

#📝 内置语言支持

#🎯 高级用法

#基础配置

#目录结构

#📝 语言包格式

#完整示例 (i18n/dsl/zh-CN.cjs)

#🎯 使用方法

#1. 字段标签翻译

#2. 覆盖默认错误消息

#3. 自定义错误消息

#4. 动态语言切换

#📋 内置错误消息键

#通用错误

#String 错误

#Number 错误

#Boolean 错误

#Array 错误

#Format 错误

#Pattern 错误

#🔧 高级用法

#嵌套字段标签

#错误消息优先级

#多语言最佳实践

#1. 目录结构

#2. 导出工具 (i18n/dsl/index.js)

#3. 消息复用

#📊 完整示例

#用户管理系统

#🐛 常见问题

#1. 语言包不生效？

#2. 错误消息仍然是英文？

#3. 自定义消息不显示？

#📚 相关文档

#对应示例文件