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

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

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');     // 韩语
// ... 更多

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); // "你好世界"

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 功能了！

# 使用 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 安装成功');

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

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

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

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

// 创建引擎实例（构造即可用，无 init 步骤）
const engine = new I18nEngine({
  locale: '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()
);

// 注册语言资源并激活
engine.registerTranslation('en', enBundle);
await engine.setLocale('en');

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

// 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>
  );
}

<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>

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

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

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

  req.t = (key: string, params?: Record<string, string>) => 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    │
└───────────┘   └───────────┘   └───────────┘   └───────────┘

用户调用 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

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

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

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

// 注册语言资源（同步）
engine.registerTranslation('zh-CN', zhCNBundle);

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

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

// 获取统计信息
const stats = engine.getStats();

// 订阅语言变更
const unsubscribe = engine.subscribe((locale) => {
  console.log(`Locale changed to: ${locale}`);
});

interface I18nEngineConfig {
  locale?: Locale;             // 初始语言
  fallbackLocale?: Locale;     // 回退语言
  debug?: boolean;             // 调试模式: false
  cache?: {
    maxSize?: number;          // 最大缓存条目(默认 1000)
    ttl?: number;              // 过期时间毫秒(默认 5 分钟)
  };
  onError?: (error: Error, context: { key: string; locale: Locale }) => void;
  missingKeyHandler?: (key: string, locale: Locale) => string;
}

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');

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');

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

// 解析 ICU 语法（parse 为实例方法，返回 { ast, errors }）
const parsed = new ICUParser().parse('{count, plural, one {# item} other {# items}}');

// 编译并渲染（locale 与参数在 compile 上下文中传入）
const result = new ICUCompiler().compile(parsed.ast, {
  locale: 'en',
  params: { count: '5' },
});
console.log(result); // "5 items"

// 在引擎中直接使用（自动检测 ICU 语法，参数值为字符串）
t('items_count', { count: '5' }); // 自动路由到 ICU 编译器

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);    // [] (无问题)

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         - 翻译质量报告

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'

// 全部功能 (~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/browser'

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

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

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

// ====== 主入口 ======
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/browser'

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

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

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"

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

// 注册语言资源并切换语言
i18n.registerTranslation('zh-CN', zhCN);
await i18n.setLocale('zh-CN');

// 获取当前语言
i18n.getLocale(); // 'zh-CN'

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

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

// 事件监听（返回退订函数）
const unsubscribe = i18n.subscribe((locale) => {});

class I18nEngine {
  constructor(config?: I18nEngineConfig);

  // 语言管理
  getLocale(): Locale;
  setLocale(locale: string): Promise<void>;
  registerTranslation(locale: Locale, map: TranslationMap): void;
  getTranslations(locale: Locale): TranslationMap | undefined;

  // 翻译
  t(key: string, params?: TranslateParams): string;
  batchTranslate(keys: string[]): Record<string, string>;
  createNamespace(prefix: string): {
    t(key: string, params?: Record<string, string>): string;
    batchTranslate(keys: string[]): Record<string, string>;
    getLocale(): Locale;
  };

  // 事件与运维
  subscribe(callback: (locale: Locale) => void): () => void;
  setDebug(enabled: boolean): void;
  getStats(): EngineStats;
  destroy(): Promise<void>;

  // 子系统（只读）
  readonly cache: LRUCache<string>;
  readonly plugins: PluginManager;
}

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

// createNamespace 是引擎实例方法（非独立导出）
const userNS = i18n.createNamespace('user');
const productNS = i18n.createNamespace('product');

// 使用命名空间（自动拼接前缀）
userNS.t('profile.name');     // → i18n.t('user.profile.name')
productNS.t('detail.title');  // → i18n.t('product.detail.title')

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

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

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

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

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

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

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

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

const tracker = new PerformanceTracker({
  slowThreshold: 10,  // 慢查询阈值 (ms)
  maxSlowEntries: 50,
  samplingRate: 1,    // 生产建议 0.1
});

i18n.plugins.register(tracker.createPlugin());

// 获取性能指标
tracker.getCacheHitRate();   // 缓存命中率 (0-100)
tracker.getPercentile(95);   // 95分位延迟 (ms)
tracker.generateReport();    // 完整性能报告

# 全量测试
pnpm test

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

# 覆盖率报告
pnpm test:coverage

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

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

// 均从根入口导出（Node.js 环境）
import {
  compileSafeRegex,
  safeEqualSecret,
  isPathInside,
} from '@yyc3/i18n-core';

// 安全的正则表达式编译 (防 ReDoS)
const result = compileSafeRegex(/^[a-z]+$/);
if (!result.safe) throw new Error(result.reason);

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

// 路径遍历防护
isPathInside(userPath, baseDir); // 越界返回 false

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

// 注册自定义语言资源
i18n.registerTranslation('custom-LANG', {
  welcome: '欢迎',
  greeting: '你好，{name}！',
});
await i18n.setLocale('custom-LANG');

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

export async function getServerSideProps(context) {
  const engine = new I18nEngine({ locale: context.locale });
  engine.registerTranslation(context.locale, localeBundle);
  await engine.setLocale(context.locale);

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

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

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);
}

# 克隆仓库
git clone git@github.com:YYC-Cube/YYC3-i18n-Core.git
cd YYC3-i18n-Core

# 安装依赖（pnpm 11，根工作区含 packages/i18n-react）
pnpm install

# 开发模式(核心包构建监听)
pnpm build:watch

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

# 格式化代码
pnpm format