---
id: unicode-rbnf
version: "2.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# unicode-rbnf — Rule-based number formatting using Unicode CLDR data

License: permissive · Maintenance: active · Downloads: 216.5K/mo

## What it is and what it does

Unicode RBNF is a pure Python library that converts numbers into their spelled-out text equivalents using Unicode Common Locale Data Repository (CLDR) rules. It supports a large number of locales and multiple formatting purposes—cardinal numbers, ordinals, years, and others depending on what the locale defines. The engine returns a result object containing the primary text plus a dictionary of all available ruleset variants, which is useful for languages with grammatical variations like gender, case, or number agreement.

The library implements core RBNF features including literal text, quotient and remainder substitution, optional substitution, rule substitution and replacement, and special rules for negative numbers, improper fractions, NaN, and infinity. It does not yet support proper fractions, preceding remainder substitution, number format strings, decimal format patterns, or plural replacements. With no external dependencies and low install friction, it integrates easily into projects that need multilingual number-to-text conversion.

Use it for:

- Convert numeric values to words for accessibility features in applications serving multiple languages.
- Generate human-readable number spellings for formal documents, invoices, or legal text in locale-specific formats.
- Format numbers as ordinals (1st, 2nd, 11th) or years (nineteen ninety-nine) for display in multilingual UIs.
- Support gender and case agreement in languages where number words inflect based on grammatical properties.
- Build chatbots or voice interfaces that need to speak numbers naturally in different languages and contexts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts numbers to spelled-out text in multiple languages and formats using Unicode CLDR rule-based number formatting (RBNF).

Yes, if you need multilingual number-to-text conversion. The package is actively maintained, has no dependencies, installs easily, and covers a wide range of locales and formatting purposes. It is still in alpha, so some advanced RBNF features are not yet implemented—verify that the specific locales and formatting modes you need are supported before committing to production use.

## Install

pip install unicode-rbnf
uv add unicode-rbnf
poetry add unicode-rbnf

## Installing unicode-rbnf

Before you install: Low install friction; pure Python wheel with no runtime dependencies. Actively maintained with recent releases; currently at alpha status (Development Status :: 3 - Alpha).

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

from unicode_rbnf import RbnfEngine

engine = RbnfEngine.for_language("en")
result = engine.format_number(1234)
print(result.text)  # "one thousand two hundred thirty-four"

Requires Python 3.8 or later.

Verify before relying:

- Whether all CLDR locales listed in the upstream repository are fully supported or if some have partial/incomplete implementations.
- Performance characteristics when formatting very large numbers or when instantiating engines for many locales in sequence.
- Whether the package handles edge cases like very large integers, scientific notation inputs, or malformed locale strings gracefully.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 216.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

number to words conversion, spell out numbers multilingual, unicode rbnf formatting, locale-aware number spelling, cardinal ordinal year formatting, cldr number formatting, text number conversion, multilingual, number-formatting, accessibility

[View on SkillFed](https://skillfed.io/packages/unicode-rbnf) · [View on PyPI](https://pypi.org/project/unicode-rbnf/)