cn2an handles the Chinese numeral cases a lookup table misses

Turning spoken numbers into digits, in both directions

cn2an converts between Chinese numerals and Arabic numerals. That sounds like a small problem until you try it, and the reason the package exists is that Chinese number writing is positional in a way that defeats a lookup table.

The immediate use is cleaning up speech recognition output. A Chinese recognition model transcribes what was said, and what was said is words, so a price, a date or a temperature arrives as characters rather than digits. Anything downstream that wants to compare, store or calculate needs the digits. The package's own topic list names speech recognition among its uses, and that is the pipeline position it occupies.

The reverse direction matters for output rather than input. Generating Chinese text that reads naturally means writing numbers the way a person would, and a template that emits bare digits where a sentence wants characters produces text that reads as machine-written.

Why this needs a library and not a dictionary

Mapping ten characters to ten digits is the easy part and it is not where the difficulty lives.

Chinese numerals carry positional markers rather than relying on digit position, so the characters for ten, hundred, thousand and ten thousand are part of the number itself. A form meaning ten-three is thirteen, while a form meaning three-ten is thirty, and the same character has done different work in each. Larger numbers group in units of ten thousand rather than in thousands, so the grouping boundaries fall in different places from the ones a Western-trained parser expects, and conversion has to regroup rather than insert separators.

Then there are the parallel writing systems. Alongside everyday numerals sit the formal characters used on financial documents, which exist because the simple forms are easy to alter with a pen stroke. The package handles those in both directions, including producing the formal currency form, which is exactly the case where getting it wrong matters most.

On top of that sit mixed forms, where a sentence carries part of a number in characters and part in digits, and decimals and negatives, each of which the package lists explicitly.

Sentence level is where the real work happens

The feature list separates single values from sentences, and the second category is the one that decides whether this saves you time.

Converting one isolated numeral is a solved problem you could write yourself. Converting numerals inside running text means finding them first, deciding where each one ends, and knowing when a numeral is not a quantity at all. The package handles dates, fractions, percentages and temperatures in sentence context, in both directions.

Those four are a well-chosen set, because each one breaks naive extraction differently. A date has several numbers with separators that are themselves characters. A fraction is written with the denominator first in Chinese, which is the opposite order from the arithmetic form, so a converter that reads left to right and does nothing else produces an inverted fraction. A percentage uses a leading marker rather than a trailing symbol. A temperature carries a unit that has to survive the conversion.

Getting the fraction ordering right is the detail that tells you someone met this problem in production rather than writing a demonstration.

Installing it, and the dependency footprint

The package is published to the index and the README recommends staying current.

pip install cn2an -U

Installing from a checkout is also documented, for anyone who needs to modify it or work from an unreleased state.

git clone https://github.com/Ailln/cn2an.git
cd cn2an && python setup.py install

Python 3.7 or newer is required, and the setup script enforces it by raising an error on older interpreters rather than failing later in a confusing way. The dependency list is a single package, declared with a minimum version, which for a library meant to sit inside someone else's text pipeline is the right weight. A normalisation utility that dragged in a large dependency tree would be rejected on that basis alone.

Confirming the install is one line, and checking which version you ended up with matters here, because the README notes the latest release fixes parsing and transformation edge cases.

import cn2an

The repository also lists an HTTP interface among its features, so the conversion can be reached as a service rather than as a library, which suits a pipeline where the surrounding code is not Python.

What to be careful about

The first thing to establish is which version you have, because this is a package whose correctness lives in edge cases. The README's own release note describes the current version as fixing numeral parsing and transformation edge cases, which is the recurring shape of changes to a converter: not new features, but another input someone found that produced the wrong answer. Pinning an old version here means keeping known defects.

There are no tagged releases on the repository, so the version history lives on the package index rather than in the source host, and a reader comparing two checkouts has no release notes between them.

The documentation is written in Chinese. For a library about Chinese text that is a reasonable choice and it is a genuine barrier for anyone else, with the linked interface reference being the route in.

The wider limitation is scope, and it is worth being clear rather than disappointed later. This converts numerals. It is not a text normalisation suite: it will not expand abbreviations, handle units generally, or resolve the many other ways spoken text differs from written text. Sibling projects exist for English numerals and for a different programming language, and the English one is described as still collecting requirements, so it is not a substitute today.

Writing the mapping yourself is the alternative

The honest alternative for most teams is a hand-written converter, because the first version takes an hour and appears to work.

The difference in approach is what happens after that hour. A hand-rolled mapping handles the digits, then meets the positional markers and grows a special case. Then it meets grouping at ten thousand and grows another. Then formal financial characters, then mixed character and digit forms, then a fraction whose parts arrive in the reverse order, then a date that is three numbers with character separators. Each of those is discovered in production, usually as a wrong number rather than an exception, which is the failure mode that makes numeric conversion worth delegating: a crash gets fixed, a silently wrong price does not.

The case for writing your own is real when the input is narrow and controlled. If you are parsing one field from one form that only ever contains a plain integer, a dictionary is less work than a dependency.

The case for the library is everything else, and particularly anything reading free text, where the set of numeral forms you will encounter is not knowable in advance. One dependency with one transitive requirement is a low price for that.

MIT terms and maintenance signals

cn2an is MIT licensed, which for a utility library is the expected choice and clears review without discussion.

The repository shows the habits of a maintained package rather than a published snapshot: separate requirement files for runtime, development and testing, a build workflow, an example directory, a scripts directory, and a manifest for packaging. A published interface reference is linked from the README, and download statistics are surfaced on the index page. The last push was on 2026-04-23.

The maintainer also runs sibling projects, a version for another programming language and a planned English equivalent, which suggests continued interest in the problem rather than a single artifact.

Upgrade cost should be low, since the interface is a small set of conversion functions and the changes described are corrections rather than redesigns. The practical habit is to take new versions promptly and keep a set of your own known inputs as a regression check, because the value of this package is precisely in the cases nobody thinks to test.

Editorial conclusion

cn2an fits anyone normalising Chinese text where numbers arrive as characters, most commonly downstream of speech recognition, or generating Chinese text that should read naturally rather than printing bare digits. Writing your own mapping remains reasonable when the input is one controlled field containing a plain integer. Take a recent version rather than pinning an old one, since the changes described are corrections to parsing and transformation edge cases rather than new features, and keep your own known inputs as a regression check, because there are no tagged releases on the repository and the version history lives on the package index instead.

Frequently asked questions

Official sources

1. Ailln/cn2an on GitHub
2. Issues
3. License: MIT
4. Project website
5. README