Thank you so much for the speedy fix!
woylie
kip
ex_cldr Core Team
Todays launch is localize_person_names that implements person name formatting based upon the CLDR Person Name specification.
Person names are simultaneously one of the most important topics for good user engagement and one of the most under-satisfied capabilities in modern software.
In 2010, Patrick McKenzie published Falsehoods Programmers Believe About Names, a list of 40 assumptions about personal names that programmers routinely make and that are routinely wrong. Fifteen years later, the article is still being translated, cited, and re-linked — because its examples remain live bugs in production systems everywhere. localize_person_names can be used to avoid nearly all of these pitfalls.
Naming mistakes can even lead to offensive or abuse material and in rare situations even legal issues.
The blog article 多文化環境におけるパーソナルネームの扱い方 (Handling personal names in multicultural environments) documents a specific Japanese failure mode: using both family-name and given-name initials together.
-
不破 貞仁 (Fuwa Sadahito) — family initial
不+ given initial貞=不貞(infidelity). -
大谷 麻美 (Ōtani Asami) — family initial
大+ given initial麻=大麻(marijuana / cannabis).
I’ve put together some guides to help understand the cultural implications of naming, how to integrate with existing applications and how to integrate with Localize.Message.
Let me know what you think!
9
kip
ex_cldr Core Team
Lauch Day #4 introduces localize_address and localize_phone_number.
These are both NIF-based libraries using libpostal and libphonenumber respectively. Consider them experimental until a 1.0 release.
This post covers address formatting. The next post about phone numbers.
Address Parsing and Formatting
Addresses are a nightmare. Hard to parse, difficult to format. Different around the world. libpostal does the heavy lifting of parsing. It’s fabulous - but not perfect. Then we use OpenCageData for global formatting templates.
Examples
There is a user guide and a few famous examples. Here are some:
221B Baker Street
The fictional London residence of Sherlock Holmes, as described by Arthur Conan Doyle. Today a real museum occupies the address.
iex> {:ok, address} = Localize.Address.parse(
...> "221b BAKER street, LONDON nw1 6xe, united kingdom",
...> territory: "GB", capitalize: true
...> )
iex> address.house_number
"221b"
iex> address.road
"Baker Street"
iex> address.postcode
"NW1 6XE"
iex> {:ok, formatted} = Localize.Address.to_string(address)
iex> IO.puts(formatted)
221b Baker Street
London
NW1 6XE
United Kingdom
The Imperial Palace, Tokyo
The primary residence of the Emperor of Japan, in the Chiyoda ward of Tokyo.
iex> {:ok, address} = Localize.Address.parse(
...> "1-1 CHIYODA, chiyoda-ku, tokyo 100-8111, JAPAN",
...> territory: "JP", capitalize: true
...> )
iex> address.city
"Tokyo"
iex> address.postcode
"100-8111"
iex> {:ok, formatted} = Localize.Address.to_string(address)
iex> IO.puts(formatted)
1-1
Chiyoda Chiyoda-Ku
Tokyo, 100-8111
Japan
8
kip
ex_cldr Core Team
Localize Launch Day #4 - localize_phone_number.
Phone number parsing and formatting
Phone numbers are at least structured data and libphonenumber does both the parsing and formatting. There is a user guide.
Capitalization
There is a :capitalize option to parsing (and a capitalise/1 function) that will titlecase and capitalise addressing as appropriate. It’s a heuristic on my behalf but I think it produces reasonable results. This can be quite tricky depending on the language. So we use unicode_string to handle it since it knows about localized casing. Here are some tricky bits that unicode_string helps us handle:
-
Dutch, “IJ” is treated as a single unit at the start of a word — when titlecasing “ijsselmeer”, the correct result is “IJsselmeer” (both I and J capitalized), not “Ijsselmeer”. This requires understanding extended grapheme clusters because the titlecase operation needs to uppercase two codepoints at the word boundary, not just one.
-
Turkish/Azeri (
:tr,:az) — dotted vs dotless I (i↔İandı↔I) -
Lithuanian (
:lt) — accent handling with soft-dotted characters -
Greek (
:el) — diacritics removed on uppercase, final sigma handling
Examples
There is also a set of examples from film and literature.
Ghostbusters — “Who you gonna call?”
The Ghostbusters ad told New York to dial 555-2368. With a full area code the number parses and formats correctly:
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 212-555-2368")
iex> Localize.PhoneNumber.to_string(phone_number, :e164)
{:ok, "+12125552368"}
iex> Localize.PhoneNumber.to_string(phone_number, :national)
{:ok, "(212) 555-2368"}
iex> Localize.PhoneNumber.territory(phone_number)
"US"
iex> Localize.PhoneNumber.valid?(phone_number)
true
Without an area code the seven-digit local number still parses, but libphonenumber cannot validate it:
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("555-2368", territory: "US")
iex> Localize.PhoneNumber.valid?(phone_number)
false
Jenny — 867-5309
Tommy Tutone’s 1981 hit gave us the most dialled number in pop music. As a seven-digit local number it parses but is not valid without an area code:
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("867-5309", territory: "US")
iex> Localize.PhoneNumber.to_string(phone_number, :national)
{:ok, "867-5309"}
iex> Localize.PhoneNumber.valid?(phone_number)
false
Give Jenny a proper area code and the number becomes fully valid:
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 415-867-5309")
iex> Localize.PhoneNumber.to_string(phone_number, :international)
{:ok, "+1 415-867-5309"}
iex> Localize.PhoneNumber.valid?(phone_number)
true
iex> Localize.PhoneNumber.type(phone_number)
:fixed_line_or_mobile
The Shining — Overlook Hotel, Colorado
Stanley Kubrick’s Overlook Hotel sits in Colorado (area code 303). Using the 555 range reserved for fiction:
iex> {:ok, phone_number} = Localize.PhoneNumber.parse("(303) 555-0147", territory: "US")
iex> Localize.PhoneNumber.to_string(phone_number, :e164)
{:ok, "+13035550147"}
iex> Localize.PhoneNumber.to_string(phone_number, :international)
{:ok, "+1 303-555-0147"}
iex> Localize.PhoneNumber.territory(phone_number)
"US"
10
kip
ex_cldr Core Team
Day #5 of Localize launch week. I said today would be launch day for Intl and indeed it is. But I’m also launching one additional library and a shiny new web site. In total today there are three things launching, all of which are clients of Localize.
- Intl which provides a Javascript Intl-like interface to Localize
- calendrical which is a set of 17 calendar types plus more
- And a Localize Playground web site at https://playground.elixir-localize.com
Intl
Since it’s just a wrapper it’s not a complex library. But I wanted to find a way to make localisation more approachable to more developers. Since Intl is the way to localise in javascript it seemed to make sense to have compatible API in Elixir. Thats Intl. There’s a compatibiilty guide that helps understand the similarities and differences. And a getting started guide too.
Highlights
-
Intl.NumberFormat— locale-aware number, currency, percent, and unit formatting. -
Intl.DateTimeFormat— locale-aware date and time formatting with range support. -
Intl.ListFormat— list joining with conjunctions, disjunctions, or unit separators. -
Intl.DisplayNames— localized names for regions, languages, currencies, scripts, calendars, and date-time fields. -
Intl.RelativeTimeFormat— relative time strings (“3 days ago”, “in 2 hours”). -
Intl.PluralRules— CLDR plural category selection (cardinal and ordinal). -
Intl.Collator— locale-aware string comparison and sorting via the Unicode Collation Algorithm. -
Intl.DurationFormat— locale-aware duration formatting. -
Intl.Segmenter— text segmentation into graphemes (built-in), words, and sentences (via optionalunicode_stringdependency).
I hope developers who are more used to working on the front end might find is reasonably easy to continue their Elixir journey to localisation with Intl.
9
kip
ex_cldr Core Team
Next up in calendrical. I’ve always been fascinated by calendars and time keeping.While ex_cldr_calendars has done a solid job for many years, it was never complete in my eyes. Calendrical is definitely next generation.
Lunar calendars
While we had solar and lunisolar calendars for a some time now (which enables Persian, Chinese/Japanese/Korean calendars), we didn’t have support for lunar calendars (used to support Islamic and Hebrew calendars). That required a lot of work in Astro to support moonrise and moonset. And also to do simulated lunar crescent detection. As a result, the moonrise/set functional accuracy is as good as it gets and the Islamic and Hebrew calendars are as accurate as they can practically be.
Composable calendars
This is special-purpose calendar in which you actually compose a set of calendars. It’s particularly useful if you’re doing historical research and you need to track when the switch from Julian to Gregorian calendars occurred. It’s very niche. But it’s also very cool.
User-defined calendars
This is made very easy by having a simple use Calendrical macro in a module and defining a few parameters. Lets you build almost any variant of a month-based or week-based calendar, Including calendars with leap years. And not only Gregorian calendars - you can override functions to have the behaviour you want. In fact most calendars in the library are defined this way now.
Calendrical Features
-
17 CLDR-aligned calendar implementations — Gregorian, Persian, Coptic, Ethiopic (two eras), Japanese, Chinese, Korean (Dangi), Lunar Japanese, four Islamic variants (Civil, TBLA, Umm al-Qura, observational), Hebrew, Buddhist, Republic of China (Minguo), Indian National (Saka), and Julian.
-
Calendrical.Behaviour— adefmacro __using__template that supplies default implementations of everyCalendarandCalendricalcallback. Users can define a new calendar in 60–200 lines by overriding only the parts that differ from the defaults. -
Composite calendars —
Calendrical.Compositelets you build a calendar that uses one base calendar before a specified date and another after, supporting historical Julian-to-Gregorian transitions and similar splices. -
Localized formatting — era names, quarter names, month names, day names, day periods (AM/PM), and full date formatting via
Calendrical.localize/3andCalendrical.strftime_options!/1. Falls through to all 766+ CLDR locales available fromLocalize. -
Fiscal-year calendars — pre-built fiscal calendars for ~50 territories (US, UK, AU, JP, …) plus a configurable
Calendrical.FiscalYear.calendar_for/1factory. -
Date arithmetic — the standard
Date.shift/2andNaiveDateTime.shift/2work across every Calendrical calendar. -
Date intervals —
Calendrical.IntervalreturnsDate.Rangevalues for years, quarters, months, weeks, and days in any supported calendar, withrelation/2implementing Allen’s interval algebra. -
k-day calculations —
Calendrical.Kdayfinds the n-th occurrence of a given weekday relative to a date (e.g. “the second Tuesday in November”). -
Calendar formatters —
Calendrical.FormatandCalendrical.Formatterprovide a behaviour-based plugin system for rendering calendars as HTML, Markdown, or any custom format. -
Astronomical calendar support — observational lunar calendars (Persian, Chinese, Korean, Lunar Japanese, observational Islamic, Saudi Rgsa, astronomical Umm al-Qura) use the Astro library for equinox, lunar phase, and crescent visibility calculations.
-
Ecclesiastical calendars —
Calendrical.Ecclesiasticalprovides Reingold-style algorithms for the movable and fixed Christian feasts of three different traditions: Western (easter_sunday/1,good_friday/1,pentecost/1,advent/1,christmas/1,epiphany/1), Eastern Orthodox (orthodox_easter_sunday/1,orthodox_good_friday/1,orthodox_pentecost/1,orthodox_advent/1,eastern_orthodox_christmas/1), and astronomical (astronomical_easter_sunday/1,astronomical_good_friday/1,paschal_full_moon/1— the WCC 1997 proposed reckoning). -
Sigils — every Calendrical calendar works with Elixir’s native
~D/~U/~Nsigils via the standard calendar suffix:~D[2024-09-01 Calendrical.Hebrew],~D[1446-09-01 Calendrical.Islamic.UmmAlQura].
11
kip
ex_cldr Core Team
Last one for today and for this week. Elixir Playground - a way to get more familiar with locales and an explorer of some of the capabilities of CLDR as expose through Localize.
Visit it at https://playground.elixir-localize.com
It’s only running on a fly shared VPS so don’t expect super fast performance. You’ll notice I the top right-hand-side of the page there is a language selector. There are 25 or so languages localized for Localize Playground. All the messages are rendered through Gettext using Localize.Message MF2 message formats.
There’s even syntax highlighting now on MF2 messages you can see on the Messages. Syntax highlighting functions are now in Localize as of version 0.15.0.
It’s a long time since I’ve build an actual app and deployed it. My friend Claude helped a lot with it. I’m sure it’s got rough edges and several issues. Please do report issues so I can improve it.
Of course it’s open source so you can clone it and run it locally.
8
kip
ex_cldr Core Team
Just wanted to note that I have completed an update to ex_money to be supported on Localize and and update to digital_token to revise how and what token data is downloaded from the ISO authority, They will be out early next week.
13
munksgaard
munksgaard
Question: I see the documentation for format_to_safe_list/3 says “This is the foundation for HTML/HEEX renderers in companion packages”. Are there any such packages yet, plans for some, or are you leaving that to the community?
0