vite-plugin-i18n-extract/README.md

Vite 插件：自动收集中文并翻译为多语言

# vite-plugin-i18n-extract

一个 Vite 插件，用于自动提取中文文本并翻译为多语言。

## 功能特点

- 自动扫描项目中的 `.js`、`.jsx` 和 `.vue` 文件
- 自动提取所有中文文本，生成 JSON 格式的多语言文件
- 通过翻译 API（百度翻译）自动翻译为指定语言
- 生成可直接配合 vue-i18n 使用的多语言资源文件
- 支持翻译缓存，避免重复翻译相同内容
- 支持忽略特定标记的中文文本

## 安装

```bash
npm install vite-plugin-i18n-extract --save-dev
```

## 基本用法

在 `vite.config.js` 中配置插件：

```javascript
// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import i18nExtractPlugin from 'vite-plugin-i18n-extract';

export default defineConfig({
  plugins: [
    vue(),
    i18nExtractPlugin({
      outputDir: './src/locales',
      sourceLanguage: 'zh-CN',
      targetLanguages: ['en-US', 'ja-JP'],
      translationService: 'baidu',
      apiKey: 'your-baidu-api-key',
      apiSecret: 'your-baidu-api-secret',
      exclude: ['node_modules', 'dist']
    })
  ]
});
```

## 配置选项

```typescript
interface PluginOptions {
  // 基础配置
  outputDir?: string; // 语言文件输出目录，默认为 './src/locales'
  sourceLanguage?: string; // 源语言代码（默认 zh-CN）
  targetLanguages?: string[]; // 需要翻译的目标语言代码
  
  // 文件扫描配置
  include?: string[]; // 包含的文件/目录
  exclude?: string[]; // 排除的文件/目录
  extensions?: string[]; // 扫描的文件扩展名
  
  // 翻译配置
  translationService?: 'baidu' | 'google' | 'deepl'; // 翻译服务
  apiKey?: string; // API密钥
  apiSecret?: string; // API密钥Secret（部分翻译服务需要）
  apiConfig?: Record<string, any>; // 服务特定配置
  
  // 高级配置
  hashAlgorithm?: string; // 哈希算法
  maxConcurrentRequests?: number; // 最大并发翻译请求
  cacheEnabled?: boolean; // 是否启用翻译缓存
  placeholderPattern?: string; // 变量占位符模式
  ignoreMark?: string; // 忽略标记（如 // i18n-ignore）
}
```

## 忽略特定文本

如果你不希望某些中文文本被提取和翻译，可以在代码中添加注释 `// i18n-ignore`：

```javascript
// 以下中文将被提取和翻译
const message = "你好，世界！";

// 以下中文将被忽略
// i18n-ignore
const ignoredMessage = "这段文本不会被提取";
```

## 输出结果

插件会在指定的输出目录（默认为 `./src/locales`）生成以下文件：

```
src/
  locales/
    zh-CN.json       # 原始中文
    en-US.json       # 英文翻译
    ja-JP.json       # 日文翻译（如果配置了）
    .i18n-cache      # 翻译缓存
```

这些文件可以直接用于 vue-i18n 的配置。

## 与 vue-i18n 集成

在你的 Vue 应用中，可以这样使用生成的语言文件：

```javascript
// i18n.js
import { createI18n } from 'vue-i18n';
import zhCN from './locales/zh-CN.json';
import enUS from './locales/en-US.json';
import jaJP from './locales/ja-JP.json';

const i18n = createI18n({
  legacy: false,
  locale: 'zh-CN',
  fallbackLocale: 'zh-CN',
  messages: {
    'zh-CN': zhCN,
    'en-US': enUS,
    'ja-JP': jaJP,
  },
});

export default i18n;
```

然后在 `main.js` 中导入并使用：

```javascript
import { createApp } from 'vue';
import App from './App.vue';
import i18n from './i18n';

createApp(App).use(i18n).mount('#app');
```

## 使用示例

请查看 [examples](./examples) 目录中的完整示例项目，了解如何在 Vue 3 项目中使用本插件。

## 支持的翻译服务

当前版本支持以下翻译服务：

- 百度翻译 API（默认）
- 更多翻译服务将在后续版本中添加

## 已知问题

1. 当前版本仅支持百度翻译 API，未来计划添加更多翻译服务支持
2. 在某些环境中可能遇到类继承相关的错误，可能需要调整 TypeScript 配置
3. 目前仅支持中文提取，未来可能会扩展到其他语言

## 贡献

欢迎各种形式的贡献：

1. 提交 Issue 报告 bug 或提出功能请求
2. 提交 Pull Request 改进代码
3. 改进文档或添加示例

请遵循以下步骤：

```bash
# 克隆仓库
git clone https://github.com/yourusername/vite-plugin-i18n-extract.git

# 安装依赖
npm install

# 构建项目
npm run build

# 测试插件
cd examples
npm install
npm run dev
```

## 更新日志

### 1.0.0 (2025-04-16)
- 首次发布
- 支持提取中文文本
- 支持百度翻译 API
- 支持翻译缓存
- 支持 Vue 3 + Vite 项目

## 许可证

MIT