@ui18n/cli/README.md

🌍 UI18n CLI工具 - 强大的国际化命令行工具

# @ui18n/cli

🛠️ **UI18n命令行工具** - 高效的国际化项目管理工具

[![npm version](https://badge.fury.io/js/%40ui18n%2Fcli.svg)](https://badge.fury.io/js/%40ui18n%2Fcli)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)

## ✨ 特性

- 🚀 **项目初始化**：快速创建国际化项目结构
- 📝 **文本提取**：自动扫描代码，提取需要翻译的文本
- 🌍 **批量翻译**：高效的批量翻译处理
- 📊 **统计分析**：详细的翻译进度和成本分析
- 🔧 **配置管理**：灵活的项目配置管理
- 🎯 **多框架支持**：支持React、Vue、Angular等主流框架
- 💰 **成本优化**：智能缓存，最小化AI API调用

## 🚀 安装

```bash
# 全局安装
npm install -g @ui18n/cli

# 或项目内安装
npm install --save-dev @ui18n/cli
```

## 📋 命令概览

```bash
ui18n --help

Commands:
  ui18n init [name]           初始化新的国际化项目
  ui18n extract               提取需要翻译的文本
  ui18n translate             批量翻译文本
  ui18n stats                 查看翻译统计信息
  ui18n config                管理项目配置

Options:
  --version                   显示版本号
  --help                      显示帮助信息
```

## 🎯 快速开始

### 1. 初始化项目

```bash
# 在当前目录初始化
ui18n init

# 创建新项目
ui18n init my-i18n-project

# 指定框架
ui18n init --framework react
ui18n init --framework vue
```

初始化后会创建以下结构：
```
my-project/
├── ui18n.config.js         # 配置文件
├── i18n/
│   ├── texts.json          # 提取的文本
│   ├── translations/       # 翻译结果
│   └── cache/              # 翻译缓存
└── src/                    # 你的源代码
```

### 2. 配置项目

编辑 `ui18n.config.js`：

```javascript
module.exports = {
  // 基础配置
  defaultLanguage: 'zh-CN',
  targetLanguages: ['en', 'ja', 'ko'],
  
  // 自托管模式（推荐）
  aiProvider: {
    type: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-3.5-turbo'
  },
  
  // 或使用云端服务（可选）
  // serviceMode: 'cloud',
  // userKey: 'your-user-key',
  
  // 文件扫描配置
  scan: {
    include: ['src/**/*.{js,jsx,ts,tsx,vue}'],
    exclude: ['node_modules/**', 'dist/**'],
    patterns: [
      /t\(['"`](.+?)['"`]\)/g,        // t('文本')
      /\$t\(['"`](.+?)['"`]\)/g,      // $t('文本')
      /<T[^>]*text=['"`](.+?)['"`]/g  // <T text="文本" />
    ]
  },
  
  // 输出配置
  output: {
    format: 'json', // 'json' | 'yaml' | 'po'
    directory: './i18n/translations',
    filename: '[lang].json'
  }
};
```

### 3. 提取文本

```bash
# 扫描代码，提取需要翻译的文本
ui18n extract

# 指定扫描目录
ui18n extract --input src/

# 指定输出文件
ui18n extract --output ./i18n/texts.json

# 增量提取（只提取新文本）
ui18n extract --incremental
```

### 4. 批量翻译

```bash
# 翻译到所有目标语言
ui18n translate

# 翻译到特定语言
ui18n translate --languages en,ja

# 指定输入文件
ui18n translate --input ./i18n/texts.json

# 并发控制
ui18n translate --concurrency 3

# 预览模式（不实际翻译）
ui18n translate --dry-run
```

### 5. 查看统计

```bash
# 查看项目统计
ui18n stats

# 详细统计
ui18n stats --detailed

# 成本分析
ui18n stats --cost
```

## 📝 详细命令

### `ui18n init`

初始化新的国际化项目。

```bash
ui18n init [项目名称] [选项]

选项:
  --framework <type>    指定框架 (react|vue|angular|vanilla)
  --template <name>     使用模板 (basic|advanced|enterprise)
  --ai-provider <type>  AI提供商 (openai|claude|qwen)
  --languages <langs>   目标语言列表，逗号分隔
  --force              强制覆盖已存在的文件
```

示例：
```bash
ui18n init my-app --framework react --languages en,ja,ko
```

### `ui18n extract`

从代码中提取需要翻译的文本。

```bash
ui18n extract [选项]

选项:
  --input <dir>         扫描目录 (默认: src/)
  --output <file>       输出文件 (默认: i18n/texts.json)
  --patterns <file>     自定义提取规则文件
  --incremental         增量提取模式
  --format <type>       输出格式 (json|yaml|csv)
  --exclude <patterns>  排除文件模式
  --min-length <num>    最小文本长度
  --max-length <num>    最大文本长度
```

示例：
```bash
ui18n extract --input src/ --output i18n/texts.json --incremental
```

### `ui18n translate`

批量翻译文本。

```bash
ui18n translate [选项]

选项:
  --input <file>        输入文件 (默认: i18n/texts.json)
  --output <dir>        输出目录 (默认: i18n/translations/)
  --languages <langs>   目标语言，逗号分隔
  --concurrency <num>   并发数 (默认: 3)
  --batch-size <num>    批处理大小 (默认: 10)
  --dry-run            预览模式，不实际翻译
  --force              强制重新翻译已有内容
  --cache-only         仅使用缓存，不调用AI
```

示例：
```bash
ui18n translate --languages en,ja --concurrency 5 --batch-size 20
```

### `ui18n stats`

查看项目统计信息。

```bash
ui18n stats [选项]

选项:
  --detailed           显示详细统计
  --cost               显示成本分析
  --format <type>      输出格式 (table|json|csv)
  --export <file>      导出统计到文件
  --languages <langs>  指定语言范围
```

示例：
```bash
ui18n stats --detailed --cost --export stats.json
```

### `ui18n config`

管理项目配置。

```bash
ui18n config <action> [选项]

Actions:
  get <key>            获取配置值
  set <key> <value>    设置配置值
  list                 列出所有配置
  reset                重置为默认配置
  validate             验证配置文件

选项:
  --global             操作全局配置
  --config <file>      指定配置文件
```

示例：
```bash
ui18n config set aiProvider.apiKey sk-xxx
ui18n config get targetLanguages
ui18n config list --global
```

## 🔧 配置文件详解

### 完整配置示例

```javascript
// ui18n.config.js
module.exports = {
  // 基础设置
  defaultLanguage: 'zh-CN',
  targetLanguages: ['en', 'ja', 'ko', 'es', 'fr'],
  fallbackLanguage: 'en',
  
  // AI提供商配置（自托管模式）
  aiProvider: {
    type: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1',
    model: 'gpt-3.5-turbo',
    timeout: 30000,
    retries: 3,
    
    // 自定义提示词
    systemPrompt: '你是一个专业的UI文本翻译专家...',
    
    // 请求配置
    requestConfig: {
      temperature: 0.1,
      max_tokens: 1000
    }
  },
  
  // 云端服务配置（可选）
  // serviceMode: 'cloud',
  // userKey: 'your-user-key',
  
  // 文件扫描配置
  scan: {
    include: [
      'src/**/*.{js,jsx,ts,tsx}',
      'src/**/*.vue',
      'pages/**/*.{js,ts,jsx,tsx}'
    ],
    exclude: [
      'node_modules/**',
      'dist/**',
      'build/**',
      '**/*.test.{js,ts}',
      '**/*.spec.{js,ts}'
    ],
    
    // 文本提取规则
    patterns: [
      // 函数调用模式
      {
        pattern: /t\(['"`](.+?)['"`]\)/g,
        description: 't() 函数调用'
      },
      {
        pattern: /\$t\(['"`](.+?)['"`]\)/g,
        description: 'Vue $t() 调用'
      },
      
      // JSX/组件模式
      {
        pattern: /<T[^>]*text=['"`](.+?)['"`]/g,
        description: 'T 组件 text 属性'
      },
      {
        pattern: /<Trans[^>]*i18nKey=['"`](.+?)['"`]/g,
        description: 'react-i18next Trans 组件'
      },
      
      // 自定义模式
      {
        pattern: /translate\(['"`](.+?)['"`]\)/g,
        description: '自定义 translate 函数'
      }
    ],
    
    // 过滤规则
    filters: {
      minLength: 2,
      maxLength: 200,
      excludePatterns: [
        /^[0-9]+$/,           // 纯数字
        /^[a-zA-Z0-9_-]+$/,   // 变量名格式
        /^\s*$/               // 空白字符
      ]
    }
  },
  
  // 翻译配置
  translation: {
    batchSize: 10,
    maxConcurrency: 3,
    retryAttempts: 3,
    retryDelay: 1000,
    
    // 质量控制
    qualityCheck: {
      enabled: true,
      maxLengthRatio: 3.0,  // 译文长度不超过原文3倍
      minSimilarity: 0.3    // 最小相似度
    }
  },
  
  // 缓存配置
  cache: {
    enabled: true,
    directory: './i18n/cache',
    ttl: 7 * 24 * 60 * 60 * 1000, // 7天
    compression: true
  },
  
  // 输出配置
  output: {
    format: 'json',
    directory: './i18n/translations',
    filename: '[lang].json',
    indent: 2,
    sortKeys: true,
    
    // 多格式输出
    formats: {
      json: {
        filename: '[lang].json',
        indent: 2
      },
      yaml: {
        filename: '[lang].yml'
      },
      po: {
        filename: '[lang].po',
        metadata: {
          'Project-Id-Version': 'MyApp 1.0',
          'Language': '[lang]'
        }
      }
    }
  },
  
  // 钩子函数
  hooks: {
    beforeExtract: async (config) => {
      console.log('开始提取文本...');
    },
    afterExtract: async (texts, config) => {
      console.log(`提取了 ${texts.length} 个文本`);
    },
    beforeTranslate: async (texts, targetLang, config) => {
      console.log(`开始翻译到 ${targetLang}...`);
    },
    afterTranslate: async (results, targetLang, config) => {
      console.log(`翻译完成: ${Object.keys(results).length} 个文本`);
    }
  }
};
```

## 🎯 使用场景

### 1. 新项目快速启动

```bash
# 创建React项目的国际化配置
ui18n init my-react-app --framework react --languages en,ja,ko

# 提取现有代码中的文本
ui18n extract --input src/

# 批量翻译
ui18n translate --languages en,ja,ko
```

### 2. 持续集成/部署

```bash
#!/bin/bash
# CI/CD 脚本示例

# 提取新文本
ui18n extract --incremental

# 检查是否有新文本需要翻译
if [ -s i18n/texts.json ]; then
  echo "发现新文本，开始翻译..."
  ui18n translate --cache-only || ui18n translate
fi

# 验证翻译完整性
ui18n stats --format json > translation-stats.json
```

### 3. 成本控制

```bash
# 预览翻译成本
ui18n translate --dry-run --detailed

# 仅使用缓存翻译
ui18n translate --cache-only

# 查看成本分析
ui18n stats --cost
```

### 4. 团队协作

```bash
# 导出待翻译文本给翻译团队
ui18n extract --format csv --output texts-for-translation.csv

# 导入翻译结果
ui18n import --input translations.csv --format csv

# 生成翻译报告
ui18n stats --detailed --export team-report.json
```

## 🔌 插件系统

CLI支持插件扩展功能：

```javascript
// ui18n.config.js
module.exports = {
  plugins: [
    // 自定义提取器插件
    {
      name: 'custom-extractor',
      extract: async (files) => {
        // 自定义提取逻辑
      }
    },
    
    // 翻译后处理插件
    {
      name: 'post-processor',
      afterTranslate: async (results) => {
        // 翻译后处理逻辑
      }
    }
  ]
};
```

## 📊 输出格式

### JSON格式
```json
{
  "保存": "Save",
  "取消": "Cancel",
  "确定": "OK"
}
```

### YAML格式
```yaml
保存: Save
取消: Cancel
确定: OK
```

### PO格式
```po
msgid "保存"
msgstr "Save"

msgid "取消"
msgstr "Cancel"
```

## 🤝 贡献

欢迎贡献代码！请查看 [贡献指南](../../CONTRIBUTING.md)。

## 📄 许可证

MIT License - 详见 [LICENSE](../../LICENSE) 文件。

---

**让国际化管理变得简单高效！** 🛠️✨