abbr2words

Multilingual, context-aware abbreviation expansion for text normalization and speech.

This standalone package was extracted from the abbreviation framework and language registries in kokorog2p. It has no runtime dependencies and uses a flat package layout (no src/ directory).

Supported languages

• Czech (cs)
• German (de)
• English (en)
• Spanish (es)
• French (fr)
• Italian (it)
• Portuguese (pt)

Locale forms such as de-DE, en_GB, and pt-BR are accepted and currently map to their base-language registry.

Installation

python -m pip install abbr2words

For development:

python -m pip install -e ".[dev]"
pytest

API

from abbr2words import abbr2words

text = "Prof. Klein kommt ggf. am Fr."
print(abbr2words(text, lang="de"))
# Professor Klein kommt gegebenenfalls am Freitag

Context can be disabled:

abbr2words("Fr. Klein", lang="de", context=False)
# Freitag Klein

Use an isolated mutable registry for project-specific entries:

from abbr2words import Expander

expander = Expander("de")
expander.add("KI", "Künstliche Intelligenz", case_sensitive=True)
print(expander("KI hilft."))

Consumers that need the shared language registry can use get_shared_expander() and reset_expanders(). Expander and get_expander() remain isolated mutable registries.

Command line

python -m abbr2words --lang de "Prof. Klein kommt ggf."
printf 'Prof. Klein kommt ggf.' | abbr2words --lang de

Scope

abbr2words expands known abbreviations and a reviewed inventory of unit symbols when a numeric quantity immediately precedes the complete unit expression. It preserves numeric values and does not spell ordinary numbers, parse dates, convert currencies, convert measurements, or perform unit conversion. Unit support is not universal UCUM support.

abbr2words("500 g", lang="en")
# "500 gram"

abbr2words("section g", lang="en")
# "section g"

Examples

The repository includes runnable examples for abbreviation-only expansion and for composing abbr2words with num2words:

python -m pip install "abbr2words[examples]"
python examples/abbreviations.py
python examples/full_text_demo.py --sample german

abbr2words itself expands abbreviations only. The optional examples show how to combine it with num2words for broader speech-text normalization, including output such as 500 g -> five hundred grams. The full-text demo is example code, not part of the stable public API. See examples/README.md for the complete command reference.

Versioning

The package version is derived from Git tags by setuptools-scm. Use tags in the form v0.2.0, v0.3.0, and so on; the corresponding package version is generated automatically during builds. A checkout without tags falls back to 0.2.0.

For a release, commit the changes, create an annotated tag, and build from that tag:

git tag -a v0.2.0 -m "Release 0.2.0"
uv build

License

Apache License 2.0. See LICENSE and NOTICE.