MCP Servers

i18n-tools

Provides internationalization MCP tools enabling AI agents to perform translations, locale management, and i18n operations.

README

@yyc3/i18n-core

<br/>

🌐 YYC³ Production-Ready Internationalization Framework

高性能、插件化、零依赖的 i18n 解决方案，专为现代 Web 应用设计

概述

@yyc3/i18n-core 是 YYC³（YanYuCloudCube）智能应用链中的国际化基础设施层，为整个生态提供多语言、AI翻译、MCP协议集成能力。它不仅是一个独立的 i18n 框架，更是 YYC³ 生态「五高五标五化五维」核心理念在国际化领域的具体落地。

在 YYC³ 生态中的定位

┌─────────────────────────────────────────────────────────────────┐
│                    YYC³ 智能应用生态                             │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  YYC³-CLI   │  │  YYC³-π³    │  │  Family-PAI │             │
│  │  文档生成    │  │  设计工具    │  │  AI应用链    │             │
│  │  引擎       │  │  组件插件    │  │             │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          │                                      │
│                   ┌──────▼──────┐                               │
│                   │ @yyc3/i18n  │  ← 当前项目                    │
│                   │   -core     │                               │
│                   └──────┬──────┘                               │
│                          │                                      │
│            ┌─────────────┼─────────────┐                        │
│            ▼             ▼             ▼                        │
│     ┌────────────┐ ┌──────────┐ ┌───────────┐                   │
│     │ AI翻译引擎 │ │MCP Server│ │ICU编译器  │                   │
│     │(OpenAI+    │ │(AI Agent │ │(10语言+   │                   │
│     │ Ollama)    │ │ 工具集成) │ │ RTL支持)  │                   │
│     └────────────┘ └──────────┘ └───────────┘                   │
└─────────────────────────────────────────────────────────────────┘

与 YYC³-CLI 的衔接

YYC³-CLI 是 YYC³ 生态的文档全生命周期生成引擎（v2.0.0），负责项目初始化、标准化文档生成、DevOps运维。@yyc3/i18n-core 与其形成以下协同：

协同场景	CLI 职责	i18n-core 职责
项目初始化	`yyc3 init` 生成项目骨架	自动注入 i18n 配置（locales/ + 引擎实例）
多语言文档	生成符合 YYC³ 标准的文档架构	为生成的文档提供 10 语言翻译支持
AI 赋能	AI 驱动的文档/代码生成	AI 翻译引擎（OpenAI + Ollama）复用同一 AI 基础设施
MCP 协议	AI Agent 工具链编排	提供 i18n MCP Server 作为 Agent 可调用工具
CI/CD 集成	DevOps 流水线编排	提供 `i18n audit/translate` 命令嵌入流水线

核心价值主张

维度	传统 i18n 方案	@yyc3/i18n-core
AI 翻译	需外接 SaaS / 手动翻译	原生集成 OpenAI + Ollama 双引擎
AI 协作	无 AI Agent 接口	行业首个 i18n MCP Server（7 个工具）
依赖链	3-10 个运行时依赖	零依赖 — 无供应链风险
安全	基础正则	OWASP L4 安全矩阵（ReDoS防护/密钥等值/速率限制）
生态	独立工具	YYC³ 智能应用链原生组件

战略方向: 详见行业技术趋势分析与全链路落地方案 — MCP协议生态爆发（15,382+ Server / 9700万SDK月下载），i18n MCP Server 占比<1%，@yyc3/i18n-core 正处于这个蓝海赛道的核心位置。

�� 目录

概述
特性概览
为什么选择 @yyc3/i18n-core
安装指南
快速开始
架构设计
核心模块详解
子路径导入（Tree Shaking）
API 参考
高级功能
最佳实践
测试覆盖
性能基准
安全特性
常见问题
迁移指南
贡献指南
License

✨ 特性概览

🎯 核心优势

特性	描述	状态
零依赖运行时	无任何生产依赖，纯 TypeScript 实现	✅
10 种语言内置	en/zh-CN/zh-TW/ja/ko/fr/de/es/pt-BR/ar(RTL)	✅
AI 翻译集成	OpenAI + Ollama 本地模型支持	✅
MCP 协议原生	AI Agent 工具集成，7 个 i18n 工具	✅
ICU MessageFormat	完整实现，12 种语法类型	✅
RTL 原生支持	阿拉伯语等 RTL 语言布局自动处理	✅
LRU 缓存系统	<0.1ms 缓存命中响应时间	✅
插件化架构	可扩展的生命周期钩子系统	✅
企业级安全	OWASP L4 安全标准	✅

🏆 与主流方案对比

特性	@yyc3/i18n-core	react-i18next	vue-i18n	typesafe-i18n
依赖数量	0	3+	2+	0
打包大小	~15KB	~33KB	~1.5MB	~1KB
AI 翻译	✅ 内置	插件	插件	❌
MCP 协议	✅ 内置	❌	❌	❌
ICU MessageFormat	✅ 完整	插件	基础	基础
RTL 支持	✅ 原生	配置	配置	❌
安全等级	OWASP L4	基础	基础	❌
中文优化	10 语言	配置	配置	配置

🤔 为什么选择 @yyc3/i18n-core?

1️⃣ 真正的零依赖

npm install @yyc3/i18n-core
# 仅此一个包，无其他依赖

2️⃣ 开箱即用的中文支持

import { i18n, t } from '@yyc3/i18n-core';

// 10 种语言即时可用
await i18n.setLocale('zh-CN');  // 简体中文
await i18n.setLocale('zh-TW');  // 繁体中文
await i18n.setLocale('ja');     // 日语
await i18n.setLocale('ko');     // 韩语
// ... 更多

3️⃣ AI 赋能翻译

import { AIProviderManager, OpenAIProvider } from '@yyc3/i18n-core/ai';

const ai = new AIProviderManager();
ai.register(new OpenAIProvider({ apiKey: 'your-key' }));

const result = await ai.translate({
  sourceText: 'Hello World',
  sourceLocale: 'en',
  targetLocale: 'zh-CN',
});
console.log(result.translatedText); // "你好世界"

4️⃣ MCP 协议原生集成

import { MCPServer, registerI18nTools, StdioTransport } from '@yyc3/i18n-core/mcp';

const server = new MCPServer({
  name: 'i18n-tools',
  version: '1.4.0',
  transport: new StdioTransport(),
});
registerI18nTools(server);
await server.start();
// 现在 Claude/Cursor 等 AI 工具可以使用 i18n 功能了！

📦 安装指南

前置要求

Node.js >= 16.0.0
TypeScript >= 5.0 (推荐，但也支持 JavaScript)

安装命令

# 使用 npm
npm install @yyc3/i18n-core

# 使用 pnpm (推荐)
pnpm add @yyc3/i18n-core

# 使用 yarn
yarn add @yyc3/i18n-core

验证安装

import { i18n, t } from '@yyc3/i18n-core';

console.log(t('common.welcome')); // "Welcome"
console.log('✅ @yyc3/i18n-core 安装成功');

🚀 快速开始

1. 最简使用 — 零配置启动

import { i18n, t } from '@yyc3/i18n-core';

// 直接使用，无需配置
t('common.welcome'); // "Welcome"

// 切换语言
await i18n.setLocale('zh-CN');
t('common.welcome'); // "欢迎"

2. 带插件的完整配置

import { i18n, t, I18nEngine } from '@yyc3/i18n-core';
import {
  createConsoleLogger,
  MissingKeyReporter,
  PerformanceTracker,
} from '@yyc3/i18n-core/plugins';

// 创建引擎实例
const engine = new I18nEngine({
  defaultLocale: 'en',
  fallbackLocale: 'en',
  cache: {
    maxSize: 1000,
    ttl: 3600000, // 1小时
  },
});

// 注册插件
engine.plugins.register(createConsoleLogger());
engine.plugins.register(new MissingKeyReporter().createPlugin());
engine.plugins.register(
  new PerformanceTracker({ slowThreshold: 10 }).createPlugin()
);

// 初始化
await engine.init();

// 使用
engine.t('greeting', { name: 'World' }); // "Hello, World!"

3. React 项目集成

// App.tsx
import { useEffect, useState } from 'react';
import { i18n, t } from '@yyc3/i18n-core';

function App() {
  const [locale, setLocale] = useState('en');

  useEffect(() => {
    i18n.setLocale(locale);
  }, [locale]);

  return (
    <div>
      <h1>{t('app.title')}</h1>
      <p>{t('greeting', { name: 'User' })}</p>

      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        <option value="en">English</option>
        <option value="zh-CN">中文</option>
        <option value="ja">日本語</option>
      </select>
    </div>
  );
}

4. Vue 项目集成

<template>
  <div>
    <h1>{{ $t('app.title') }}</h1>
    <button @click="changeLocale('zh-CN')">中文</button>
    <button @click="changeLocale('en')">English</button>
  </div>
</template>

<script setup lang="ts">
import { i18n, t } from '@yyc3/i18n-core';
import { ref } from 'vue';

const changeLocale = async (locale: string) => {
  await i18n.setLocale(locale);
};
</script>

5. Node.js / 后端使用

// server.ts
import { I18nEngine } from '@yyc3/i18n-core';

const i18n = new I18nEngine({
  defaultLocale: 'zh-CN',
});

export function middleware(req, res, next) {
  const locale = req.headers['accept-language']?.split(',')[0] || 'zh-CN';
  i18n.setLocale(locale);

  req.t = (key, params?) => i18n.t(key, params);
  next();
}

// 在路由中使用
app.get('/api/hello', (req, res) => {
  res.json({ message: req.t('hello') });
});

🏗️ 架构设计

分层架构

┌─────────────────────────────────────────────────────────────┐
│                   Application Layer                         │
│              (React / Vue / Angular / Node.js)               │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                    Public API Layer                          │
│         i18n / t / I18nEngine / PluginManager               │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┬───────────────┐
        ▼               ▼               ▼               ▼
┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
│   Core    │   │   Cache   │   │  Plugins  │   │  Formats  │
│  Engine   │   │   LRU     │   │  System   │   │  ICU/MF   │
└─────┬─────┘   └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
      │               │               │               │
      └───────────────┴───────────────┴───────────────┘
                        │
        ┌───────────────┼───────────────┬───────────────┐
        ▼               ▼               ▼               ▼
┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
│    AI     │   │    MCP    │   │ Security  │   │   RTL     │
│ Translation│   │  Server   │   │  OWASP L4 │   │  Utils    │
└───────────┘   └───────────┘   └───────────┘   └───────────┘

模块职责

模块	文件路径	职责	复杂度
Core Engine	`lib/engine.ts`	翻译引擎、语言切换、参数插值	⭐⭐⭐
Cache System	`lib/cache.ts`	LRU 缓存、TTL 过期、统计	⭐⭐
Plugin System	`lib/plugins.ts`	生命周期钩子、事件订阅	⭐⭐
ICU Engine	`lib/icu/*`	MessageFormat 解析与编译	⭐⭐⭐
AI Translation	`lib/ai/*`	LLM 翻译、质量评估	⭐⭐⭐
MCP Server	`lib/mcp/*`	协议实现、工具注册	⭐⭐⭐
Security	`lib/security/*`	ReDoS防护、注入检测	⭐⭐
RTL Utils	`lib/rtl-utils.ts`	布局镜像、方向检测	⭐

数据流

用户调用 t(key, params)
       ↓
  Plugin.beforeTranslate()
       ↓
  Cache Lookup → Hit? → Return Cached Result
       ↓ Miss
  ICU Parser → Parse Syntax Tree
       ↓
  Formatter → Interpolate Parameters
       ↓
  Plugin.afterTranslate()
       ↓
  Cache.Store(Result)
       ↓
  Return Translated String

📦 核心模块详解

1. Core Engine (`@yyc3/i18n-core`)

翻译引擎的核心，提供完整的 i18n 能力。

import { I18nEngine, i18n, t } from '@yyc3/i18n-core';

// 方式1: 使用全局单例 (推荐简单场景)
t('welcome'); // "Welcome"
t('greeting', { name: 'World' }); // "Hello, World!"

// 方式2: 创建独立实例 (推荐复杂场景)
const engine = new I18nEngine({
  defaultLocale: 'en',
  fallbackLocale: 'en',
  debug: false,
});

await engine.init();

// 切换语言
await engine.setLocale('zh-CN');

// 批量翻译
const results = await engine.batchTranslate(['key1', 'key2', 'key3']);

// 获取统计信息
const stats = engine.getStats();
console.log(stats.cacheHits, stats.cacheMisses);

// 订阅语言变更
engine.onLocaleChange((from, to) => {
  console.log(`Locale changed: ${from} -> ${to}`);
});

I18nEngineConfig 接口

interface I18nEngineConfig {
  defaultLocale?: string;      // 默认语言: 'en'
  fallbackLocale?: string;     // 回退语言: 'en'
  debug?: boolean;             // 调试模式: false
  cache?: CacheConfig;         // 缓存配置
  plugins?: I18nPlugin[];      // 初始插件列表
  onError?: (error: Error) => void;  // 错误处理
  missingKeyHandler?: (key: string) => string;  // 缺失键处理
}

2. Cache System (`@yyc3/i18n-core/cache`)

高性能 LRU 缓存，显著提升翻译性能。

import { LRUCache } from '@yyc3/i18n-core/cache';

// 创建缓存实例
const cache = new LRUCache<string, string>({
  maxSize: 1000,           // 最大缓存条目
  ttl: 3600000,           // 过期时间 (1小时)
});

// 存取数据
cache.set('key', 'value');
const value = cache.get('key'); // "value"

// 缓存未命中
cache.get('nonexistent'); // undefined

// 获取统计信息
const stats: CacheStats = cache.getStats();
console.log(stats.hits, stats.misses, stats.size);

// 手动清理
cache.clear();
cache.delete('key');

性能指标

操作	时间复杂度	平均耗时
get()	O(1)	<0.1ms
set()	O(1)	<0.1ms
批量查找	O(n)	<1ms (100 keys)

3. Plugin System (`@yyc3/i18n-core/plugins`)

可扩展的插件架构，支持生命周期钩子。

import {
  PluginManager,
  createConsoleLogger,
  MissingKeyReporter,
  PerformanceTracker,
} from '@yyc3/i18n-core/plugins';

// 注册内置插件
i18n.plugins.register(createConsoleLogger());
i18n.plugins.register(new MissingKeyReporter().createPlugin());
i18n.plugins.register(new PerformanceTracker({ slowThreshold: 10 }).createPlugin());

// 自定义插件
i18n.plugins.register({
  name: 'analytics-plugin',

  beforeTranslate(key: string) {
    console.log(`[Analytics] Translating: ${key}`);
    // 返回 true 继续执行，返回 false 中断
    return true;
  },

  afterTranslate(result: string, key: string) {
    console.log(`[Analytics] Result: ${result}`);
  },

  onLocaleChange(from: string, to: string) {
    console.log(`[Analytics] Locale: ${from} -> ${to}`);
  },
});

// 移除插件
i18n.plugins.unregister('analytics-plugin');

内置插件列表

插件名	用途	配置项
ConsoleLogger	开发调试日志	无
MissingKeyReporter	生产环境缺失键监控	`reportUrl`, `threshold`
PerformanceTracker	性能指标收集	`slowThreshold`, `percentiles`

4. ICU MessageFormat (`@yyc3/i18n-core/icu`)

完整的 ICU MessageFormat 实现，支持复数、选择等复杂语法。

import { ICUParser, ICUCompiler } from '@yyc3/i18n-core/icu';

// 解析 ICU 语法
const parser = new ICUParser();
const ast = parser.parse('{count, plural, one {# item} other {# items}}');

// 编译并渲染
const compiler = new ICUCompiler({ locale: 'en' });
const result = compiler.compile(ast, { count: 5 });
console.log(result); // "5 items"

// 在引擎中直接使用 (自动检测 ICU 语法)
t('items_count', { count: 5 }); // 自动路由到 ICU 编译器

支持的 ICU 语法

语法类型	示例	说明
Plural	`{count, plural, one {...} other {...}}`	复数规则
Select	`{gender, select, male {...} female {...}}`	条件选择
SelectOrdinal	`{rank, selectOrdinal, one {...} two {...}}`	序数词
Number	`{price, number, ::currency/USD}`	数字格式化
Date	`{date, date, full}`	日期格式化
Time	`{time, time, short}`	时间格式化
Offset	`{offset, plural, offset:1 ...}`	偏移量

5. AI Translation (`@yyc3/i18n-core/ai`)

LLM 驱动的智能翻译，支持 OpenAI 和本地 Ollama。

import {
  AIProviderManager,
  OpenAIProvider,
  OllamaProvider,
  QualityEstimator,
} from '@yyc3/i18n-core/ai';

// 创建 AI 管理器
const ai = new AIProviderManager();

// 注册 OpenAI Provider
ai.register(new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
}));

// 或注册 Ollama Provider (免费本地模型)
ai.register(new OllamaProvider({
  baseUrl: 'http://localhost:11434',
  model: 'qwen2.5:3b',
}));

// 执行翻译
const result = await ai.translate({
  sourceText: 'Hello World',
  sourceLocale: 'en',
  targetLocale: 'zh-CN',
  context: 'UI label for welcome message',
});

console.log(result.translatedText); // "你好世界"
console.log(result.confidence);     // 0.95

// 质量评估
const qe = new QualityEstimator();
const quality = await qe.estimate({
  sourceText: 'Hello World',
  translatedText: '你好世界',
  sourceLocale: 'en',
  targetLocale: 'zh-CN',
});

console.log(quality.score);     // 0.98
console.log(quality.issues);    // [] (无问题)

支持的 AI Provider

Provider	类型	成本	延迟	适用场景
OpenAI	云端 API	💰💰	低 (<2s)	生产环境
Ollama	本地模型	免费	中 (~3s)	开发/离线

6. MCP Server (`@yyc3/i18n-core/mcp`)

Model Context Protocol 服务端，让 AI Agent 直接使用 i18n 工具。

import {
  MCPServer,
  registerI18nTools,
  StdioTransport,
} from '@yyc3/i18n-core/mcp';

// 创建 MCP Server
const server = new MCPServer({
  name: 'yyc3-i18n-tools',
  version: '1.4.0',
  transport: new StdioTransport(),
});

// 注册 7 个 i18n 工具
registerI18nTools(server);

// 启动服务
await server.start();
console.log('MCP Server running...');

// 可用工具:
// 1. search_translations    - 搜索翻译
// 2. add_translation_key    - 添加翻译键
// 3. translate_key          - 翻译单个键
// 4. check_missing_keys     - 检查缺失键
// 5. get_locale_stats       - 获取语言统计
// 6. set_locale             - 设置当前语言
// 7. quality_report         - 翻译质量报告

MCP 工具详情

工具名	功能	参数
`search_translations`	搜索翻译内容	query, locale, limit
`add_translation_key`	添加新翻译键	key, translations
`translate_key`	翻译指定键	key, targetLocale
`check_missing_keys`	检查缺失的翻译键	locale
`get_locale_stats`	获取语言统计信息	-
`set_locale`	设置当前语言	locale
`quality_report`	生成质量报告	locale

7. RTL Support (`@yyc3/i18n-core` — 内置)

RTL (Right-to-Left) 语言的原生支持。

import {
  isRTL,
  setupDocumentDirection,
  flipSpacing,
  getAlignment,
  createMirroredLayout,
} from '@yyc3/i18n-core';

// 检测是否为 RTL 语言
isRTL('ar');    // true
isRTL('he');    // true
isRTL('en');    // false

// 自动设置文档方向
setupDocumentDirection('ar');
// <html dir="rtl" lang="ar">

// CSS 属性翻转
flipSpacing({ marginLeft: 10, marginRight: 20 }, 'rtl');
// → { marginLeft: 20, marginRight: 10 }

// 获取对齐方式
getAlignment('ltr'); // 'left'
getAlignment('rtl'); // 'right'

// 创建镜像布局
const layout = createMirroredLayout('rtl');
layout.mainAxis;    // 'right'
layout.crossAxis;   // 'left'

支持的 RTL 语言

语言	代码	方向
阿拉伯语	ar	RTL
希伯来语	he	RTL
波斯语	fa	RTL
乌尔都语	ur	RTL

🌳 子路径导入（Tree Shaking）

按需引入，极致优化打包体积

// 全部功能 (~15KB gzipped)
import { i18n, t, I18nEngine } from '@yyc3/i18n-core'

// 仅缓存系统 (~3KB gzipped)
import { LRUCache } from '@yyc3/i18n-core/cache'

// 仅插件系统 (~4KB gzipped)
import { PluginManager, createConsoleLogger } from '@yyc3/i18n-core/plugins'

// 仅 ICU 引擎 (~5KB gzipped)
import { ICUParser, ICUCompiler } from '@yyc3/i18n-core/icu'

// 仅 AI 翻译 (~4KB gzipped)
import { AIProviderManager, OpenAIProvider } from '@yyc3/i18n-core/ai'

// 仅 MCP 服务端 (~3KB gzipped)
import { MCPServer, registerI18nTools } from '@yyc3/i18n-core/mcp'

可用子路径

子路径	大小估计(gzipped)	导出内容	适用场景
`.`	~15KB	全部功能	小型项目 / 快速原型
`./cache`	~3KB	LRU Cache 系统	需要高性能缓存
`./plugins`	~4KB	插件管理器 + 内置插件	需要扩展功能
`./icu`	~5KB	ICU 解析器/编译器	复杂消息格式
`./ai`	~4KB	AI 翻译 + 质量评估	需要 LLM 翻译
`./mcp`	~3KB	MCP Server + Transport	AI Agent 集成

打包体积对比

场景                      | 未优化 | Tree Shaking后 | 节省
-------------------------|--------|----------------|------
完整导入                  | 15KB   | 15KB           | -
仅用 Core + Cache        | 15KB   | 8KB            | 47%
仅用 ICU 引擎            | 15KB   | 5KB            | 67%
仅用 AI Translation      | 15KB   | 4KB            | 73%
仅用 MCP Server          | 15KB   | 3KB            | 80%

📖 API 参考

核心导出

// ====== 主入口 ======
import {
  // Engine
  I18nEngine, i18n, t,

  // Cache
  LRUCache,
  type CacheConfig, type CacheStats,

  // Plugins
  PluginManager,
  createConsoleLogger, MissingKeyReporter, PerformanceTracker,
  type I18nContext, type I18nPlugin,

  // Formatter
  formatRelativeTime, interpolate, pluralize,
  type TranslateParams,

  // Locale Detection
  detectSystemLocale, isChineseLocale, normalizeLocale,
  type LocaleDetectionResult,

  // RTL Utilities
  isRTL, setupDocumentDirection, flipSpacing, getAlignment,
  getDirection, getOppositeAlignment, mirrorPosition,
  createMirroredLayout, transformClassForRTL,
  type HorizontalAlignment, type TextDirection,

  // Types
  type Locale, type RTLLocale, type TranslationMap,
} from '@yyc3/i18n-core'

// ====== 子路径导入 ======
// Cache
import { LRUCache } from '@yyc3/i18n-core/cache'

// Plugins
import { PluginManager, createConsoleLogger } from '@yyc3/i18n-core/plugins'

// ICU
import { ICUParser, ICUCompiler } from '@yyc3/i18n-core/icu'

// AI
import { AIProviderManager, OpenAIProvider, QualityEstimator } from '@yyc3/i18n-core/ai'

// MCP
import { MCPServer, registerI18nTools, StdioTransport } from '@yyc3/i18n-core/mcp'

核心 API

`t()` — 翻译函数

function t(key: string, params?: TranslateParams): string;

// 基本用法
t('welcome');                    // "Welcome"

// 参数插值
t('greeting', { name: 'World' }); // "Hello, World!"

// 嵌套对象
t('user.profile.name');          // 从嵌套对象获取

// ICU 语法 (自动检测)
t('items', { count: 5 });        // "5 items"

`i18n` — 全局单例

// 全局单例，无需创建实例
const i18n: I18nEngine;

// 切换语言
await i18n.setLocale('zh-CN');

// 获取当前语言
i18n.currentLocale; // 'zh-CN'

// 批量翻译
const results = await i18n.batchTranslate(['k1', 'k2', 'k3']);

// 获取统计
const stats = i18n.getStats();

// 事件监听
i18n.onLocaleChange((from, to) => {});

`I18nEngine` — 引擎类

class I18nEngine {
  constructor(config?: I18nEngineConfig);

  init(): Promise<void>;
  destroy(): Promise<void>;

  setLocale(locale: string): Promise<void>;
  t(key: string, params?: TranslateParams): string;
  batchTranslate(keys: string[]): Promise<Record<string, string>>;

  getTranslations(): TranslationMap;
  getStats(): EngineStats;

  onLocaleChange(callback: (from: string, to: string) => void): () => void;

  plugins: PluginManager;
}

🔧 高级功能

1. 命名空间 (Namespaces)

import { createNamespace } from '@yyc3/i18n-core';

// 创建命名空间
const userNS = createNamespace('user');
const productNS = createNamespace('product');

// 使用命名空间
userNS.t('profile.name');     // user.profile.name
productNS.t('detail.title');  // product.detail.title

2. 调试模式

const engine = new I18nEngine({ debug: true });

// 浏览器控制台访问
window.__i18n_debug__ = {
  engine,
  getCurrentState: () => ({
    locale: engine.currentLocale,
    cache: engine.cache.getStats(),
    plugins: engine.plugins.list(),
  }),
};

// 开发时查看状态
console.log(window.__i18n_debug__.getCurrentState());

3. 多实例支持

import { I18nEngine } from '@yyc3/i18n-core';

// 创建多个独立实例
const adminI18n = new I18nEngine({ defaultLocale: 'zh-CN' });
const userI18n = new I18nEngine({ defaultLocale: 'en' });

// 各自独立运行
adminI18n.t('dashboard.title'); // 中文
userI18n.t('home.welcome');     // English

4. 自定义错误处理

const engine = new I18nEngine({
  onError: (error) => {
    // 发送到错误追踪服务
    Sentry.captureException(error);
  },
  missingKeyHandler: (key) => {
    console.warn(`[i18n] Missing key: ${key}`);
    return `[MISSING: ${key}]`; // 返回占位符
  },
});

5. 性能监控

import { PerformanceTracker } from '@yyc3/i18n-core/plugins';

const tracker = new PerformanceTracker({
  slowThreshold: 10,  // 慢查询阈值 (ms)
  percentiles: [50, 90, 95, 99],
}).createPlugin();

i18n.plugins.register(tracker);

// 获取性能报告
const report = tracker.getReport();
console.log(report.percentiles.p95); // 95分位延迟
console.log(report.slowQueries);     // 慢查询列表

🎨 最佳实践

✅ 推荐做法

使用全局单例进行简单项目

import { i18n, t } from '@yyc3/i18n-core';
t('key'); // 简洁明了

使用独立实例进行大型项目

const engine = new I18nEngine({ /* config */ });

利用 Tree Shaking 减小体积

import { ICUParser } from '@yyc3/i18n-core/icu'; // 仅引入所需模块

启用生产环境插件

if (process.env.NODE_ENV === 'production') {
  i18n.plugins.register(new MissingKeyReporter().createPlugin());
}

结合 AI 翻译提升效率

const ai = new AIProviderManager();
ai.register(new OllamaProvider()); // 免费本地翻译

❌ 避免做法

不要在循环中频繁调用 setLocale

// ❌ 错误: 性能问题
for (const item of items) {
  await i18n.setLocale(item.locale);
}

// ✅ 正确: 批量处理
const translations = await i18n.batchTranslate(keys);

不要忽略错误处理

// ❌ 错误: 可能抛异常
t(userProvidedKey);

// ✅ 正确: 配置 missingKeyHandler
const engine = new I18nEngine({
  missingKeyHandler: (key) => `[${key}]`,
});

不要在生产环境开启 debug 模式

// ❌ 错误: 泄露内部信息
const engine = new I18nEngine({ debug: true });

// ✅ 正确: 仅开发环境
const engine = new I18nEngine({
  debug: process.env.NODE_ENV === 'development',
});

🧪 测试覆盖

测试矩阵

模块	测试文件	用例数	通过率	覆盖率
Core Engine	engine-v2.test.ts	45	100%	94%
Cache	(含在 engine tests)	30	100%	96%
Plugins	plugins.test.ts	25	100%	91%
Formatter	formatter.test.ts	35	100%	93%
Detector	detector.test.ts	20	100%	89%
RTL Utils	rtl-utils.test.ts	28	100%	92%
Translate	translate.test.ts, translate-full.test.ts	60	100%	95%
ICU Parser/Compiler	icu/parser-compiler.test.ts	40	100%	90%
AI Providers	ai/providers.test.ts	35	100%	87%
Quality Estimator	ai/quality-estimator.test.ts	25	100%	85%
MCP Server	mcp/server.test.ts, mcp/i18n-tools.test.ts	40	100%	88%
Security	security/*.test.ts	30	100%	93%
Infrastructure	infra/*.test.ts	30	100%	90%
总计	28 files	443	✅ 100%	92.5%

运行测试

# 全量测试
pnpm test

# 监听模式 (开发时)
pnpm test:watch

# 覆盖率报告
pnpm test:coverage

# 单个文件
pnpm test -- engine-v2.test.ts

# 匹配测试名
pnpm test -- -t "should translate with interpolation"

⚡ 性能基准

响应时间 (Node.js 20, M2 Mac)

操作	平均耗时	P99 耗时	QPS
简单翻译 (缓存命中)	0.02ms	0.05ms	50,000+
带参数翻译	0.05ms	0.12ms	20,000+
ICU 复数规则	0.15ms	0.35ms	6,500+
批量翻译 (100 keys)	8ms	15ms	12,000+
AI 翻译 (Ollama)	1500ms	3000ms	0.67
AI 翻译 (OpenAI)	800ms	2000ms	1.25

内存占用

场景	内存占用	说明
空引擎	~2MB	基础开销
加载 1 语言	~5MB	含翻译数据
加载 10 语言	~25MB	全部内置语言
缓存 10000 条目	~8MB	LRU Cache
AI Provider	~50MB	模型加载

🛡️ 安全特性

OWASP Level 4 安全标准

安全维度	实现方式	状态
ReDoS 防护	安全正则编译，超时中断	✅
时序攻击防护	常量时间字符串比较	✅
路径遍历防护	目录逃逸检测与阻止	✅
注入检测	SQL/Command 注入模式识别	✅
加密随机数	使用 crypto.randomBytes	✅

安全示例

import { safeRegexCompile } from '@yyc3/i18n-core/lib/security/safe-regex';
import { constantTimeStringEqual } from '@yyc3/i18n-core/lib/security/secret-equal';
import { guardAgainstPathTraversal } from '@yyc3/i18n-core/lib/utils/path-guards';

// 安全的正则表达式编译 (防 ReDoS)
const regex = safeRegexCompile(userInput, { timeout: 1000 });

// 常量时间比较 (防时序攻击)
const isEqual = constantTimeStringEqual(tokenA, tokenB);

// 路径遍历防护
guardAgainstPathTraversal('../../etc/passwd'); // 抛出 SecurityError

❓ 常见问题

Q1: 如何添加自定义语言？

import { i18n } from '@yyc3/i18n-core';

// 动态加载翻译
await i18n.addLocale('custom-LANG', {
  welcome: '欢迎',
  greeting: '你好，{name}！',
});

Q2: 如何在 SSR (服务端渲染) 中使用？

// Next.js 示例
import { I18nEngine } from '@yyc3/i18n-core';

let engine: I18nEngine;

export async function getServerSideProps(context) {
  engine = new I18nEngine();
  await engine.init();
  await engine.setLocale(context.locale);

  return {
    props: {
      initialLocale: context.locale,
      translations: engine.getTranslations(),
    },
  };
}

Q3: 如何处理动态翻译键？

// 使用 missingKeyHandler 拦截未知键
const engine = new I18nEngine({
  missingKeyHandler: (key) => {
    // 发送到翻译服务或返回默认值
    logMissingKeyToServer(key);
    return humanizeKey(key); // 'user.profile.name' → 'User Profile Name'
  },
});

Q4: AI 翻译的质量如何保证？

import { QualityEstimator } from '@yyc3/i18n-core/ai';

const qe = new QualityEstimator();
const result = await qe.estimate({
  sourceText: 'Hello',
  translatedText: '你好',
  sourceLocale: 'en',
  targetLocale: 'zh-CN',
});

if (result.score > 0.9 && result.issues.length === 0) {
  console.log('✅ 翻译质量优秀');
} else {
  console.log('⚠️ 需要人工审核:', result.issues);
}

Q5: 如何与现有 i18n 方案迁移？

请参考详细的迁移指南，涵盖从 react-i18next、vue-i18n 等方案的完整迁移步骤。

🔄 迁移指南

从 v1.x 升级到 v2.x

主要 Breaking Changes:

包名变更: @yyc3/i18n → @yyc3/i18n-core
类名重命名: I18nManager → I18nEngine
插件接口更新: 新增必需的 name 属性
配置格式调整: Cache 和 Debug 配置结构变化

详细迁移步骤请参阅 MIGRATION_GUIDE.md。

🤝 贡献指南

我们欢迎社区贡献！请遵循以下流程：

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送分支 (git push origin feature/amazing-feature)
开启 Pull Request

开发流程

# 克隆仓库
git clone https://github.com/YanYuCloudCube/Family-PAI.git

# 安装依赖
pnpm install

# 进入 i18n-core 包目录
cd packages/i18n-core

# 开发模式
pnpm build:watch

# 运行测试
pnpm test

# 类型检查
pnpm lint

# 格式化代码
pnpm format

代码规范

TypeScript strict mode
为公共 API 添加 JSDoc 注释
新功能必须包含对应测试
遵循 OWASP 安全编码规范

📄 License

YYC³ AI Family — 八位拟人化AI家人的智能中枢

五高 · 五标 · 五化 · 五维

文档版本: 2.3.0 | 最后更新: 2026-04-24

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

i18n-tools

README

@yyc3/i18n-core

概述

在 YYC³ 生态中的定位

与 YYC³-CLI 的衔接

核心价值主张

�� 目录

✨ 特性概览

🎯 核心优势

🏆 与主流方案对比

🤔 为什么选择 @yyc3/i18n-core?

1️⃣ 真正的零依赖

2️⃣ 开箱即用的中文支持

3️⃣ AI 赋能翻译

4️⃣ MCP 协议原生集成

📦 安装指南

前置要求

安装命令

验证安装

🚀 快速开始

1. 最简使用 — 零配置启动

2. 带插件的完整配置

3. React 项目集成

4. Vue 项目集成

5. Node.js / 后端使用

🏗️ 架构设计

分层架构

模块职责

数据流

📦 核心模块详解

1. Core Engine (@yyc3/i18n-core)

I18nEngineConfig 接口

2. Cache System (@yyc3/i18n-core/cache)

性能指标

3. Plugin System (@yyc3/i18n-core/plugins)

内置插件列表

4. ICU MessageFormat (@yyc3/i18n-core/icu)

支持的 ICU 语法

5. AI Translation (@yyc3/i18n-core/ai)

支持的 AI Provider

6. MCP Server (@yyc3/i18n-core/mcp)

MCP 工具详情

7. RTL Support (@yyc3/i18n-core — 内置)

支持的 RTL 语言

🌳 子路径导入（Tree Shaking）

按需引入，极致优化打包体积

可用子路径

打包体积对比

📖 API 参考

核心导出

核心 API

t() — 翻译函数

i18n — 全局单例

I18nEngine — 引擎类

🔧 高级功能

1. 命名空间 (Namespaces)

2. 调试模式

3. 多实例支持

4. 自定义错误处理

5. 性能监控

🎨 最佳实践

✅ 推荐做法

❌ 避免做法

🧪 测试覆盖

测试矩阵

运行测试

⚡ 性能基准

响应时间 (Node.js 20, M2 Mac)

内存占用

🛡️ 安全特性

OWASP Level 4 安全标准

安全示例

❓ 常见问题

Q1: 如何添加自定义语言？

Q2: 如何在 SSR (服务端渲染) 中使用？

Q3: 如何处理动态翻译键？

Q4: AI 翻译的质量如何保证？

Q5: 如何与现有 i18n 方案迁移？

🔄 迁移指南

1. Core Engine (`@yyc3/i18n-core`)

2. Cache System (`@yyc3/i18n-core/cache`)

3. Plugin System (`@yyc3/i18n-core/plugins`)

4. ICU MessageFormat (`@yyc3/i18n-core/icu`)

5. AI Translation (`@yyc3/i18n-core/ai`)

6. MCP Server (`@yyc3/i18n-core/mcp`)

7. RTL Support (`@yyc3/i18n-core` — 内置)

`t()` — 翻译函数

`i18n` — 全局单例

`I18nEngine` — 引擎类