npm package: @milesight/changelog
Description: Changesets changelog generator with Conventional Commits support and i18n
Author: Milesight
Latest version: 1.0.0

# @milesight/changelog

> A [Changesets](https://github.com/changesets/changesets) changelog generator with [Conventional Commits](https://www.conventionalcommits.org/) support and built-in i18n.

[![npm version](https://img.shields.io/npm/v/@milesight/changelog)](https://www.npmjs.com/package/@milesight/changelog)
[![license](https://img.shields.io/npm/l/@milesight/changelog)](./LICENSE)

## Features

- **Conventional Commits** — Parses `type(scope)!: description` format and maps each type to an emoji automatically
- **i18n** — Ships with English and Chinese locales; configurable via `.changeset/config.json`
- **Custom types** — Extend or override the built-in commit type set per project
- **Rich summary formats** — Supports single-line, title + details, and multiple independent entries
- **Dual output** — Ships both CJS (`dist/index.js`) and ESM (`dist/index.mjs`) builds

## Installation

```bash
# npm
npm add -D @milesight/changelog

# pnpm
pnpm add -D @milesight/changelog

# yarn
yarn add -D @milesight/changelog
```

## Usage

Set `changelog` in your `.changeset/config.json`:

```json
{
  "changelog": ["@milesight/changelog", { "locale": "en" }]
}
```

That's it. Run `changeset version` as usual — changelogs are generated automatically.

## Options

| Option        | Type                                     | Default | Description                                      |
| ------------- | ---------------------------------------- | ------- | ------------------------------------------------ |
| `locale`      | `"en" \| "zh"`                           | `"en"`  | Display language for type labels and UI strings  |
| `customTypes` | `Record<string, TypeConfig>`             | —       | Additional or overriding commit types            |

### `TypeConfig`

```ts
interface TypeConfig {
  /** Emoji to display for this commit type */
  emoji: string;
  /**
   * Localized labels keyed by locale code.
   * Falls back to the English label, then the type key itself.
   */
  labels?: Partial<Record<'en' | 'zh', string>>;
}
```

## Built-in Commit Types

| Type       | Emoji | English Label | Chinese Label |
| ---------- | ----- | ------------- | ------------- |
| `feat`     | ✨     | New Feature   | 新特性        |
| `fix`      | 🐛    | Bug Fix       | 问题修复      |
| `perf`     | ⚡    | Performance   | 性能优化      |
| `refactor` | ♻️    | Refactor      | 代码重构      |
| `docs`     | 📝    | Documentation | 文档          |
| `style`    | 💅    | Style         | 样式          |
| `test`     | ✅    | Tests         | 测试          |
| `build`    | 🏗️   | Build         | 构建          |
| `ci`       | 👷    | CI/CD         | CI/CD         |
| `chore`    | 🔧    | Chore         | 杂项          |
| `revert`   | ⏪    | Revert        | 回退          |

Unrecognised types fall back to 📦.

## Custom Types

Add project-specific commit types via `customTypes`:

```json
{
  "changelog": [
    "@milesight/changelog",
    {
      "locale": "zh",
      "customTypes": {
        "release": {
          "emoji": "🚀",
          "labels": { "en": "Release", "zh": "正式发布" }
        },
        "security": {
          "emoji": "🔒",
          "labels": { "en": "Security", "zh": "安全修复" }
        }
      }
    }
  ]
}
```

Custom types are **merged** with the built-in set. If a key already exists (e.g. `feat`), the custom entry takes precedence.

## Changeset Summary Formats

The generator supports four summary formats:

**1. Single title**
```
fix: resolve null pointer in form submit
```

**2. Title + details**
```
feat: add theme token system
- supports light/dark variable sets
- exposes getCSSVariable helper
```

**3. Multiple independent titles**
```
feat: add useTheme hook
fix: correct focus ring on Safari
```

**4. Multiple titles each with details** (blank line as separator)
```
feat: add useTheme hook
- supports ThemeProvider injection
- reactive to system preference

fix: correct focus ring on Safari
- affected input and button components
```

## Output Example

Given a changeset with the summary above, the generated changelog entry looks like:

```markdown
- ✨ add useTheme hook
  - supports ThemeProvider injection
  - reactive to system preference

- 🐛 correct focus ring on Safari
  - affected input and button components
```

## i18n

Switch to Chinese by setting `"locale": "zh"`:

```json
{ "changelog": ["@milesight/changelog", { "locale": "zh" }] }
```

Breaking change markers and dependency update messages will then appear in Chinese:

```markdown
- ✨ 重新设计 API 接口 **[破坏性变更]**
- 📦 依赖 `lodash` 升级至 `4.18.0`
```

## License

[MIT](./LICENSE) © Milesight