# How book-to-skill Handles Multilingual Chapter Detection: Arabic, Roman, Chinese & Kangxi Support

> Discover how book-to-skill achieves multilingual chapter detection effortlessly. Supports Arabic, Roman, Chinese, and Kangxi numerals out of the box. Enhance your projects now.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: deep-dive
- Published: 2026-09-01

---

> **multilingual chapter detection** is built into book-to-skill with native support for Arabic numerals, Roman numerals, traditional Chinese numerals, and Kangxi radicals—no configuration required.

The `book-to-skill` repository provides a robust chapter-extraction pipeline that recognizes chapter headings across multiple writing systems and numeral styles. Whether your source material uses standard Western numbering, classical Roman numerals, or traditional Chinese characters, the library automatically detects and parses chapter boundaries without manual intervention.

## Core Detection Mechanism in utils.py

The backbone of **multilingual chapter detection** resides in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py), specifically in the `_match_chapter_number` function starting at line 447. This function orchestrates multiple numeral parsers to identify valid chapter headings.

Each parser follows the same contract: attempt to extract an integer chapter number (1–999) from a heading string. If successful, the heading is treated as a chapter boundary.

## Supported Numeral Systems

### ASCII and Arabic Chapter Numbers

Standard numeric headings like `12  Introduction` are detected using regex pattern matching. The parser requires **two or more spaces** after the number to distinguish chapter headings from list items.

```python

# From book_to_skill/utils.py, lines 447-456

_match_chapter_number("12  Advanced Topics")   # → 12

```

The regex `^([1-9]\d{0,2})\s{2,}\S` enforces this spacing requirement, preventing false positives on numbered lists.

### Roman Numerals

Classical chapter numerals (`I`, `II`, `IV`, `IX`, `XIV`) are supported through bidirectional conversion functions. The `_roman_to_int` helper (lines 514–527) validates and converts Roman strings, while `_int_to_roman` (lines 502–511) handles reverse conversion when needed.

```python
_match_chapter_number("IX  Conclusion")        # → 9

_match_chapter_number("XIV  Appendices")       # → 14

```

### Chinese (Han) Numerals

Traditional Chinese characters for numbers are fully supported through the `_cn_numeral_to_int` function at lines 484–499. This parser recognizes both simple numerals (`一`, `二`, `三`) and compound forms with units (`二十`, `一百零八`).

The implementation maps individual characters using lookup tables `_CN_NUM_VALUES` and `_CN_NUM_UNITS`, enabling conversion of any valid Chinese numeral from 1 to 999.

```python
_match_chapter_number("二十一  章节标题")       # → 21

_match_chapter_number("一百零八  细节说明")     # → 108

```

### Kangxi Radicals Normalization

Before Chinese numeral parsing, the system normalizes Kangxi radicals (Unicode block U+2F00) into their corresponding ideographs. This preprocessing occurs in `_match_chapter_number` (lines 332–339) via `translate(_KANGXI_NUMERAL_TRANS)`.

This step ensures compatibility with legacy texts and specialized fonts that may use radical variants instead of standard Han characters.

### Full-Width Arabic Digits

East-Asian typography often employs full-width Arabic digits (`１`, `２`, `３`). These are handled transparently through the same numeric pipeline, converting to standard integers before chapter validation.

```python
_match_chapter_number("１２  序章")             # → 12

```

## Structural Chapter Detection

For documents with varied heading styles, `_structural_chapter_count` (lines 404–481) performs line-by-line analysis. This function:

- Skips fenced code blocks to avoid false chapter detection in source examples
- Applies the same multilingual numeral heuristics to Setext and ATX markdown headings
- Handles AsciiDoc and RST conventions through pattern-agnostic parsing

The structural walker feeds detected chapter boundaries into the skill generation pipeline, which outputs isolated chapter files to the `chapters/` directory.

## Working Code Example

```python
from book_to_skill.utils import _match_chapter_number

# Test all supported numeral systems

test_cases = [
    "12  Advanced Topics",           # ASCII Arabic

    "IX  Conclusion",                # Roman

    "二十一  章节标题",               # Chinese Han

    "１２  序章",                     # Full-width Arabic

]

for heading in test_cases:
    chapter_num = _match_chapter_number(heading)
    print(f"{heading!r:30} → {chapter_num}")

```

All four cases return valid integer chapter numbers, demonstrating the **multilingual chapter detection** capability without configuration switches or language flags.

## Integration with Document Parsers

Language-specific parsers in `book_to_skill/parsers/*.py` (PDF, HTML, EPUB) feed raw text into the chapter detector. This architecture separates format handling from numeral parsing, allowing any input format to leverage the same **multilingual chapter detection** engine.

The discovery tool at [`tools/discovery_tax.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/discovery_tax.py) demonstrates downstream reuse of chapter detection for analysis pipelines.

## Test Coverage

Unit tests in [`tests/test_book_to_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tests/test_book_to_skill.py) validate:

- Chinese numeral conversion edge cases (`_cn_numeral_to_int`)
- Roman numeral round-trip correctness (`_int_to_roman` ↔ `_roman_to_int`)
- Kangxi radical normalization accuracy
- Full-width digit handling

## Summary

- **multilingual chapter detection** in book-to-suport supports Arabic, Roman, Chinese, and Kangxi numeral systems out of the box
- Core logic resides in `_match_chapter_number` and helpers within [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py)
- No configuration required—detection is automatic based on character patterns
- Valid chapter numbers span 1–999 across all supported writing systems
- Line-based structural parsing handles markdown, AsciiDoc, and RST formats uniformly

## Frequently Asked Questions

### Does book-to-skill require language configuration for chapter detection?

No. The `_match_chapter_number` function automatically attempts multiple parsers in sequence: ASCII Arabic, Roman, Chinese, and full-width variants. The first successful conversion determines the chapter number without explicit language selection.

### What is the maximum chapter number supported?

All numeral parsers enforce a 1–999 range. Chinese numerals compound using units (`十`, `百`), Roman numerals follow classical construction rules, and Arabic formats accept 1–3 digit numbers. This bound prevents false positives on year dates and similar numeric strings.

### Can I extend support for additional numeral systems?

Yes. The parser architecture in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) accommodates new converters by adding conversion logic to `_match_chapter_number`. Each converter must return an integer or `None`, following the existing pattern of `_roman_to_int` and `_cn_numeral_to_int`.

### How does the system avoid detecting numbered lists as chapters?

The ASCII Arabic parser requires **two or more spaces** after the number via regex `\s{2,}`. Single-space separators typical of markdown lists (`1. Item`) fail this pattern, preserving list structure while capturing genuine chapter headings.