i18n-sheet-convert/README.md

一个用于在i18n JSON文件和Excel文件之间进行转换的工具

# i18n-sheet-convert

一个用于在i18n JSON文件和Excel文件之间进行转换的工具。这个工具通过在JSON格式和Excel电子表格之间进行转换，帮助你管理国际化（i18n）翻译。

## 功能特点

- 将i18n JSON文件转换为Excel格式
- 将Excel文件转换回i18n JSON格式
- 支持嵌套的JSON结构
- 从Excel转换回时保持JSON结构
- Excel中自动调整列宽
- **从本地化目录自动检测语言**
- **支持自定义语言配置**
- 支持多种语言（不仅仅是中文和英文）

## 安装

```bash
npm install i18n-sheet-convert
# 或者
yarn add i18n-sheet-convert
# 或者
pnpm add i18n-sheet-convert
```

## 使用方法

### 自动检测语言

```typescript
import { I18nConverter } from 'i18n-sheet-convert';

// 转换器将自动检测本地化目录中的语言文件
const converter = new I18nConverter({
  localesPath: './locales',  // 包含JSON文件的目录
  outputPath: './output'     // Excel输出目录
});

// 将JSON转换为Excel
await converter.jsonToExcel();

// 将Excel转换回JSON
await converter.excelToJson();
```

### 手动语言配置

```typescript
import { I18nConverter } from 'i18n-sheet-convert';

const converter = new I18nConverter({
  localesPath: './locales',
  outputPath: './output',
  languages: [
    { code: 'zh-CN', name: '中文' },
    { code: 'en', name: 'English' },
    { code: 'ja', name: '日本語' },
    // 根据需要添加更多语言
  ]
});

await converter.jsonToExcel();
await converter.excelToJson();
```

### 文件结构

你的本地化目录应该包含以语言代码命名的JSON文件：
- `zh-CN.json`：中文翻译
- `en.json`：英文翻译
- `ja.json`：日语翻译
- 等等

Excel文件将在你的输出目录中生成为 `translations.xlsx`。

### JSON格式示例

```json
// zh-CN.json
{
  "common": {
    "submit": "提交",
    "cancel": "取消"
  }
}

// en.json
{
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}

// ja.json
{
  "common": {
    "submit": "送信",
    "cancel": "キャンセル"
  }
}
```

### Excel格式

生成的Excel文件将包含以下列：
- `key`：翻译键名（例如："common.submit"）
- 每种语言一列（例如："zh-CN"、"en"、"ja"）

## API

### `I18nConverter`

#### 构造函数

```typescript
constructor(options: I18nConverterOptions)
```

选项：
- `localesPath`：包含JSON文件的目录路径
- `outputPath`：Excel文件保存的路径
- `languages?`：可选的语言配置数组：
  ```typescript
  interface I18nLanguageConfig {
    code: string;    // 语言代码（例如：'en'，'zh-CN'）
    name: string;    // 显示名称（例如：'English'，'中文'）
  }
  ```

#### 方法

##### `jsonToExcel()`

将JSON文件转换为Excel格式。

##### `excelToJson()`

将Excel文件转换回JSON格式。