Skip to content

Transliteration & parsing

These methods convert text between scripts, detect look-alike strings, and parse locale-formatted numbers, money, and dates back into values.

Method Use it for
transliterate(text, id) Run any ICU transform (script conversion, decomposition)
romanize(text) The common "to ASCII Latin" case — slugs, search keys
confusable(a, b) Are these two strings visually confusable?
suspicious(text) Is this single string spoof-prone (mixed-script)?
parse_number / parse_money / parse_date / parse_moment The inverse of the formatters

These methods use ICU transforms, spoof checks, and parsers.

Transliterate & romanize

transliterate(text, id) runs any ICU transform. The id is a transform specification — a source/target pair, optionally chained with ;:

id Effect
Greek-Latin Greek script → Latin
Any-Latin any script → Latin (best-effort)
Latin-ASCII strip Latin diacritics to plain ASCII
Any-Latin; Latin-ASCII the chain most slugs want
Any-Hangul, Cyrillic-Latin, Han-Latin, … other script pairs

romanize(text) is the pre-chained common case (Any-Latin; Latin-ASCII) — to Latin, then stripped to ASCII — ideal for slugs and search keys.

c = Cosmo("en")
c.romanize("Москва")                                 # "Moskva"
c.transliterate("Λάμδα", "Greek-Latin")              # "Lámda"
c.transliterate("Łódź café", "Any-Latin; Latin-ASCII") # "Lodz cafe"

An unknown transform id throws. The full list of ids available on your runtime comes from supported_values("transliterator") — the one supported_values key beyond the standard six.

Spoof detection

confusable(a, b) asks whether two strings are visually confusable (e.g. a Cyrillic look-alike of a Latin brand). suspicious(text) flags a single string as spoof-prone — typically because it mixes scripts that shouldn't appear together.

Backed by UTS #39

Both checks implement Unicode Technical Standard #39, Unicode Security Mechanisms — the standard that defines the confusable-character data and mixed-script detection rules — through ICU's SpoofChecker.

c = Cosmo("en")
c.confusable("paypal", "раураl")     # True
c.confusable("hello", "world")       # False
c.suspicious("pаypal")               # True
c.suspicious("paypal")               # False

Use these to defend account names, domains, and brand mentions against homograph attacks — suspicious() on signup to reject mixed-script usernames, confusable() to flag a new name that mimics an existing one.

Parsing (inverse formatters)

Intl can only format, never parse — but ICU's parsers are available in the other this library. Each reads the kind of text produced by its corresponding formatter:

Parser Inverts Returns
parse_number(text) number() a float
parse_money(text) money() amount and currency
parse_date(text, width?) date() a native date (width defaults to short)
parse_moment(text, pattern) format_moment() a native date from a raw pattern
Cosmo("de").parse_number("1.234,56")             # 1234.56  (German grouping)
Cosmo("en").parse_number("1,234.56")             # 1234.56
Cosmo("en_US").parse_money("$12.30")             # {"amount": 12.3, "currency": "USD"}

utc = Cosmo("en_US", {"timeZone": "UTC"})
utc.parse_date("February 2, 2020", "long")       # datetime
utc.parse_moment("2020-02-02", "yyyy-MM-dd")     # datetime

A few things worth knowing:

  • The locale matters — parse_number("1.234,56") reads 1234.56 in de but would read 1.234 in en. Parse in the same locale you formatted (or the user's input locale).
  • parse_date()'s width must match how the text was produced — a "long" string won't parse with the short skeleton. Set a timeZone modifier so the resulting moment is anchored, not shifted by the runtime zone.
  • parse_money() returns the amount and the recognised currency in a dictionary.- Text that doesn't parse throws rather than returning 0 — so you can reliably distinguish a real "0" from unparseable input. Wrap user input in a try/catch.

Practical examples

A URL slug generator. Romanize to ASCII, lower-case, then squeeze non-alphanumerics to hyphens:

import re
def slug(c, title):
    ascii_text = c.lower(c.romanize(title))
    return re.sub(r"[^a-z0-9]+", "-", ascii_text).strip("-")

slug(Cosmo("en"), "Café Déjà Vu")   # "cafe-deja-vu"
slug(Cosmo("en"), "Москва 2024")    # "moskva-2024"

Safely importing a user-entered amount. Parse in the user's locale and treat a throw as "invalid", not zero:

def read_amount(c, text):
    try:
        return c.parse_money(text)          # {"amount": …, "currency": …}
    except Exception:
        return None                         # genuinely unparseable

read_amount(Cosmo("en_US"), "$1,299.00")    # {"amount": 1299.0, "currency": "USD"}
read_amount(Cosmo("en_US"), "n/a")          # None