feat: Add global locale support for number parsing

Add locale parameter to top-level API functions to support
locale-specific number formats using Babel's CLDR data.

- Add locale_number_parser module with Babel-based parsing
- Add locale_context module for thread-safe locale management
- Update try_float() to respect locale context
- Add locale parameter to allotrope_from_io/file functions
- Add babel >= 2.9.0 dependency
- Add comprehensive tests for locale parsing and context

This enables parsing numbers in different locales (e.g., German
"1.234,56" vs US "1,234.56") by passing locale="de_DE" to the
top-level API functions.

Co-Authored-By: Claude Opus 4.1 <noreply@anthropic.com>

Author: nathan-stender

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this packages will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Global locale support for number parsing - Add `locale` parameter to top-level API functions to support locale-specific number formats (e.g., German "1.234,56" vs US "1,234.56")
+
 ## [0.1.116] - 2026-04-01
 
 ### Added

pyproject.toml

@@ -47,6 +47,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "babel >= 2.9.0",
   "cattrs >= 23.2.0",
   "chardet >= 5.2.0",
   "defusedxml >= 0.7.1",

src/allotropy/parsers/utils/locale_context.py

@@ -0,0 +1,40 @@
+"""Context management for locale-aware number parsing.
+
+This module provides utilities to set and manage the current locale context
+for number parsing throughout the parsing pipeline.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from allotropy.parsers.utils.values import _current_locale
+
+
+@contextmanager
+def set_locale_context(locale: str | None) -> Iterator[None]:
+    """Context manager to set the locale for number parsing.
+
+    Args:
+        locale: The locale string (e.g., "en_US", "de_DE", "fr_FR") or None for default
+
+    Example:
+        >>> with set_locale_context("de_DE"):
+        ...     # All try_float() calls within this context will use German locale
+        ...     value = try_float("1.234,56", "value")  # Parses as 1234.56
+    """
+    token = _current_locale.set(locale)
+    try:
+        yield
+    finally:
+        _current_locale.reset(token)
+
+
+def get_current_locale() -> str | None:
+    """Get the currently set locale for number parsing.
+
+    Returns:
+        The current locale string or None if not set
+    """
+    return _current_locale.get()

src/allotropy/parsers/utils/locale_number_parser.py

@@ -0,0 +1,282 @@
+"""Locale-aware number parsing utilities.
+
+This module provides locale-aware number parsing based on Babel's CLDR data.
+It allows parsing numbers with locale-specific decimal and grouping separators.
+
+Example:
+    >>> parse_number_with_locale("1.234,56", "de_DE")
+    "1234.56"
+    >>> parse_number_with_locale("1,234.56", "en_US")
+    "1234.56"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+import logging
+import math
+import re
+
+from babel.core import Locale, UnknownLocaleError
+from babel.numbers import (
+    get_decimal_symbol,
+    get_group_symbol,
+    NumberFormatError,
+    parse_decimal,
+)
+
+from allotropy.exceptions import AllotropeConversionError
+
+logger = logging.getLogger(__name__)
+
+# Default locale for number parsing (US English)
+DEFAULT_LOCALE = "en_US"
+
+
+@dataclass(frozen=True)
+class NumberFormat:
+    """Format used to parse numbers for a locale.
+
+    Attributes:
+        group_delimiter: The symbol used as the group separator (ex. "," in 1,234.56)
+        decimal_delimiter: The symbol used as the decimal point (ex. "." in 1,234.56)
+    """
+
+    group_delimiter: str
+    decimal_delimiter: str
+
+
+# Alternative group delimiters that some locales support
+GROUP_DELIMITER_ALTERNATIVES = {
+    "\xa0": " ",  # Non-breaking space → regular space
+    "\u202f": " ",  # Narrow no-break space → regular space
+    "'": "'",  # Different apostrophe encodings
+}
+
+
+class _NumberFormatBuilder:
+    """Builder for locale-specific number formats."""
+
+    locale_str: str
+    locale: Locale
+
+    def __init__(self, locale: str) -> None:
+        """Initialize the builder.
+
+        Args:
+            locale: The locale string (e.g., "en_US", "de_DE", "fr_FR")
+
+        Raises:
+            AllotropeConversionError: If locale is invalid
+        """
+        locale = locale.replace("-", "_")
+        try:
+            self.locale = Locale.parse(locale)
+        except UnknownLocaleError:
+            # Try with just the language code (e.g., "es" from "es_LA")
+            locale = locale[: locale.index("_")] if "_" in locale else locale
+            try:
+                self.locale = Locale.parse(locale)
+            except UnknownLocaleError as e:
+                msg = f"Unsupported locale: {locale}"
+                raise AllotropeConversionError(msg) from e
+        self.locale_str = locale
+
+    def build(self) -> NumberFormat:
+        """Build a NumberFormat for this locale."""
+        return NumberFormat(
+            group_delimiter=get_group_symbol(self.locale_str),
+            decimal_delimiter=get_decimal_symbol(self.locale_str),
+        )
+
+
+# Cache for number formats to avoid repeated Babel lookups
+_NUMBER_FORMAT_CACHE: dict[str, NumberFormat] = {}
+
+
+def get_number_format(locale: str = DEFAULT_LOCALE) -> NumberFormat:
+    """Get the number format for a locale.
+
+    Args:
+        locale: The locale string (e.g., "en_US", "de_DE")
+
+    Returns:
+        NumberFormat for the locale
+    """
+    if locale not in _NUMBER_FORMAT_CACHE:
+        try:
+            builder = _NumberFormatBuilder(locale)
+            _NUMBER_FORMAT_CACHE[locale] = builder.build()
+        except AllotropeConversionError:
+            logger.warning(
+                f"Unsupported locale {locale}, falling back to {DEFAULT_LOCALE}"
+            )
+            if DEFAULT_LOCALE not in _NUMBER_FORMAT_CACHE:
+                _NUMBER_FORMAT_CACHE[DEFAULT_LOCALE] = _NumberFormatBuilder(
+                    DEFAULT_LOCALE
+                ).build()
+            return _NUMBER_FORMAT_CACHE[DEFAULT_LOCALE]
+    return _NUMBER_FORMAT_CACHE[locale]
+
+
+def parse_number_with_locale(number_str: str, locale: str = DEFAULT_LOCALE) -> str:
+    """Parse a locale-formatted number string and return a standard format.
+
+    Converts a number with locale-specific separators to a standard format
+    (period decimal separator, no group separators).
+
+    Args:
+        number_str: The number string to parse (e.g., "1.234,56" in de_DE)
+        locale: The locale to use for parsing (e.g., "de_DE")
+
+    Returns:
+        The number in standard format (e.g., "1234.56")
+
+    Raises:
+        AllotropeConversionError: If the number cannot be parsed
+    """
+    if not number_str or number_str.strip() == "":
+        msg = "Cannot parse empty string as number"
+        raise AllotropeConversionError(msg)
+
+    number_str = number_str.strip()
+
+    # Handle special values (NaN, infinity)
+    special_value = _is_nan_or_inf(number_str)
+    if special_value is not False:
+        # Normalize to Python's standard string representation
+        return str(special_value).lower()
+
+    try:
+        number_format = get_number_format(locale)
+        sanitized = _sanitize_number_to_parse(number_str, number_format)
+
+        # Parse with Babel
+        if "e" in sanitized.lower():
+            # Scientific notation
+            result = _parse_scientific_notation(sanitized, locale, number_format)
+        else:
+            # Standard notation
+            result = _parse_standard_notation(sanitized, locale, number_format)
+
+        # Convert Decimal to string, preserving precision
+        return str(result)
+    except (NumberFormatError, ValueError, AllotropeConversionError) as e:
+        msg = f"Cannot parse '{number_str}' as number for locale {locale}: {e}"
+        raise AllotropeConversionError(msg) from e
+
+
+def _sanitize_number_to_parse(number_str: str, number_format: NumberFormat) -> str:
+    """Sanitize number string for parsing."""
+    # Convert alternative group delimiters
+    sanitized = _convert_group_delimiters(number_str, number_format)
+
+    # Remove underscores (Python numeric literal support)
+    if "__" in sanitized:
+        msg = f"Invalid number format: {number_str}"
+        raise AllotropeConversionError(msg)
+    sanitized = sanitized.replace("_", "")
+
+    return sanitized.lower()
+
+
+def _convert_group_delimiters(number_str: str, number_format: NumberFormat) -> str:
+    """Convert alternative group delimiters to standard ones."""
+    if number_format.group_delimiter in GROUP_DELIMITER_ALTERNATIVES:
+        alternative = GROUP_DELIMITER_ALTERNATIVES[number_format.group_delimiter]
+        return number_str.replace(alternative, number_format.group_delimiter)
+    return number_str
+
+
+def _is_nan_or_inf(number_str: str) -> bool | float:
+    """Check if string represents NaN or infinity.
+
+    Returns:
+        False if not NaN/inf, otherwise returns the normalized float value
+    """
+    try:
+        value = float(number_str)
+        if math.isnan(value) or math.isinf(value):
+            return value
+        return False
+    except ValueError:
+        return False
+
+
+def _parse_scientific_notation(
+    number_str: str, locale: str, number_format: NumberFormat
+) -> Decimal:
+    """Parse number in scientific notation."""
+    before_e, after_e = number_str.split("e", 1)
+
+    # Validate exponent
+    if not re.match(r"^[+-]?\d+$", after_e):
+        msg = f"Invalid scientific notation: {number_str}"
+        raise AllotropeConversionError(msg)
+
+    # Parse mantissa
+    parse_decimal(string=before_e, locale=locale, strict=True)
+
+    # Remove group delimiter for Babel (it doesn't support groups in scientific notation)
+    sanitized = before_e.replace(number_format.group_delimiter, "") + "e" + after_e
+    return parse_decimal(string=sanitized, locale=locale, strict=True)
+
+
+def _parse_standard_notation(
+    number_str: str, locale: str, number_format: NumberFormat
+) -> Decimal:
+    """Parse number in standard notation."""
+    # Extract parts
+    maybe_sign, before_decimal, after_decimal = _try_match_number(
+        number_str, number_format, locale
+    )
+
+    # Remove leading/trailing zeros
+    before_decimal = before_decimal.lstrip("0") if before_decimal else ""
+    if after_decimal:
+        after_decimal = after_decimal.rstrip("0").rstrip(
+            number_format.decimal_delimiter
+        )
+
+    # Reconstruct number
+    number = before_decimal + after_decimal
+
+    # Add leading zero if starts with decimal
+    if number and number[0] == number_format.decimal_delimiter:
+        number = "0" + number
+
+    # Handle empty string (was all zeros)
+    if not number:
+        number = "0"
+
+    # Add sign
+    if maybe_sign == "-":
+        number = "-" + number
+
+    return parse_decimal(string=number, locale=locale, strict=True)
+
+
+def _try_match_number(
+    number_str: str, number_format: NumberFormat, locale: str
+) -> tuple[str, str, str]:
+    """Match number string and extract parts."""
+    # Match optional sign
+    sign_group = "([-+]?)"
+
+    # Match digits and group delimiters before decimal
+    before_decimal_group = f"([\\d{number_format.group_delimiter}]*)?"
+
+    # Match decimal and digits after
+    after_decimal_group = (
+        f"([{number_format.decimal_delimiter}{number_format.group_delimiter}\\d]*)?"
+    )
+
+    pattern = f"^{sign_group}{before_decimal_group}{after_decimal_group}$"
+    match = re.match(pattern, number_str)
+
+    if not match:
+        msg = f"Invalid number format for locale {locale}: {number_str}"
+        raise AllotropeConversionError(msg)
+
+    return match.group(1), match.group(2) or "", match.group(3) or ""

src/allotropy/parsers/utils/values.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from contextvars import ContextVar
 import math
 import re
 from typing import Any, TypeVar
@@ -17,6 +18,9 @@
 
 PrimitiveValue = str | int | float
 
+# Context variable to store the current locale for number parsing
+_current_locale: ContextVar[str | None] = ContextVar("current_locale", default=None)
+
 
 def str_to_bool(value: str) -> bool:
     return value.lower() in ("yes", "y", "true", "t", "1")
@@ -49,6 +53,21 @@ def try_int_or_none(value: str | None) -> int | None:
 def _try_float(value: str | float | None) -> float:
     if isinstance(value, float):
         return value
+
+    # Check if locale-aware parsing is enabled
+    locale = _current_locale.get()
+    if locale:
+        from allotropy.parsers.utils.locale_number_parser import (
+            parse_number_with_locale,
+        )
+
+        try:
+            return float(parse_number_with_locale(str(value), locale))
+        except AllotropeConversionError:
+            # Fall back to default parsing if locale parsing fails
+            pass
+
+    # Default parsing: treat comma as decimal separator (European format)
     # NOTE: this will convert a string with commas for thousands into a decimal, potentially introducing
     # an unexpected error, e.g. one thousand represented as 1,000 would get converted to 1.0
     # However, numbers are not usually represented like this in scientific output (we have no example of it)