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")reads1234.56indebut would read1.234inen. Parse in the same locale you formatted (or the user's input locale). parse_date()'swidthmust match how the text was produced — a"long"string won't parse with theshortskeleton. Set atimeZonemodifier 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: