python-intl

A small library using PyICU to provide a Python API similar to what the Intl JavaScript API provides. It is not meant to fully behave the same, but instead be close enough so the "same" code works on JavaScript and Python, with similar results.

Status: This is very much work in progress.

Note: There are a lot of tests running the Python implementation against the JavaScript one and comparing the results. In general things should be pretty stable there. Still there are some cases with known differences. Also note that results depend on the ICU version you have installed on your machine.

General notes about the Python adaption

All names will be using the Python style rules. This means instead of formatToParts a method will be called format_to_parts. Also a dictionary key like dayPeriod will be named day_period. Python uses snake case, let's stick to this.

Instead of passing around undefined objects like in JavaScript we want to use well defined and typed dataclasses. This for example is true for the Intl.DateTimeFormat format options, you can use DateTimeFormatOptions as a clean representation of those. Using a dictionary (which behaves the most like those JavaScript objects) is still fine and will automatically converted, as seen in the examples here.

Many objects like for example the DateTimeFormatOptions provide methods to convert their Python representation to a JavaScript compatible JSON format by returning a dict using the JavaScript naming. You can use the to_json method for this.

For example:

import python_intl as Intl

Intl.DateTimeFormatOptions(time_zone_name="short_offset").to_json()
# Will return: {'timeZoneName': 'shortOffset'}

Available Intl classes

Intl.Locale

Example usage

import datetime as dt
import python_intl as Intl

locale = Intl.Locale("de-DE")

Compatibility

Locale currently does not support any methods or options. It is mainly there to allow using the locale class instead of a string with the other classes. There will be more later.

Intl.NumberFormat

Example usage

import python_intl as Intl

# Format liters
number = 1234.567
formatter = Intl.NumberFormat("de-DE", {"style": "unit", "unit": "liter"})
formatter.format(number)
# Result = "1.234,567 l"

# Format euros
number = 1234.567
formatter = Intl.NumberFormat("de-DE", {"style": "currency", "currency": "EUR"})
formatter.format(number)
# Result = "1.234,57 €"
# Note: Result will be automatically rounded to two decimal places, as EUR defines.

Compatibility

Intl.DateTimeFormat

Example usage

import datetime as dt
import python_intl as Intl

# Format a datetime
datetime = dt.datetime(2026, 8, 15)
formatter = Intl.DateTimeFormat("de-DE", {"year": "numeric", "month": "2-digit", "day": "2-digit"})
formatter.format(datetime)
# Result = "15.08.2026"

# Format a datetime range
datetime_till = dt.datetime(2026, 9, 7)
formatter.format_range(datetime, datetime_till)
# Result = "15.08. – 07.09.2026"

Compatibility

Intl.Collator

Example usage

import python_intl as Intl

collator = Intl.Collator("de-DE", {"numeric": True})
collator.compare("10", "9")
# Result = 1, which means 9 comes before 10

# You can also use sorted, although this is not available in JavaScript
collator.sorted(["10", "9"])
# Result = ['9', '10']

Compatibility

Note: Not all options are currently supported.

Additional methods

• Collator.sorted: Somewhat like sorted, but uses the collator for comparison. If you want to sort complex datastructures you can provide a key parameter (like with sorted) to get a comparable string value (for example by returning an attribute).

Installation

Be sure to be able to install PyICU, see the installation docs there: https://gitlab.pyicu.org/main/pyicu#installing-pyicu

Hint: I mainly did run into issues with pkg-config not finding the ICU library, setting PKG_CONFIG_PATH accordingly helps most of the time I guess. See .envrc for how to set this up correctly on nix based systems.

When this is done you should be able to install python-intl using any package manager, like pip install python-intl or uv add python-intl.

Contributing

If you want to contribute to this project, feel free to just fork the project, create a dev branch in your fork and then create a pull request (PR). If you are unsure about whether your changes really suits the project please create an issue first, to talk about this.

Please do not contribute AI generated code unless we explicitly talked about this and agreed upon doing so first. In general I do not want AI contributions.