text2spoken 0.0.2a1__py3-none-any.whl

text2spoken/__init__.py

@@ -0,0 +1,50 @@
+"""Text normalization: rewriting written text into the words a voice should speak.
+
+``normalize(text, lang)`` is the entry point. It runs the raw text through the
+per-concern passes in this package — dates and times, hyphen-joined
+word/digit pairs, units and ordinal indicators, then a word-by-word pass that
+expands contractions, titles, fractions and bare numbers — so that nothing
+reaches the phonemizer as digits or symbols.
+
+The language-specific lookup tables live in :mod:`text2spoken.tables`,
+apart from the code that applies them, so a new language is a data change.
+"""
+
+from text2spoken.datetimes import (
+    _normalize_dates_and_times,
+    pronounce_date,
+    pronounce_time,
+)
+from text2spoken.numbers import (
+    _get_number_separators,
+    _normalize_number_word,
+    is_fraction,
+)
+from text2spoken.tables import CONTRACTIONS, TITLES, UNITS
+from text2spoken.text import (
+    _normalize_word,
+    _normalize_word_hyphen_digit,
+    expand_word,
+    normalize,
+)
+from text2spoken.units import _normalize_units
+from text2spoken.version import __version__
+
+expand_dates_and_times = _normalize_dates_and_times
+expand_hyphen_digits = _normalize_word_hyphen_digit
+expand_units = _normalize_units
+
+__all__ = [
+    "CONTRACTIONS",
+    "TITLES",
+    "UNITS",
+    "__version__",
+    "expand_dates_and_times",
+    "expand_hyphen_digits",
+    "expand_units",
+    "expand_word",
+    "is_fraction",
+    "normalize",
+    "pronounce_date",
+    "pronounce_time",
+]

text2spoken/datetimes.py

@@ -0,0 +1,119 @@
+"""Spoken forms for the date and time patterns that survive into raw text."""
+import datetime
+import re
+from datetime import date
+import logging
+
+from ovos_date_parser import nice_time, nice_date
+
+LOG = logging.getLogger("text2spoken")
+
+
+def pronounce_date(date_obj: date, full_lang: str) -> str:
+    """
+    Pronounces a date object using ovos-date-parser.
+    """
+    return nice_date(date_obj, full_lang)
+
+
+def pronounce_time(time_string: str, full_lang: str) -> str:
+    """
+    Pronounces a time string using ovos-date-parser.
+    Handles military time like "15h01" and converts it to a
+    datetime.time object before passing it to nice_time.
+    """
+    try:
+        hours, mins = time_string.split("h")
+        time_obj = datetime.time(int(hours), int(mins))
+        # Use nice_time from ovos-date-parser
+        return nice_time(time_obj, full_lang, speech=True, use_24hour=True, use_ampm=False)
+    except Exception as e:
+        LOG.warning(f"Failed to parse time string '{time_string}': {e}")
+        return time_string.replace("h", " ")
+
+
+def _normalize_dates_and_times(text: str, full_lang: str, date_format: str = "DMY") -> str:
+    """
+    Helper function to normalize dates and times using regular expressions.
+    This prepares the strings for pronunciation.
+    """
+    lang_code = full_lang.split("-")[0]
+    # Pre-process with regex to handle English am/pm times.
+    # Anchored to a preceding digit so ordinary words containing "am"/"pm"
+    # (e.g. "I am happy", "spam") are never touched.
+    if lang_code == "en":
+        text = re.sub(
+            r"(?i)\b(\d+)\s*([ap])\.?m\.?\b",
+            lambda m: f"{m.group(1)} {m.group(2).upper()} M",
+            text,
+        )
+
+    # Normalize times like "15h01" to words
+    time_pattern = re.compile(r"(\d{1,2})h(\d{2})", re.IGNORECASE)
+
+    def replace_time(match):
+        time_str = match.group(0)
+        return pronounce_time(time_str, full_lang)
+
+    text = time_pattern.sub(replace_time, text)
+
+    # Find dates like "DD/MM/YYYY" or "YYYY/MM/DD"
+    date_pattern = re.compile(r"(\d{1,4})[/-](\d{1,2})[/-](\d{1,4})")
+
+    # Expand every date found in the text, not just the first one.
+    result_parts = []
+    pos = 0
+    for match in date_pattern.finditer(text):
+        # Get the three parts of the date string
+        part1_str, part2_str, part3_str = match.groups()
+        p1, p2, p3 = int(part1_str), int(part2_str), int(part3_str)
+
+        # Initialize month, day, and year
+        month, day, year = None, None, None
+
+        # Determine year first based on length (4 digits)
+        if len(part1_str) == 4:
+            year, rest_parts = p1, [p2, p3]
+        elif len(part3_str) == 4:
+            year, rest_parts = p3, [p1, p2]
+        else:
+            # If no 4-digit year, it's ambiguous, assume a 2-digit year.
+            # We'll assume the last part is the year based on common patterns.
+            year = p3
+            # Expand 2-digit year to 4-digit year
+            if year < 100:
+                # Assume years 00-29 are 2000-2029, 30-99 are 1930-1999
+                year = 2000 + year if year < 30 else 1900 + year
+            rest_parts = [p1, p2]
+
+        # From the remaining parts, try to determine day and month
+        if day is None and any(p > 12 and len(str(p)) == 2 for p in rest_parts):
+            # If a two-digit number is > 12, it's a day
+            day_candidate = next((p for p in rest_parts if p > 12), None)
+            if day_candidate:
+                day = day_candidate
+                rest_parts.remove(day_candidate)
+                month = rest_parts[0]
+
+        # Fallback to date_format if day/month are still ambiguous
+        if day is None or month is None:
+            if date_format.lower() == "mdy":
+                month, day = rest_parts[0], rest_parts[1]
+            else:  # default to DD/MM/YY
+                day, month = rest_parts[0], rest_parts[1]
+
+        try:
+            date_obj = date(year, month, day)
+            replacement = pronounce_date(date_obj, full_lang)
+        except (ValueError, IndexError) as e:
+            LOG.warning(f"Could not parse date from '{match.group(0)}': {e}")
+            replacement = match.group(0)
+
+        result_parts.append(text[pos:match.start()])
+        result_parts.append(replacement)
+        pos = match.end()
+
+    result_parts.append(text[pos:])
+    text = "".join(result_parts)
+
+    return text

text2spoken/numbers.py

@@ -0,0 +1,90 @@
+"""Spoken forms for numbers: separators, fractions and digit strings."""
+import logging
+import string
+
+from ovos_number_parser import pronounce_number, pronounce_fraction
+from ovos_number_parser.util import is_numeric
+from unicode_rbnf import FormatPurpose
+
+LOG = logging.getLogger("text2spoken")
+
+
+def _get_number_separators(full_lang: str) -> tuple[str, str]:
+    """
+    Determines decimal and thousands separators based on language.
+    Defaults to '.' decimal and ',' thousands for most languages.
+    Special cases:
+    - 'pt', 'es', 'fr', 'de': ',' decimal and '.' thousands.
+    """
+    lang_code = full_lang.split("-")[0]
+    decimal_separator = '.'
+    thousands_separator = ','
+    if lang_code in ["pt", "es", "fr", "de"]:
+        decimal_separator = ','
+        thousands_separator = '.'
+    return decimal_separator, thousands_separator
+
+def is_fraction(word: str) -> bool:
+    """Checks if a word is a fraction like '3/3'."""
+    if "/" in word:
+        parts = word.split("/")
+        if len(parts) == 2:
+            n1, n2 = parts
+            return n1.isdigit() and n2.isdigit()
+    return False
+
+def _normalize_number_word(word: str, full_lang: str, rbnf_engine) -> str:
+    """
+    Helper function to normalize a single word that is a number, handling
+    decimal and thousands separators based on locale.
+    """
+    cleaned_word = word.rstrip(string.punctuation)
+
+    # Handle fractions like '3/3'
+    if is_fraction(cleaned_word):
+        try:
+            return pronounce_fraction(cleaned_word, full_lang) + word[len(cleaned_word):]
+        except Exception as e:
+            LOG.error(f"ovos-number-parser failed to pronounce fraction: {word} - ({e})")
+            return word
+
+    # Handle numbers with locale-specific separators
+    decimal_separator, thousands_separator = _get_number_separators(full_lang)
+    temp_cleaned_word = cleaned_word
+
+    # Check if the word contains a thousands separator followed by digits and a decimal separator
+    # This is a specific check for formats like '123.456,78'
+    has_thousands_and_decimal = (
+            thousands_separator in temp_cleaned_word and
+            decimal_separator in temp_cleaned_word and
+            temp_cleaned_word.index(thousands_separator) < temp_cleaned_word.index(decimal_separator)
+    )
+
+    if has_thousands_and_decimal:
+        temp_cleaned_word = temp_cleaned_word.replace(thousands_separator, "")
+        temp_cleaned_word = temp_cleaned_word.replace(decimal_separator, ".")
+    elif decimal_separator in temp_cleaned_word and is_numeric(temp_cleaned_word.replace(decimal_separator, ".", 1)):
+        # Handle cases like '1,2' -> '1.2'
+        temp_cleaned_word = temp_cleaned_word.replace(decimal_separator, ".")
+    elif thousands_separator in temp_cleaned_word and is_numeric(temp_cleaned_word.replace(thousands_separator, "", 1)):
+        # Handle cases like '1.234' -> '1234'
+        temp_cleaned_word = temp_cleaned_word.replace(thousands_separator, "")
+
+    # Check if the word is a valid number after processing
+    if is_numeric(temp_cleaned_word):
+        try:
+            num = float(temp_cleaned_word) if "." in temp_cleaned_word else int(temp_cleaned_word)
+            return pronounce_number(num, lang=full_lang) + word[len(cleaned_word):]
+        except Exception as e:
+            LOG.error(f"ovos-number-parser failed to pronounce number: {word} - ({e})")
+            return word
+
+    elif rbnf_engine and cleaned_word.isdigit():
+        try:
+            pronounced_number = rbnf_engine.format_number(cleaned_word, FormatPurpose.CARDINAL).text
+            return pronounced_number + word[len(cleaned_word):]
+        except Exception as e:
+            LOG.error(f"unicode-rbnf failed to pronounce number: {word} - ({e})")
+            return word
+
+    return word

text2spoken/tables.py

@@ -0,0 +1,352 @@
+"""Per-language lookup tables consumed by the normalization pipeline.
+
+Keys are ISO-639 language codes; a locale tag is reduced to its language
+subtag before lookup, so "pt-BR" and "pt-PT" share one table.
+"""
+
+# A dictionary of common contractions and their expanded forms.
+# This list is very comprehensive for English.
+CONTRACTIONS = {
+    "en": {
+        "I'd": "I would",
+        "I'll": "I will",
+        "I'm": "I am",
+        "I've": "I have",
+        "ain't": "is not",
+        "aren't": "are not",
+        "can't": "can not",
+        "could've": "could have",
+        "couldn't": "could not",
+        "didn't": "did not",
+        "doesn't": "does not",
+        "don't": "do not",
+        "gonna": "going to",
+        "gotta": "got to",
+        "hadn't": "had not",
+        "hasn't": "has not",
+        "haven't": "have not",
+        "he'd": "he would",
+        "he'll": "he will",
+        "he's": "he is",
+        "how'd": "how did",
+        "how'll": "how will",
+        "how's": "how is",
+        "isn't": "is not",
+        "it'd": "it would",
+        "it'll": "it will",
+        "it's": "it is",
+        "might've": "might have",
+        "mightn't": "might not",
+        "must've": "must have",
+        "mustn't": "must not",
+        "needn't": "need not",
+        "oughtn't": "ought not",
+        "shan't": "shall not",
+        "she'd": "she would",
+        "she'll": "she will",
+        "she's": "she is",
+        "should've": "should have",
+        "shouldn't": "should not",
+        "somebody's": "somebody is",
+        "someone'd": "someone would",
+        "someone'll": "someone will",
+        "someone's": "someone is",
+        "that'd": "that would",
+        "that'll": "that will",
+        "that's": "that is",
+        "there'd": "there would",
+        "there're": "there are",
+        "there's": "there is",
+        "they'd": "they would",
+        "they'll": "they will",
+        "they're": "they are",
+        "they've": "they have",
+        "wasn't": "was not",
+        "we'd": "we would",
+        "we'll": "we will",
+        "we're": "we are",
+        "we've": "we have",
+        "weren't": "were not",
+        "what'd": "what did",
+        "what'll": "what will",
+        "what're": "what are",
+        "what's": "what is",
+        "what've": "what have",
+        "whats": "what is",
+        "when'd": "when did",
+        "when's": "when is",
+        "where'd": "where did",
+        "where's": "where is",
+        "where've": "where have",
+        "who'd": "who would",
+        "who'd've": "who would have",
+        "who'll": "who will",
+        "who're": "who are",
+        "who's": "who is",
+        "who've": "who have",
+        "why'd": "why did",
+        "why're": "why are",
+        "why's": "why is",
+        "won't": "will not",
+        "won't've": "will not have",
+        "would've": "would have",
+        "wouldn't": "would not",
+        "wouldn't've": "would not have",
+        "y'ain't": "you are not",
+        "y'aint": "you are not",
+        "y'all": "you all",
+        "ya'll": "you all",
+        "you'd": "you would",
+        "you'd've": "you would have",
+        "you'll": "you will",
+        "you're": "you are",
+        "you've": "you have",
+        "I'm'a": "I am going to",
+        "I'm'o": "I am going to",
+        "I'll've": "I will have",
+        "I'd've": "I would have",
+        "Whatcha": "What are you",
+        "amn't": "am not",
+        "'cause": "because",
+        "can't've": "cannot have",
+        "couldn't've": "could not have",
+        "daren't": "dare not",
+        "daresn't": "dare not",
+        "dasn't": "dare not",
+        "everyone's": "everyone is",
+        "gimme": "give me",
+        "gon't": "go not",
+        "hadn't've": "had not have",
+        "he've": "he would have",
+        "he'll've": "he will have",
+        "he'd've": "he would have",
+        "here's": "here is",
+        "how're": "how are",
+        "how'd'y": "how do you do",
+        "howd'y": "how do you do",
+        "howdy": "how do you do",
+        "'tis": "it is",
+        "'twas": "it was",
+        "it'll've": "it will have",
+        "it'd've": "it would have",
+        "kinda": "kind of",
+        "let's": "let us",
+        "ma'am": "madam",
+        "may've": "may have",
+        "mayn't": "may not",
+        "mightn't've": "might not have",
+        "mustn't've": "must not have",
+        "needn't've": "need not have",
+        "ol'": "old",
+        "oughtn't've": "ought not have",
+        "sha'n't": "shall not",
+        "shan't": "shall not",
+        "shalln't": "shall not",
+        "shan't've": "shall not have",
+        "she'd've": "she would have",
+        "shouldn't've": "should not have",
+        "so've": "so have",
+        "so's": "so is",
+        "something's": "something is",
+        "that're": "that are",
+        "that'd've": "that would have",
+        "there'll": "there will",
+        "there'd've": "there would have",
+        "these're": "these are",
+        "they'll've": "they will have",
+        "they'd've": "they would have",
+        "this's": "this is",
+        "this'll": "this will",
+        "this'd": "this would",
+        "those're": "those are",
+        "to've": "to have",
+        "wanna": "want to",
+        "we'll've": "we will have",
+        "we'd've": "we would have",
+        "what'll've": "what will have",
+        "when've": "when have",
+        "where're": "where are",
+        "which's": "which is",
+        "who'll've": "who will have",
+        "why've": "why have",
+        "will've": "will have",
+        "y'all're": "you all are",
+        "y'all've": "you all have",
+        "y'all'd": "you all would",
+        "y'all'd've": "you all would have",
+        "you'll've": "you will have"
+    }
+}
+
+# Dictionaries for titles, units, and their full word equivalents.
+TITLES = {
+    "en": {
+        "Dr.": "Doctor",
+        "Mr.": "Mister",
+        "Prof.": "Professor"
+    },
+    "ca": {
+        "Dr.": "Doctor",
+        "Sr.": "Senyor",
+        "Sra.": "Senyora",
+        "Prof.": "Professor"
+    },
+    "es": {
+        "Dr.": "Doctor",
+        "Sr.": "Señor",
+        "Sra.": "Señora",
+        "Prof.": "Profesor",
+        "D.": "Don",
+        "Dña.": "Doña"
+    },
+    "pt": {
+        "Dr.": "Doutor",
+        "Sr.": "Senhor",
+        "Sra.": "Senhora",
+        "Prof.": "Professor",
+        "Drª.": "Doutora",
+        "Eng.": "Engenheiro",
+        "D.": "Dom",
+        "Dª": "Dona"
+    },
+    "gl": {
+        "Dr.": "Doutor",
+        "Sr.": "Señor",
+        "Sra.": "Señora",
+        "Prof.": "Profesor",
+        "Srta.": "Señorita"
+    },
+    "fr": {
+        "Dr.": "Docteur",
+        "M.": "Monsieur",
+        "Mme": "Madame",
+        "Mlle": "Mademoiselle",
+        "Prof.": "Professeur",
+        "Pr.": "Professeur"
+    },
+    "it": {
+        "Dr.": "Dottore",
+        "Sig.": "Signore",
+        "Sig.ra": "Signora",
+        "Prof.": "Professore",
+        "Dott.ssa": "Dottoressa",
+        "Sig.na": "Signorina"
+    },
+    "nl": {
+        "Dr.": "Dokter",
+        "Dhr.": "De Heer",
+        "Mevr.": "Mevrouw",
+        "Prof.": "Professor",
+        "Drs.": "Dokterandus",
+        "Ing.": "Ingenieur"
+    },
+    "de": {
+        "Dr.": "Doktor",
+        "Prof.": "Professor"
+    }
+}
+
+UNITS = {
+    "en": {
+        "€": "euros",
+        "%": "per cent",
+        "°C": "degrees celsius",
+        "°F": "degrees fahrenheit",
+        "°K": "degrees kelvin",
+        "°": "degrees",
+        "$": "dollars",
+        "£": "pounds",
+        "km": "kilometers",
+        "m": "meters",
+        "cm": "centimeters",
+        "mm": "millimeters",
+        "ft": "feet",
+        "in": "inches",
+        "yd": "yards",
+        "mi": "miles",
+        "kg": "kilograms",
+        "g": "grams",
+        "lb": "pounds",
+        "oz": "ounces",
+        "L": "liters",
+        "mL": "milliliters",
+        "gal": "gallons",
+        "qt": "quarts",
+        "pt": "pints",
+        "hr": "hours",
+        "min": "minutes",
+        "s": "seconds"
+    },
+    "pt": {
+        "€": "euros",
+        "%": "por cento",
+        "°C": "graus celsius",
+        "°F": "graus fahrenheit",
+        "°K": "graus kelvin",
+        "°": "graus",
+        "$": "dólares",
+        "£": "libras",
+        "km": "quilômetros",
+        "m": "metros",
+        "cm": "centímetros",
+        "mm": "milímetros",
+        "kg": "quilogramas",
+        "g": "gramas",
+        "L": "litros",
+        "mL": "mililitros",
+        "h": "horas",
+        "min": "minutos",
+        "s": "segundos"
+    },
+    "es": {
+        "€": "euros",
+        "%": "por ciento",
+        "°C": "grados celsius",
+        "°F": "grados fahrenheit",
+        "°K": "grados kelvin",
+        "°": "grados",
+        "$": "dólares",
+        "£": "libras",
+        "km": "kilómetros",
+        "m": "metros",
+        "cm": "centímetros",
+        "kg": "kilogramos",
+        "g": "gramos",
+        "L": "litros",
+        "mL": "millilitros"
+    },
+    "fr": {
+        "€": "euros",
+        "%": "pour cent",
+        "°C": "degrés celsius",
+        "°F": "degrés fahrenheit",
+        "°K": "degrés kelvin",
+        "°": "degrés",
+        "$": "dollars",
+        "£": "livres",
+        "km": "kilomètres",
+        "m": "mètres",
+        "cm": "centimètres",
+        "kg": "kilogrammes",
+        "g": "grammes",
+        "L": "litres",
+        "mL": "millilitres"
+    },
+    "de": {
+        "€": "Euro",
+        "%": "Prozent",
+        "°C": "Grad Celsius",
+        "°F": "Grad Fahrenheit",
+        "°K": "Grad Kelvin",
+        "°": "Grad",
+        "$": "Dollar",
+        "£": "Pfund",
+        "km": "Kilometer",
+        "m": "Meter",
+        "cm": "Zentimeter",
+        "kg": "Kilogramm",
+        "g": "Gramm",
+        "L": "Liter",
+        "mL": "Milliliter"
+    }
+}

text2spoken/text.py

@@ -0,0 +1,156 @@
+"""The text normalization pipeline: raw written text to speakable words."""
+import logging
+import re
+
+from unicode_rbnf import RbnfEngine
+
+from text2spoken.datetimes import _normalize_dates_and_times
+from text2spoken.numbers import _normalize_number_word
+from text2spoken.tables import CONTRACTIONS, TITLES
+from text2spoken.units import _normalize_units
+
+LOG = logging.getLogger("text2spoken")
+
+def _normalize_word_hyphen_digit(text: str) -> str:
+    """
+    Helper function to normalize words attached to digits with a hyphen,
+    such as 'sub-23' -> 'sub 23'.
+
+    A hyphen (or en-dash/em-dash) directly between two digit runs, such as
+    '3-2' or '1139-1185', is left untouched: that is a score or a range,
+    not a word glued to a digit, and it is up to the phonemizer to read it
+    as such.
+    """
+    # Regex to find a word (\w+) followed by a hyphen/en-dash/em-dash and a
+    # digit (\d+).
+    pattern = re.compile(r"(\w+)[-–—](\d+)")
+
+    def _replace(match: "re.Match") -> str:
+        word_part = match.group(1)
+        if word_part.isdigit():
+            # digit-dash-digit is a range or score (e.g. '3-2', '1139-1185')
+            return match.group(0)
+        return f"{word_part} {match.group(2)}"
+
+    text = pattern.sub(_replace, text)
+    return text
+
+def _normalize_word(word: str, full_lang: str, rbnf_engine) -> str:
+    """
+    Helper function to normalize a single word.
+    """
+    lang_code = full_lang.split("-")[0]
+    word = word.replace("’", "'")
+
+    if word in CONTRACTIONS.get(lang_code, {}):
+        return CONTRACTIONS[lang_code][word]
+
+    if word in TITLES.get(lang_code, {}):
+        return TITLES[lang_code][word]
+
+    # Delegate number parsing to the new helper function
+    normalized_number = _normalize_number_word(word, full_lang, rbnf_engine)
+    if normalized_number != word:
+        return normalized_number
+
+    return word
+
+def expand_word(word: str, lang: str) -> str:
+    """Expand one word: a contraction, a title, a fraction or a number."""
+    rbnf_engine = None
+    try:
+        rbnf_engine = RbnfEngine.for_language(lang.split("-")[0])
+    except (ValueError, KeyError) as e:
+        LOG.debug(f"RBNF engine not available for language '{lang}': {e}")
+    return _normalize_word(word, lang, rbnf_engine)
+
+def normalize(text: str, lang: str) -> str:
+    """
+    Normalize a text string for speech by expanding contractions and titles and converting dates, times, numbers, units, and fractions into spoken forms.
+    
+    Parameters:
+        text (str): Input text to normalize.
+        lang (str): Locale language tag (e.g., "en", "en-US") that determines language-specific rules.
+    
+    Returns:
+        str: The normalized text with expanded contractions and titles and with dates, times, numbers, units, and fractions converted to their spoken equivalents.
+    
+    Notes:
+        Date and time normalization is attempted for the locale and is silently skipped if unsupported. Numeric formatting may use a locale RBNF engine when available; otherwise a fallback is used.
+    """
+    full_lang = lang
+    lang_code = full_lang.split("-")[0]
+    dialog = text
+
+    # Step 1: Handle dates and times with ovos-date-parser
+    date_format = "MDY" if full_lang.lower() == "en-us" else "DMY"
+    try:
+        dialog = _normalize_dates_and_times(dialog, full_lang, date_format)
+    except:  # throws exception on unsupported langs
+        pass
+
+    # Step 2: Normalize words with hyphens and digits
+    dialog = _normalize_word_hyphen_digit(dialog)
+
+    # Step 3: Expand units attached to numbers
+    dialog = _normalize_units(dialog, full_lang)
+
+    # Step 4: Normalize word-by-word
+    words = dialog.split()
+    rbnf_engine = None
+    try:
+        rbnf_engine = RbnfEngine.for_language(lang_code)
+    except (ValueError, KeyError) as e:
+        LOG.debug(f"RBNF engine not available for language '{lang_code}': {e}")
+
+    normalized_words = [_normalize_word(word, full_lang, rbnf_engine) for word in words]
+    dialog = " ".join(normalized_words)
+
+    return dialog
+if __name__ == "__main__":
+    # --- Example usage for demonstration purposes ---
+
+    # General normalization examples
+    print("General English example: " + normalize('I\'m Dr. Prof. 3/3 0.5% of 12345€, 5ft, and 10kg', 'en'))
+    print(
+        f"Word Salad Portuguese (Dr. Prof. 3/3 0,5% de 12345€, 5m, e 10kg): {normalize('Dr. Prof. 3/3 0,5% de 12345€, 5m, e 10kg', 'pt')}")
+    print(
+        f"Word Salad Portuguese (Dr. Prof. 3/3 0.5% de 12345€, 5m, e 10kg): {normalize('Dr. Prof. 3/3 0.5% de 12345€, 5m, e 10kg', 'pt')}")
+
+    # Portuguese examples with comma decimal separator
+    print("\n--- Portuguese Decimal Separator Examples ---")
+    print(
+        f"Original: 'A coima aplicada é de 1,2 milhões de euros.' Normalized: '{normalize('A coima aplicada é de 1,2 milhões de euros.', 'pt')}'")
+    print(
+        f"Original: 'Agora, tem 1,88 metros e muito para contar.' Normalized: '{normalize('Agora, tem 1,88 metros e muito para contar.', 'pt')}'")
+    print(
+        f"Original: 'Ainda temos 1,7 milhões de pobres!' Normalized: '{normalize('Ainda temos 1,7 milhões de pobres!', 'pt')}'")
+    print(f"Original: 'O lucro foi de 123.456,78€.' Normalized: '{normalize('O lucro foi de 123.456,78€.', 'pt')}'")
+    print(f"Normalized: '{normalize('O lucro foi de 123.456,78€.', 'pt-PT')}'")
+
+    # English dates and times
+    print("\n--- English Date & Time Examples ---")
+    print(f"English date (MDY format): {normalize('The date is 08/03/2025', 'en-US')}")
+    print(f"English ambiguous date (MDY assumed): {normalize('The report is due 15/05/2025', 'en-US')}")
+    print(f"English date with dashes: {normalize('The event is on 11-04-2025', 'en-US')}")
+    print(f"English AM/PM time: {normalize('The meeting is at 10am', 'en-US')}")
+    print(f"English military time: {normalize('The party is at 19h30', 'en-US')}")
+    print(f"English month name: {normalize('The report is due 15 May 2025', 'en-US')}")
+
+    # Portuguese dates and times
+    print("\n--- Portuguese Date & Time Examples ---")
+    print(f"Portuguese date (A data é 03/08/2025): {normalize('A data é 03/08/2025', 'pt')}")
+    print(
+        f"Portuguese ambiguous date (O relatório é para 15/05/2025): {normalize('O relatório é para 15/05/2025', 'pt')}")
+    print(
+        f"Portuguese date with dashes (O evento é no dia 25-10-2024): {normalize('O evento é no dia 25-10-2024', 'pt')}")
+    print(f"Portuguese military time (O encontro é às 14h30): {normalize('O encontro é às 14h30', 'pt')}")
+
+    # Other examples
+    print(f"\n--- Other Examples ---")
+    print(f"English fraction: {normalize('The fraction is 1/2', 'en')}")
+    print(f"English plural fraction: {normalize('There are 3/4 of a cup', 'en')}")
+    print(f"Spanish example with units: {normalize('The temperature is 25ºC', 'es')}")
+    print(f"Portuguese with punctuation: {normalize('12345€, 5m e 10kg', 'pt')}")
+    print(
+        f"Portuguese word-digit: {normalize('Esta temporada leva oito jogos ao serviço da equipa sub-23 leonina.', 'pt')}")

text2spoken/units.py

@@ -0,0 +1,98 @@
+"""Expansion of units and ordinal indicators attached to numbers."""
+import logging
+import re
+
+from ovos_number_parser import pronounce_number
+
+from text2spoken.numbers import _get_number_separators
+from text2spoken.tables import UNITS
+
+LOG = logging.getLogger("text2spoken")
+
+def _normalize_units(text: str, full_lang: str) -> str:
+    """
+    Helper function to normalize units attached to numbers.
+    This function handles symbolic and alphanumeric units separately
+    to avoid issues with word boundaries.
+    """
+    # "º" (U+00BA, masculine ordinal indicator, e.g. "1º andar") looks like
+    # "°" (U+00B0, degree sign) but is not the same character. Only treat it
+    # as a degree sign when it is actually used as a temperature unit
+    # (e.g. "20ºC" / "20ºc"), so ordinals are not corrupted into degrees.
+    # Case-insensitive to match the (IGNORECASE) unit regex below.
+    text = re.sub(r"º(?=\s?[CFK]\b)", "°", text, flags=re.IGNORECASE)
+
+    # Any remaining "º" is a genuine ordinal indicator attached to a digit
+    # (e.g. "1º andar", "20º"). normalize() must never leave raw digits in
+    # the output, so expand these as ordinal numbers, falling back to a
+    # plain cardinal (still dropping the "º") if ordinal pronunciation is
+    # unavailable for the language.
+    def _replace_ordinal_indicator(match: "re.Match") -> str:
+        number = int(match.group(1))
+        try:
+            return pronounce_number(number, full_lang, ordinals=True)
+        except Exception as e:
+            LOG.error(f"Failed to pronounce ordinal number: {number}º - ({e})")
+            return pronounce_number(number, full_lang)
+
+    text = re.sub(r"(\d+)º", _replace_ordinal_indicator, text)
+
+    lang_code = full_lang.split("-")[0]
+    if lang_code in UNITS:
+        # Determine number separators for the language
+        decimal_separator, thousands_separator = _get_number_separators(full_lang)
+
+        # Separate units into symbolic and alphanumeric
+        symbolic_units = {k: v for k, v in UNITS[lang_code].items() if not k.isalnum()}
+        alphanumeric_units = {k: v for k, v in UNITS[lang_code].items() if k.isalnum()}
+
+        # Create regex pattern for symbolic units and replace them first
+        sorted_symbolic = sorted(symbolic_units.keys(), key=len, reverse=True)
+        symbolic_pattern_str = "|".join(re.escape(unit) for unit in sorted_symbolic)
+        if symbolic_pattern_str:
+            # Pattern to match numbers with optional thousands and decimal separators
+            number_pattern_str = rf"(\d+[{re.escape(thousands_separator)}]?\d*[{re.escape(decimal_separator)}]?\d*)"
+            symbolic_pattern = re.compile(number_pattern_str + r"\s*(" + symbolic_pattern_str + r")", re.IGNORECASE)
+
+            def replace_symbolic(match):
+                number = match.group(1)
+                # Remove thousands separator and replace decimal separator for parsing
+                if thousands_separator in number and decimal_separator in number:
+                    number = number.replace(thousands_separator, "").replace(decimal_separator, ".")
+                elif decimal_separator != "." and decimal_separator in number:
+                    number = number.replace(decimal_separator, ".")
+                unit_symbol = match.group(2)
+                # The regex is IGNORECASE (e.g. "°c" matches "°C"), so the
+                # matched text may not share the dict key's exact case.
+                unit_word = (symbolic_units.get(unit_symbol)
+                             or symbolic_units.get(unit_symbol.upper())
+                             or symbolic_units.get(unit_symbol.lower()))
+                try:
+                    return f"{pronounce_number(float(number) if '.' in number else int(number), full_lang)} {unit_word}"
+                except Exception as e:
+                    LOG.error(f"Failed to pronounce number with unit: {number}{unit_symbol} - ({e})")
+                    return match.group(0)
+
+            text = symbolic_pattern.sub(replace_symbolic, text)
+
+        # Create regex pattern for alphanumeric units and replace them next
+        sorted_alphanumeric = sorted(alphanumeric_units.keys(), key=len, reverse=True)
+        alphanumeric_pattern_str = "|".join(re.escape(unit) for unit in sorted_alphanumeric)
+        if alphanumeric_pattern_str:
+            number_pattern_str = rf"(\d+[{re.escape(thousands_separator)}]?\d*[{re.escape(decimal_separator)}]?\d*)"
+            alphanumeric_pattern = re.compile(number_pattern_str + r"\s*(" + alphanumeric_pattern_str + r")\b",
+                                              re.IGNORECASE)
+
+            def replace_alphanumeric(match):
+                number = match.group(1)
+                # Remove thousands separator and replace decimal separator for parsing
+                if thousands_separator in number and decimal_separator in number:
+                    number = number.replace(thousands_separator, "").replace(decimal_separator, ".")
+                elif decimal_separator != "." and decimal_separator in number:
+                    number = number.replace(decimal_separator, ".")
+                unit_symbol = match.group(2)
+                unit_word = alphanumeric_units[unit_symbol]
+                return f"{pronounce_number(float(number) if '.' in number else int(number), full_lang)} {unit_word}"
+
+            text = alphanumeric_pattern.sub(replace_alphanumeric, text)
+    return text

text2spoken/version.py

@@ -0,0 +1,10 @@
+# START_VERSION_BLOCK
+VERSION_MAJOR = 0
+VERSION_MINOR = 0
+VERSION_BUILD = 2
+VERSION_ALPHA = 1
+# END_VERSION_BLOCK
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}"
+if VERSION_ALPHA:
+    __version__ += f"a{VERSION_ALPHA}"

text2spoken-0.0.2a1.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: text2spoken
+Version: 0.0.2a1
+Summary: Rewrite written text into the words a voice speaks: numbers, dates, times, units, titles and contractions
+Author-email: JarbasAI <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/TigreGotico/text2spoken
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ovos-number-parser>=0.4.0
+Requires-Dist: ovos-date-parser>=0.6.4a1
+Requires-Dist: unicode_rbnf>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# text2spoken
+
+text2spoken rewrites written text into the words a voice speaks. It expands numbers, dates, times, units, titles and contractions. A phonemizer then reads words, not digits or symbols.
+
+## Quickstart
+
+```bash
+pip install --pre text2spoken
+```
+
+```python
+from text2spoken import normalize
+
+print(normalize("Dr. Smith paid 3/4 of the bill at 25°C.", "en"))
+print(normalize("O Sr. Silva pagou 10kg às 14h30.", "pt-PT"))
+```
+
+```text
+Doctor Smith paid three quarters of the bill at twenty five degrees celsius.
+O Senhor Silva pagou dez quilogramas às catorze e trinta.
+```
+
+## Where this fits
+
+Alone: it turns written text into spoken words, with `from text2spoken import normalize`.
+In the stack: it is the normalisation stage. A frontend or a TTS library calls it before phonemization, and it calls `ovos-number-parser`, `ovos-date-parser` and `unicode_rbnf`.
+Through scriptconv: scriptconv has no `normalize` extra. Install `text2spoken` directly.
+
+## What `normalize` does
+
+`normalize(text, lang)` runs four passes in this order:
+
+1. It expands dates and times, such as `03/08/2025` and `14h30`.
+2. It splits a word from a digit that a hyphen joins, such as `sub-23`. A range such as `3-2` stays as it is.
+3. It expands units and ordinal indicators, such as `10kg`, `25°C` and `1º`.
+4. It reads each word, and expands contractions, titles, fractions and numbers.
+
+Each pass is also a plain function, so a frontend can compose them and add its own rules. See [docs/api.md](docs/api.md).
+
+The language tag selects the rules. The tables use the part before the first hyphen, so `pt-BR` and `pt-PT` share one table. `en-US` reads an ambiguous date as month first, and every other tag reads it as day first.
+
+## Languages
+
+These languages have tables in `text2spoken/tables.py`:
+
+| Table | Languages |
+| --- | --- |
+| `CONTRACTIONS` | en |
+| `TITLES` | ca, de, en, es, fr, gl, it, nl, pt |
+| `UNITS` | de, en, es, fr, pt |
+
+This command prints the same list from the installed package:
+
+```bash
+python -c "from text2spoken import CONTRACTIONS, TITLES, UNITS; [print(sorted(t)) for t in (CONTRACTIONS, TITLES, UNITS)]"
+```
+
+Numbers, dates and times come from `ovos-number-parser` and `ovos-date-parser`, so those packages set their language coverage.
+
+To add a language, add its entries to `text2spoken/tables.py`. A new language needs no code change.
+
+## Behaviour to know
+
+- The library uses no network and loads no model, so it works offline.
+- A language that the parsers do not support keeps its digits. The library logs an error and returns the text.
+- A `text` or `lang` value of the wrong type raises `TypeError` or `AttributeError` from the code that reads it.
+- Importing the library imports `ovos-date-parser`, which sets the import time.
+- `ovos-config`, a dependency of `ovos-date-parser`, creates `~/.config/mycroft` at import.
+
+## Development
+
+```bash
+uv pip install --prerelease=allow -e ".[test]"
+pytest tests
+```
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

text2spoken-0.0.2a1.dist-info/RECORD

@@ -0,0 +1,12 @@
+text2spoken/__init__.py,sha256=tGUnKx7mLTS83PXhizo-eJ7MYMWvkibwZIMFrod8UsQ,1469
+text2spoken/datetimes.py,sha256=ZU_OhMW5LgmeiFmOWnCIFp8BIsUdQD2albzHT9xux-8,4392
+text2spoken/numbers.py,sha256=Cz_hsqB9lL9zv3nuDkepamWHeRFJdrrl_g96rOgSMDY,3782
+text2spoken/tables.py,sha256=RJPI30KFfkyUEzmRlCbCgezWPv5bYlSxlS1Lt2kj6gk,9725
+text2spoken/text.py,sha256=zpb4B9KgBaJAaw6AigdDbv6-HGiJyMsErjffm0WlOw0,7064
+text2spoken/units.py,sha256=F-Sbz2DJZecR6_PT-vZ9klCS5U3noagOpXXaJywe2vg,5429
+text2spoken/version.py,sha256=bnn56eZMSfhGARN80wnH9MfTv5i5iSuTTHzeoeoQDb8,237
+text2spoken-0.0.2a1.dist-info/licenses/LICENSE,sha256=JBPAOkIXtKdcPVf305lJfqrNVYQ0beL0DenojOGR0EI,11346
+text2spoken-0.0.2a1.dist-info/METADATA,sha256=ZBa_OVGOlZt2uxOuFB5O1p0V1Ab3BtCqMGM5FHcUeWU,3795
+text2spoken-0.0.2a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+text2spoken-0.0.2a1.dist-info/top_level.txt,sha256=XqjmOV2yDxubrqC_aw5JrPslVXaKYipolDOxUBgnmXQ,12
+text2spoken-0.0.2a1.dist-info/RECORD,,

text2spoken-0.0.2a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

text2spoken-0.0.2a1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 TigreGotico Lda
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

text2spoken-0.0.2a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+text2spoken