Repository: studyzy/imewlconverter

Stars: 9843

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

IME WL Converter (深蓝词库转换) is a cross-platform dictionary converter for Input Method Editors (IMEs). It converts dictionary files between 20+ different IME formats including Sougou Pinyin, QQ Pinyin, Rime, Google Pinyin, Baidu Pinyin, and many others.

Language: C# (.NET 10.0)
License: GPL-3.0
Platforms: Windows, Linux, macOS

Common Commands Copy Chapter

Build Commands Copy Section

Restore NuGet packages

make restore
Build all projects (Debug mode)

make build
Build Release configuration

make build-release
Build command-line tool only

make build-cmd
Build macOS GUI version

make build-mac

Testing Copy Section

Run unit tests

make test
Run unit tests with verbose output

make test-verbose
Run integration tests (requires CLI built first)

make integration-test
Run integration tests with debug output

cd tests/integration
./run-tests.sh --all -v

Running the Application Copy Section

Run CLI tool

make run-cmd
Run macOS GUI

make run-mac
Run CLI directly with dotnet

dotnet run --project src/ImeWlConverterCmd

CLI Usage Examples Copy Section

Convert Sougou .scel to Google Pinyin text format

dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O output.txt input.scel
Convert multiple files

dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O ./output/ file1.scel file2.scel
Apply filters (length, rank, remove English/numbers)

dotnet run --project src/ImeWlConverterCmd -- \
  -i scel -o ggpy -O output.txt \
  -f "len:1-100|rank:2-9999|rm:eng|rm:num" \
  input.scel

Code Quality Copy Section

Format code

make format
Check code formatting (CI)

make lint

Publishing and Packaging Copy Section

Publish macOS versions (ARM64 + x64)

make publish-mac
Create macOS .app bundles

make app-mac
Create distributable .zip packages

make package-mac

High-Level Architecture Copy Chapter

Core Components Copy Section

The codebase follows a plugin-style architecture with clear separation of concerns:

1. ImeWlConverterCore - Core library containing all conversion logic
2. ImeWlConverterCmd - Command-line interface
3. ImeWlConverterMac - macOS GUI application (Avalonia UI)
4. IME WL Converter Win - Windows GUI application (WinForms/WPF)
5. ImeWlConverterCoreTest - Unit tests

Conversion Pipeline Copy Section

The conversion process follows a pipeline architecture:

Input File → Import → Filters → Code Generation → Export → Output File

Key Classes:

- MainBody - Orchestrates the entire conversion pipeline
- ConsoleRun - Handles CLI argument parsing and execution
- IWordLibraryImport - Interface for all input format parsers
- IWordLibraryExport - Interface for all output format generators
- WordLibrary - Core data structure representing a dictionary entry (word + code + rank)
- WordLibraryList - Collection of WordLibrary entries

Directory Structure Copy Section

src/ImeWlConverterCore/
├── IME/              # Input format parsers (20+ formats)
│   ├── SougouPinyin.cs
│   ├── QQPinyin.cs
│   ├── Rime.cs
│   └── ...
├── Generaters/       # Output format generators
│   ├── PinyinGenerater.cs
│   ├── Wubi86Generater.cs
│   └── ...
├── Filters/          # Word filtering logic
│   ├── LengthFilter.cs
│   ├── RankFilter.cs
│   ├── EnglishFilter.cs
│   └── ...
├── Helpers/          # Utility functions
│   ├── PinyinHelper.cs
│   ├── BinFileHelper.cs
│   └── ...
├── Entities/         # Data models (WordLibrary, CodeType, etc.)
├── MainBody.cs       # Core orchestration logic
└── ConsoleRun.cs     # CLI argument handling

Adding New Format Support Copy Section

To add support for a new IME format:

1. For Import: Create a new class in src/ImeWlConverterCore/IME/ that implements IWordLibraryImport
- Inherit from BaseImport or BaseTextImport for common functionality
- Implement Import(string path) to parse the file format
- Add the format to the import registry in ConsoleRun.LoadImeList()

2. For Export: Create a new class that implements IWordLibraryExport
- Implement Export(WordLibraryList) to generate output
- Implement ExportLine(WordLibrary) for line-by-line export
- Add the format to the export registry in ConsoleRun.LoadImeList()

3. Add the format constant to ConstantString.cs with a short code (e.g., SOUGOU_XIBAO_SCEL_C = "scel")

Code Generation System Copy Section

The codebase supports multiple encoding methods (Pinyin, Wubi, Cangjie, etc.) through the IWordCodeGenerater interface:

- PinyinGenerater - Full Pinyin and Shuangpin (double Pinyin)
- Wubi86Generater, Wubi98Generater - Wubi input methods
- SelfDefiningCodeGenerater - Custom user-defined encoding

Generators can read encoding tables from resource files or user-provided files.

Filter System Copy Section

Filters are applied after import but before export:

- Single Filters (ISingleFilter): Process individual entries (e.g., LengthFilter, RankFilter)
- Batch Filters (IBatchFilter): Process the entire word list (e.g., deduplication)
- Filters are configured via CLI with -f or --filter parameter

Chinese Character Conversion Copy Section

Built-in support for simplified/traditional Chinese conversion through the IChineseConverter interface.

Integration Tests Copy Chapter

The project uses a shell-based integration test framework located in tests/integration/.

Test Structure Copy Section

- test-cases/ - Test case definitions organized by format or feature
- 1-imports/ - Tests for importing various formats to CSV
- 2-exports/ - Tests for exporting CSV to various formats
- 3-advanced/ - Advanced features (filters, encoding, large files)
- Each test suite has a test-config.yaml defining test cases
- Test data is sourced from src/ImeWlConverterCoreTest/Test/ (shared with unit tests)

Running Integration Tests Copy Section

Run all tests

cd tests/integration
./run-tests.sh --all
Run specific suite

./run-tests.sh -s 1-imports
Run with verbose output

./run-tests.sh -s 1-imports -v
Keep output files for debugging

./run-tests.sh -s 1-imports --keep-output
Generate JUnit XML report (for CI)

./run-tests.sh --all --xml

Adding Integration Tests Copy Section

1. Choose or create a test suite directory under tests/integration/test-cases/
2. Create or update test-config.yaml with your test case
3. Reference existing test files from src/ImeWlConverterCoreTest/Test/ using relative paths
4. Generate expected output by running the converter manually
5. Run ./run-tests.sh -s <suite-name> to verify

See tests/integration/README.md for detailed documentation.

Version Management Copy Chapter

Version numbers are automatically generated from Git tags using MinVer:

- Tags follow semantic versioning (e.g., v2.9.0)
- Version is embedded in assemblies at build time
- Check version: make version

Build Configuration Copy Chapter

- Debug: Default, includes debugging symbols
- Release: Optimized builds with:
- Code trimming (PublishTrimmed=true)
- Single-file publishing (PublishSingleFile=true)
- ReadyToRun compilation for faster startup
- No PDB files

CI/CD Workflow Copy Chapter

GitHub Actions workflow (.github/workflows/ci.yml):

1. Lint - Code formatting check (fast-fail)
2. Build and Test - Build + unit tests on Ubuntu
3. Platform Builds - Parallel builds for Windows (x64/x86), Linux (x64/arm64), macOS (x64/arm64)
4. Integration Tests - Run on Linux and macOS builds
5. Artifacts retained for 7-30 days

OpenSpec Integration Copy Chapter

This project uses OpenSpec workflow for specification-driven development:

- Specs located in specs/ directory
- Integration test specification in specs/001-integration-tests/
- Uses YAML contracts for test case schemas
- OpenSpec configuration in .specify/ and openspec/ directories

Important Notes Copy Chapter

Character Encoding Copy Section

The codebase handles multiple encodings (UTF-8, GBK, GB2312, Big5). Always register the CodePagesEncodingProvider:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

This is done in Program.cs and MainBody.cs constructors.

Binary File Formats Copy Section

Several IME formats use proprietary binary formats (e.g., .scel, .bdict, .qpyd). Parsers for these are in:

- BinFileHelper.cs - Binary reading utilities
- Individual format classes (e.g., SougouPinyin.cs for .scel files)

Reverse engineering documentation for these formats is not provided in the codebase but can be found in related Chinese forums.

Resource Files Copy Section

Encoding tables and dictionaries are embedded as resources:

- src/ImeWlConverterCore/Resources/ - Contains .txt files for various encoding tables
- Access via DictionaryHelper.GetResourceContent(filename)

Cross-Platform Considerations Copy Section

- Use Path.Combine() for file paths, never hardcode separators
- The CLI tool is framework-dependent (requires .NET runtime)
- macOS app bundles include the full .NET runtime (self-contained)
- Integration tests work on Linux, macOS, and Windows (Git Bash)

Debugging Tips Copy Chapter

Integration Test Failures Copy Section

Keep test output for inspection

cd tests/integration
./run-tests.sh -s <suite> --keep-output
Manually run conversion to debug

dotnet run --project ../../src/ImeWlConverterCmd -- \
  -i <format> -o <format> -O <output-file> <input-file>
Compare output

diff -u expected.txt test-output/actual.txt

Unit Test Debugging Copy Section

Test data is in src/ImeWlConverterCoreTest/Test/ with real dictionary files from various IME formats. Tests cover:

- Format parsing (import)
- Format generation (export)
- Filters
- Helpers (Pinyin, Wubi, etc.)

README.md Copy Chapter

<div align="center">

深蓝词库转换

!Actions Check
!Integration Tests
!License
!Repo size

!Downloads

一款输入法词库转换软件，支持以下超过 20 种的输入法工具和词库

</div>

本程序支持批量转换（一次拖拽多个词库文件，或者按住 Ctrl 选择多个文件），支持命令行模式（在命令行下使用-h命令查看帮助），支持 Windows、Linux、MacOS。

支持列表 Copy Section

PC 端：

- Chinese-pyim(Linux)
- FIT 输入法(Mac)
- libpinyin(Linux)
- MacOS 自带简体拼音
- QQ 拼音（文本词库和 qpyd 格式分类词库）
- QQ 五笔
- Rime 输入法(Linux 中州韻、Windows 小狼毫、Mac OS 鼠鬚管)
- Win10 微软拼音
- Win10 微软五笔
- 百度拼音 PC（文本词库、bdict 格式）
- 必应输入法
- 仓颉平台
- 谷歌拼音
- 极点五笔
- 极点郑码
- 灵格斯词库 ld2
- 拼音加加
- 手心输入法
- 搜狗拼音（文本词库、Bin 格式备份词库和 scel 格式细胞词库）
- 搜狗五笔
- 微软拼音 2010
- 小小输入法（拼音、五笔、郑码、二笔）
- 小鸭五笔
- 新浪拼音
- 雅虎奇摩输入法（注音）
- 紫光拼音（文本词库和 uwl 格式分类词库）
- 自定义格式

手机端：

- QQ 手机拼音
- 百度手机拼音（文本词库和 bcd 格式）
- 谷歌拼音输入法

该软件支持 6 种以上的输入法编码方法：

- 仓颉
- 二笔（超强二笔，青松二笔等）
- 拼音（全拼、双拼）
- 五笔（五笔 86、五笔 98、新世纪五笔）
- 郑码
- 注音
- 自定义

命令行使用 Copy Chapter

基本语法 Copy Section

imewlconverter --input-format <格式> --output-format <格式> --output <输出路径> <输入文件>...

或使用短选项：

imewlconverter -i <格式> -o <格式> -O <输出路径> <输入文件>...

常用示例 Copy Section

单文件转换：

imewlconverter -i scel -o ggpy -O output.txt input.scel

多文件转换：

imewlconverter -i scel -o ggpy -O output.txt file1.scel file2.scel file3.scel

批量转换到目录（输出目录以 / 结尾）：

imewlconverter -i scel -o ggpy -O ./output/ *.scel

使用过滤器：

imewlconverter -i scel -o ggpy -O output.txt -f "len:1-100|rm:eng|rm:num" input.scel

查看帮助：

imewlconverter --help
imewlconverter --list-formats  # 查看支持的格式列表

重要说明 Copy Section

从 v3.0.0 开始，命令行参数格式已更新为 GNU 风格。如果您使用的是旧格式（如 -i:scel），请参阅 MIGRATION.md 进行迁移。

集成测试 Copy Chapter

本项目包含完整的集成测试框架，确保各种输入法格式之间的转换正确性。

快速运行测试 Copy Section

1. 编译CLI工具

cd src/ImeWlConverterCmd
dotnet build -c Release
2. 运行集成测试

cd ../../tests/integration
./run-tests.sh --all

测试覆盖范围 Copy Section

当前已实现：
- ✅ 导入测试（多种输入格式 → 统一CSV格式）
- ✅ 导出测试（统一CSV格式 → 多种输出格式）
- ✅ 高级功能测试（过滤、编码、大文件性能）

详细的测试矩阵与数据来源见 tests/integration/TEST-MATRIX.md。

更多信息 Copy Section

- 集成测试完整文档
- 测试用例配置规范
- 测试数据来源

Star History Copy Chapter