Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.4.0] — October 23rd, 2026

Release notes

1. Built on CLDR 49 and Unicode 18. CLDR 49 no longer publishes 114 locales below Basic coverage, collation follows UCA 18, and its new data is supported, from dual and UTC offset formats to new units and the Unicode 18 currency signs.

2. Significant work on date and time formatting towards TR35: semantic skeletons, append items, qualified metazone names, cyclic years, and a calendar's own weeks and quarters. Many outputs change; see the breaking changes below.

3. Date, time, date-time and interval parsing move from Calendrical into Localize, so an application that uses only the proleptic Gregorian calendar no longer needs Calendrical.

4. Time zones are parsed and resolved by Localize.DateTime.Timezone.parse_zone/2, resolve/3 and parse_offset/2, and Localize.TimeZoneDatabase handles fixed offsets.

5. Calendars other than Calendar.ISO come from Calendrical 2.0, which ships the same day, and a locale's -u-ca- converts a value into its calendar.

6. Localize.Inflection is added as a technical preview: inflected words, pronouns and quantities, MessageFormat 2's i: functions and inflected units.

7. CLDR 49's technical previews are supported and marked as such: ordinal days, numeric date and time separators, the c12 and c24 hour cycles, semantic skeletons and rational number formats.

8. Number parsing reads currency amounts and a locale's alternative separators (:currency, :separators).

9. Locale data is verifiable and self-hostable: mix localize.verify_locales, Localize.cldr_repo_ref/0 and a self-hosting guide.

10. Public functions return {:error, exception} for arguments and options of the wrong type, where they previously raised.

Breaking changes

Localize 1.4 includes a significant number of breaking changes but they are all a result of improved conformance with TR35 and would not, in typical use, be expected to be observed in the majority of current use cases.

Calendars

• A calendar other than Calendar.ISO must implement the Calendrical 2.0 behaviour, and any other is refused with Localize.UnknownCalendarError. Use Calendrical 2.0 with Localize 1.4.

• A locale's -u-ca- converts a value into that calendar before it is formatted: en-u-ca-hebrew writes a Gregorian date as a Hebrew one. The calendar comes from the provider registered with Localize.Calendar.register_provider/1, which Calendrical 2.0 registers when it starts.

• MessageFormat 2's calendar option names the calendar on the message's locale, as -u-ca- does, rather than a calendar module.

• The parse functions' :calendar option is a calendar module, and the date is returned in it. A CLDR calendar name such as :hebrew, or a module that is no calendar, returns Localize.UnknownCalendarError.

• The parse functions no longer take :return_calendar. Use Date.convert/2 on the result.

• Localize.DependencyRequiredError is removed. Nothing returns it, since Localize no longer reaches for Calendrical by name.

• A numeric month is written as the calendar writes it (written_date/3): a Hebrew common year's Adar is "6", as ICU writes it, where it was "7".

• y in the Chinese and Dangi calendars is the year's place in the 60-year cycle: the year that began in 2026 is "43", where it was "4663". u writes the year's number.

• Quarters and week numbers are the calendar's own: a Coptic or Hebrew thirteenth month is in Q4, where it was Q5. Calendar.ISO keeps the locale's weeks.

• W numbers a month's weeks as a year's are numbered, and its pattern writes the month that week belongs to: 1 October 2021 is "week 5 of September" in en-GB, where it was "week 0 of October".

• A date in a calendar of weeks is written with CLDR's generic calendar, "M06 16, 2026 AD", where its week was written as its month.

• A calendar's own formats are read before ISO 8601, so "2023-11-22" read in the Chinese calendar is a Chinese date, where it was a Gregorian date converted.

• Text that none of a calendar's formats reads is read in the calendar its info/0 names as :parsing_calendar, then converted: "Feb 1, 2024" in Calendrical.ISOWeek is 1 February 2024.

• Japanese eras before Meiji start on proleptic Gregorian dates, so each moves by days to weeks: CLDR recorded their lunisolar proclamation dates.

Formatting dates and times

• Localize.DateTime.to_string/2 joins date and time with the locale's "at" pattern by default: en :long is "July 6, 2024 at 2:30:45 PM". style: :default restores the previous output; :medium and :short are unchanged.

• An interval joins date and time with the locale's standard date-time pattern, not the "at" pattern: "June 15, 2026, 10:00 – 14:30". style: :at restores it.

• An interval at a standard format writes the fields and widths of that format's single-value pattern: vi :short is "1/4/23 – 10/4/23", where it was "01/04/2023 – 10/04/2023".

• Two times on one day at a format with seconds are each written whole: "Apr 8, 2026, 12:00:00 PM – Apr 8, 2026, 2:00:00 PM". time_format: :short, or a skeleton without seconds, writes the date once.

• Skeletons match the locale's availableFormats only, as CLDR's pattern generator does, not its standard formats: ko :yMd is "2024/7/6".

• A pattern or skeleton that asks for a field the value lacks returns {:error, %Localize.DateTimeInvalidInputError{}}, where it left the field blank: "Jun , 2026".

• A partial date takes its skeleton from the fields it has: %{year: 2024, month: 6} is "Jun 2024", where it was "6/2024".

• The numeric weekday fields e and c count from the locale's first day of the week: Saturday is 7 in en and 6 in de, where both gave 6. cc is one digit.

• A pattern field at a width TR35 does not list, such as MMMMMM or HHH, formats as U+FFFD.

• Localize.Calendar.localize/3 returns a Localize.DateTimeInvalidInputError for a value that lacks the field it names, where it gave the field's first value: localize(%{year: 2026}, :month) was "January".

Time zones

• A metazone name is qualified by the zone's country or city unless the zone is the metazone's preferred zone for the locale's country: in en, Berlin is "Central European Time (Germany)" (v) and "Central European Summer Time (Germany)" (z).

• A zone's standard name stands in for a missing generic name only where the zone keeps one offset for 184 days either side, so London's summer is no longer "Greenwich Mean Time".

• A zero offset is spelled out in the localized GMT format, "GMT+00:00" long and "GMT+0" short. Localize.DateTime.Timezone.gmt_format/3 drops its :zero_format option.

• EST5EDT, CST6CDT, MST7MDT and PST8PDT are zones of their own in CLDR 49, not aliases of New York, Chicago, Denver and Los Angeles, so they format by their offset.

Parsing

• A date-time parsed with an offset keeps its wall time and offset: "2026-05-23T14:30:00+05:00" is 14:30 at +05:00, where it was 09:30 UTC. DateTime.shift_zone/3 gives the previous result.

• The time zone of a date-time parsed with an offset is the offset itself, "+05:00", where it was "Etc/UTC". DateTime.add/4 and DateTime.shift/3 on it need the new Localize.TimeZoneDatabase.

• A named zone in parsed text resolves to a DateTime through the configured time zone database, where it was dropped unless Calendrical was installed. A zone the locale does not write, such as "XQZV", is an error.

Relative time

• Localize.DateTime.Relative counts the calendar periods between two dates with the calendar's diff/3 and shift/6, not a mean month or year: 1 February is "next month" from 31 January. Hours count the clock, so 00:01 is "in 1 hour" from 23:59.

• Without :unit, the largest unit of which a whole one lies between the two values is chosen, as ECMA-262 Temporal chooses it. A number of seconds is counted in weeks at most.

MessageFormat 2

• {$t :time} and {$d :datetime} give the time to the minute, as TR35 specifies; precision=second restores the seconds. A date or time option other than timeZone, hour12 and calendar set from a variable is an error.

Locale data and display names

• CLDR 49 drops 114 locales below Basic coverage, among them aa, ab, an and ht. Such a locale resolves to a fallback, :und for aa.

• An unsupported :prefer value is an error, where it resolved to :standard. :prefer now applies to Localize.Language, Localize.Territory and Localize.Script too.

• Collation moves to Unicode 18 (UCA 18.0.0), so any stored Localize.Collation.sort_key/2 must be regenerated. compare/3 is unchanged for existing characters.

Added

• An ISO 8601 week date parses in any of its forms, "2026-W25-2", "2026W252" or "2026-W25", as a week and day of the calendar it is read in.

• Localize.Number.Parser.parse/2 takes :currency and reads an amount with that currency's separators: de-AT writes € 1.234,56 but 1 234,56 plain, so "1.234,56" parses only with the option.

• Localize.Number.Parser.parse/2 takes :separators, naming the set of decimal and grouping separators to read with for a locale that has more than one: en-ZA writes 1 234,56 with its :standard set and 1,234.56 with its :us set. A locale without the named set reads with its standard one.

• Localize.Locale.data_locale_id/1 returns the id of the locale whose data is loaded for a locale, which is its own unless a fallback supplied it. Language rules now follow that locale so they agree with its text, while territory preferences keep following the requested locale.

• Localize.Number.Symbol.for_currency/2 returns the symbols an amount of a currency is written with, taking the currency's own decimal separator over the locale's currency separators over its plain ones.

• The day of the month (d) is the day the calendar writes its date with, its written_date/3, so Calendrical's Julian year-start variants write 25 March 1750 from month 1 day 1.

• Such a date reads back through the calendar's date_from_written_date/3: "March 25, 1750" is month 1 day 1 again, alone, in a map or at either end of an interval.

• The months between two dates are counted by the calendar's diff/3, so Calendrical's March25 months 1 and 13, both named March, are two months.

• Every parse function refuses text longer than :max_parse_length, 1,024 bytes by default, with a Localize.DateTimeParseLengthError. The longest text any locale writes is 666 bytes, and reading cost grows with the square of the length.

• Localize.Territory.Hemisphere.hemisphere/1 returns the hemisphere of a territory or locale, :northern, :southern or :ambiguous where the equator crosses it: hemisphere(:AU) is {:ok, :southern}. A region is answered from the territories it contains.

• Localize.Calendar.register_provider/1 registers the module that supplies calendar modules for a locale's -u-ca-, and calendar_provider/0 returns it. Calendrical 2.0 registers itself when it starts.

• Localize.Date.parse/2, Localize.DateTime.parse/2 and Localize.Interval.parse/2 read a composite calendar's date in each calendar its parsing_calendars/0 names, so "Mo5 11, 1872" in Calendrical.Reform.Japan reads back.

• Localize.Date.parse/2 takes :format, a standard format, skeleton or pattern, and reads the text with it alone: mt's :yMd "4/3/2024" is 3 April. Localize.Interval.parse/2 takes it as the interval's format.

• Localize.DateTime.parse/2 reads the date and the time with the two halves of :format: "3/4/2024 22:05" with format: "d/M/y HH:mm". :date_format and :time_format set one half.

• Localize.Time.parse/2 takes :format too, a standard format, a skeleton or a pattern, and reads the text with that format alone: "14h30" with format: "HH'h'mm". A :long or a :full format reads a time with its zone and, as it is written for a time that has none, without it.

• A date's months, days and patterns are named from the CLDR calendar in effect on that date, the calendar's cldr_calendar_type/3: Japan's lunisolar dates before 1873 take the Chinese calendar's names.

• Localize.Number.resolve_currency/2 and resolve_currencies/2 resolve a symbol several currencies share by the nearest locale that uses one, so "$" is the Canadian dollar in fr. It stays unknown where no locale is a clear fit, as in es.

• Localize.Interval.to_string/3 and to_parts/3 take a skeleton or a pattern as a date interval's :format or :date_format, as CLDR keys interval formats by skeleton, so a format no standard format reaches can be named: format: :yMMMEd is "Mon, Jun 15 – Thu, Jun 18, 2026" in en.

• Localize.DateTime.Timezone.parse_zone/2 reads a time zone in any form a locale writes one — a name, location, city, zone ID or localized GMT format — as TR35's time zone parsing does, and resolve/3 resolves it at a date and time through the configured time zone database.

• Localize.Inflection, a technical preview, inflects words from CLDR's inflection data, with pronoun/2,3 and quantify/4: inflect("Haus", :de, %{case: "dative", number: "plural"}) is "Häusern". Data for 48 languages comes from mix localize.download_inflection.

• MessageFormat 2 gains the Unicode inflection project's i: functions, :i:inflect, :i:pronoun, :i:quantify, :i:list and :i:numeral, with SSML output (output: :ssml). Localize.Message.Namespace lets an application register a namespace of its own.

• Localize.Unit.to_string/2 takes :inflect, synthesizing a pattern when the requested :grammatical_case has no CLDR one — :safe uses attested paths only, :always also guesses from suffixes. Localize.Unit.grammatical_gender/2 returns a unit's gender.

• Localize.Locale.LocaleDisplay.key_name/2 and type_name/3 return a BCP 47 key's localized name and the name of one of its type values — key_name(:ca) is "Calendar", type_name(:ca, :buddhist) is "Buddhist Calendar", and "Buddhist", CLDR's scope="core" name, with prefer: :menu. A value may be given in its BCP 47 form, :gregory or :level1.

• Localize.Locale.LocaleDisplay.display_name/2 takes key_value_display: :separate, TR35's SeparateKeyValue, so en-u-ca-gregory is "English (Calendar: Gregorian)".

• Localize.Calendar.display_name(:calendar, calendar) takes prefer: :menu for the short name a menu of calendars uses, "Gregorian", and accepts BCP 47 names such as :gregory.

• Localize.affirmative_responses/1 and negative_responses/1 return CLDR's POSIX yesstr / nostr forms — {:ok, ["ja", "j"]} for :de — and affirmative?/2 and negative?/2 match a response against them, folding case as TR35 requires.

• Localize.Locale.LocaleDisplay.type_value_name/2 returns the localized name for a boolean BCP 47 keyword value: "On" and "Off" in en, "Ein" and "Aus" in de.

• CLDR 49's placeholderBoundarySpacing separates a text field from a neighbour its output would run digits into, as TR35 now specifies, so zh's "vHH:mm:ss" renders a nameless zone as "GMT+8 14:30:45" rather than "GMT+814:30:45". Numeric fields written together are left alone.

• designation: :utc on Localize.DateTime.Timezone.gmt_format/3 writes CLDR 49's alt="utc" forms, "UTC+01:00" and "UTC+?" in en, and non_location_format/3 passes it to its GMT fallback. Both spellings read back through parse_offset/2.

• CLDR 49's dualOffsetFormat joins the two offsets a zone keeps, so the localized GMT format describes a zone that moves between them: offsets: :dual writes Los Angeles as "GMT-8/-7" and Denver as "GMT-7/-6", where Phoenix keeps one offset and stays "GMT-7". A value with no zone writes its single offset.

• A skeleton whose time half is only a zone joins its date through CLDR 49's Date-Timezone item, and one whose date half is only a weekday joins its time through Time-Day-Of-Week, as TR35 now specifies. en :yMMMdz renders "Jul 6, 2024 EDT", where it errored.

• Localize.DateTime.SemanticSkeleton implements TR35 semantic skeletons, which ask for a date by meaning ("YMDE") rather than by field, and :format accepts one everywhere. :time_precision, :zone_length, :hour_cycle and alignment: :column shape the result.

• MessageFormat 2's :date, :time and :datetime take TR35's options, from fields and length to timeZoneStyle, and the overrides timeZone, hour12 and calendar: {$d :date fields=month-day} in en-AU is "14 Jun".

• Localize.DateTime.Timezone.parse_offset/2 reads a fixed UTC offset from a zone string — ISO 8601, or the localized GMT format in any locale's spelling — inverting gmt_format/3. Localize.DateTime.parse/2 uses it, so "May 16, 2026 2:30 PM GMT+10:30" parses without calendrical.

• Localize.Date.parse/2, Localize.Time.parse/2 and Localize.DateTime.parse/2 parse natively, no longer requiring calendrical — parse("March 22, 2026", locale: :en) gives {:ok, ~D[2026-03-22]}. Localize.Interval.parse/2 and Localize.DateTime.Parser.parse/2 join them.

• Localize.MinimalPairs exposes CLDR's minimal pairs — the phrases demonstrating a locale's plural, ordinal, case and gender forms. cardinal/1, ordinal/1, grammatical_case/1 and grammatical_gender/1 return them; format/3 picks the one a number selects.

• CLDR's symbol-alt-variant currency symbols are ingested as Localize.Currency.variant_symbol and selected with currency_symbol: :variant — :TRY in en gives "TL". CLDR 49's new Unicode 18 signs resolve through it: :AED "⃃", :MVR "⃂", :OMR "⃄" and :SAR "⃁".

• CLDR 49's numeric date and time separators, a technical preview: Localize.DateTime.numeric_separators/2 returns a locale's pair, and :numeric_date_separator and :numeric_time_separator set them on the date, time and interval formatters.

• CLDR 49's -u-hc-c12 and -u-hc-c24, a technical preview, ask for the locale's own 12- or 24-hour cycle, resolved from the cycles its region allows: ja-u-hc-c12 writes 00:30 as "午前0:30".

• Ordinal dates from CLDR 49, which CLDR designates a technical preview: the ddd field formats the day from the locale's dayOfMonths data, so en :yMMMddd renders "Jul 6th, 2024". Locales without that data, and patterns with a numeric month, format the plain day.

• Date-time skeletons resolve through TR35's append items when no available format carries every requested field, appending the missing ones from the locale's appendItems templates. en has no quarter format, so :yMMMdQ now renders "Jul 6, 2024 (quarter: 3)" where it errored.

• Localize.DateTime.Timezone.location_name/3 returns the place the generic location format names for a timezone — a country for a single-zone territory or a CLDR primary zone, a city otherwise — and generic_location_format/2 renders it through the locale's regionFormat.

• The g pattern symbol formats the modified Julian day and the deprecated l is ignored, as TR35 specifies, where both returned a tokenize error.

• mix localize.verify_locales checks a directory of locale files against the release's SHA-256 manifest, exiting non-zero on a mismatch so it can gate a build. It reports the CLDR tag the reference data came from, since the hashes are not overridable.

• Localize.cldr_repo_ref/0 returns the CLDR repository tag the bundled data was generated from, such as "release-49", and the tag now ships in the hex package. Together with Localize.version/0 it traces a locale file to the source it came from.

• A self-hosting guide covers provisioning, verifying and serving locale data from a private CDN. Configure the cache location before downloading, since the download target follows it.

Changed

• Localize.Interval.parse/2 reads text as Localize.Interval.to_string/3 writes it at the given :format, so "Jun 16 – 20, 2026" at :medium parses, where only two dates written whole did.

• A relative time uses its named form only for a whole offset: Localize.DateTime.Relative.to_string(0.9999, unit: :day) is "in 1 day", where it was "tomorrow".

• Localize.Date.parse/2 without a format keeps its compiled patterns for each locale and calendar: "Jun 16, 2026" in en takes about 0.4 ms, where it took 5.

• Localize.Interval.parse/2 keeps its compiled patterns too, so an en interval takes about 2 ms, where it took up to 80. They use up to about 300 KB of :persistent_term for each locale and calendar.

• The Japanese calendar keeps all 237 eras, from 大化 (645) to 令和, where CLDR 49 has Meiji onwards only; the earlier eras take curated dates and CLDR 48.2's names. 白鳳 carries private_era: true, and four unattested eras unverified: true.

• Skeleton matching ranks narrow and short widths nearer abbreviated than wide and breaks ties by TR35's field order, as CLDR's reference generator does: ja :yMdEEEEE renders "2024/7/6(土)", not "2024/7/6土".

Fixed

• A cached locale whose bytes do not match the release's hash manifest is stale, as one of another data version is, so mix localize.download_locales and runtime downloads replace it where it was kept as current.

• A stale cached locale that cannot be refreshed logs a warning naming mix localize.download_locales, once per locale, where it fell back to its parent with only a debug message.

• Regional and script locales name subdivisions, inheriting from their parents: en-GB names :gbeng "England" where it named none. Names CLDR marks unconfirmed are left out.

• Relative months know a month by its name, cldr_month/1, again: a Julian year reckoned from 25 March counts its March as two months, and 21 February to 25 March is "next month", where it was "in 2 months".

• A fiscal calendar's date is written as the Gregorian date it is, through the calendar's cardinal_year/3: 10 August 2026 in a year begun in July is "Aug 10, 2026", where it was "Aug 10, 2027". It reads back through date_from_cardinal_date/3, and an interval across 1 January writes both years.

• A locale's -u-mu-fahrenhe overrides the unit to Fahrenheit, where the override was dropped: BCP 47 caps a value at eight characters, so CLDR spells it fahrenhe, which named no unit.

• A currency amount uses the locale's currency separators where CLDR gives them: fr-CH writes 1'234.56 CHF and de-AT € 1.234,56, where both used their plain-number separators.

• Locale generation fails on a CLDR key its structs do not define, where struct/2 dropped it silently, which is how the currency separators went missing.

• A missing locale falls back to its parents and then to :en rather than to the und root, which has no currency data and no localized names. Only an explicit request for :und loads the root, and the error of a locale that cannot be loaded names the locale requested rather than the last fallback tried.

• A pre-validated Localize.Number.Format.Options struct takes the sign from each number it formats. The sign of the number it was validated with was reused, so options validated with 0 formatted -70 as "CHF 70.00".

• Localize.validate_locale/1 returns an error for an unknown -u-tz- timezone id, a -t- numeric value that is not a 4, 6 or 8 digit date and a -t- keyword without a value, where it raised. A -u-vt- value of several codepoints is accepted, where it raised too.

• Localize.Message.format_to_safe_list/3 returns a data-model error rather than raising WithClauseError: a duplicate declaration parses and then fails validation, which its with had no clause for.

• RBNF plural-keyed substitutions select with the plural rules of the locale the rule set came from, since the forms they choose between are that locale's own words.

• Localize.Locale.gettext_locale_id/2 caches its match per locale and known Gettext locales, so a repeated call takes about 0.4 µs where it took about 34 µs.

• Localize.Currency.currency_strings/2 reads the index of currency-naming strings from the locale data, where the pipeline now generates it, so a call takes about 0.6 µs where it built the index each time for about 1.2 ms. A filtered call is still built, because a filter changes which strings name a single currency.

• Localize.validate_locale/1 returns Localize.InvalidLocaleError for an unknown -u-tz- zone, a -t- date that is not 4, 6 or 8 digits and a -t- keyword without a value, where it raised. A multi-codepoint -u-vt- value is accepted.

• A display name is that of the code it is keyed by, not of a retired alias: ak is "Akan", where it was "Twi", and fil is "Filipino" on every OTP release (#59).

• Inflection data is stored under its data version, so an earlier version is never read for a current one, as a stale zh file was for zh-TW. mix localize.download_inflection --prune removes superseded versions.

• A locale that :persistent_term has no room for returns a Localize.LiteralMemoryError naming the VM flag +MIscs, where loading it stopped the VM. All CLDR locales take about 814 MB of its 1 GB default; the performance guide's "Memory" section gives the sizes.

• A skeleton asking a non-Gregorian date for a field its formats lack has it appended, after matching the calendar's formats and then the Gregorian's: a Hebrew :yMMMdw is "1 Tamuz 5786 (week: 39)", where it was an error. The Chinese and Dangi calendars match only their own.

• A week date in every ISO 8601 form is the calendar's own week, where "2026W252" and "2026-W25" were ISO 8601's in every calendar. A week or day the calendar lacks is an error, where "2026-W53-1" was read in a 52-week year.

• A year, or a year and quarter, written for a calendar other than Calendar.ISO reads as a map of those fields: "2023 AD" in a calendar of weeks is %{year: 2023}, where it was an error, and "Q2 2023 AD" is the year and quarter, not the quarter's first day.

• A related Gregorian year reads as the calendar year that begins in it, however far from the reference date: the Islamic "AH 1699-12-28" is 16 June 1700, where it was an error. Of two years beginning in one Gregorian year, the nearer is read.

• A cyclic year beside an era is that era's year of the name: Calendrical.LunarJapanese's "Genroku (1688–1704) geng-chen 4 29" is 1700, where it was 2000. A name the era has no year of is an error.

• An inverted range read for a calendar whose dates are read in another names its two dates in the calendar asked for: Localize.Interval.parse/2 of "Feb 5, 2024 – Feb 1, 2024" for a calendar of weeks returned a Localize.DateRangeParseError holding the Gregorian dates the text was read as.

• A year below 1 is read where its numbering spells its sign: ja writes a Japanese date before the first era with the jpanyear numbering, "大化マイナス688年3月15日", and it was read as no date, alone and in an interval.

• A week without its year is a week of the reference date's week-based year: "Sun (week: 53)" read on 3 January 2021 is that day, where it was no date. Two such weeks read as an interval.

• A pattern's '' is read inside and outside quoted text, as TR35 has it, so mt's "25 ġimgħa ta' 2026" reads back, where its "ta'" was read as "ta".

• A weekday beside a week is that day of the week in every calendar, where "Tue, week 25 of 2026" was read as the week's first day.

• An interval at a standard format is written in that format's numbering, as the date alone is: he's Hebrew medium interval is "א׳–ה׳ בתמוז ה׳תשפ״ו", where it used digits. It reads back, and an interval at a skeleton stays in digits.

• A year a format names is never written as a number, nor a numbered year as a name, as TR35's adjustments require: en's Chinese medium interval is "Mo5 2 – 6, bing-wu", where the related year took the name's place. Between two numbered years the one asked for is written, "5/2/2026 – 5/6/2026".

• An interval whose dates are in two sixty-year cycles of the Chinese or Dangi calendar writes both dates in full, "5/2/2026 – 5/2/2086" for en's yMd, as ICU does, where the interval's pattern wrote the two alike, "5/2/43 – 5/2/43". A format that writes no year takes one first, as it does for any two years.

• G on a Chinese or Dangi date writes the number of its sixty-year cycle, "78" in 2026, as ICU does, where it returned Localize.ItemNotFoundError. Read beside the year's place it names one year: "77 60" began in 1983.

• An interval written without a year across the new year ends in the year after: "Dec 28 – Jan 3" was refused as an inverted range of the reference date's year. The later date is a year on only where it would otherwise come before the earlier, by its calendar's own days, and never an earlier day of the same month.

• A date without its year in a range takes the other date's year, or the next across the new year: "June 16 to August 20, 2031" is that summer, where it was five years earlier, and "Dec 28 – Jan 3, 2027" reads, where it was refused.

• A zone keeps its metazone from 1970 on, as ICU has it: New York in 1965 is "GMT-05:00" and "New York Time", and Los Angeles in 1850 "GMT-07:52:58", not "Pacific Standard Time". Localize.DateTime.Timezone.metazone_for/2 is nil before 1970.

• A pattern that writes a year's name beside its number keeps the name when a skeleton asks for another numbered year. The skeleton r wrote a Chinese year as "2026(2026)" in most locales, root's "r(U)" turned to "r(r)", and writes "2026(bing-wu)".

• Localize.DateTime.parse/2 reads with a Localize.DateTime.SemanticSkeleton given as :format, where the skeleton was ignored. A skeleton whose minutes are optional reads "2 PM", which Localize.Time.parse/2 refused.

• A date and time is written with the numbering its date format states, CLDR's numbers attribute, as the date alone is. he's Hebrew date and time was "1 בתמוז 5786, 14:30" beside the date's "א׳ בתמוז ה׳תשפ״ו", and zh's Chinese day "2" beside "初二".

• An interval whose CLDR item names the year is read with the related year written in the name's place. en's Chinese "Mo5 2 – 6, 2026", beside the item "MMM d – d, U", was an error, as "2026 M05 2–6" was in 487 locales.

• A date two of a locale's formats read is read by the one whose own separators it has. af's "10-7-2569 BE" is its GyMd's, "M-d-y G", the seventh of October, where its "d/M/y GGGGG" read it first, a hyphen for its slash, as the tenth of July.

• An interval written without a year is read as dates of the reference date's year, as a date alone is. "Jun 16 – 20", which the month and day fields write, was read only as two partial dates with as: :map.

• An interval reads with or without spaces about its dash, so en's "Jun 16–20, 2026" and de's "16. – 20.06.2026" read, where they were errors.

• An interval in a year two eras share is read where one of its dates is written without its month. en's "May 1 – 5, 1 Reiwa" asked the calendar about the year 2019 alone, which is Heisei 31 until April, and was an error; each date now asks with the month and the day it takes from the other.

• A numeric field takes the abbreviated width of a named one where the calendar has no numeric format, as CLDR's conformance data and ICU do: GyMd for a Chinese date in en is "Mo5 2, 2026", where it was "Fifth Month 2, 2026(bing-wu)".

• An interval's values are written and read in the order the locale's fallback pattern states, as ICU does: kek writes 16 June 2026 to 20 August 2027 as "20/8/2027 – 16/6/2026", where the earlier date came first. A date written once beside two times stays before them.

• The first year of a Japanese era is read as ja writes it. Its full, long and medium dates take CLDR's jpanyear numbering, whose year 1 is 元, so "令和元年5月1日" was an error.

• A year of an era that began before a calendar changed how it numbers its years is read. Calendrical.Reform.Japan counts its years from 645 until 1872 and as the Gregorian calendar does from 1873, so every date from the reform to the end of Meiji in 1912, "Jun 16, 6 Meiji", was an error.

• A range is cut at every place its separator occurs, where only the first was tried, so da's "2026-W25-2-2026-W27-1" and "October 5, 2026 to October 10, 2026" read. Text before the first date (fr-CH's "du {0} au {1}") and a later-date-first pattern read too.

• An interval is read by the pattern whose own separators are in the text before one that reads it through a lenient separator. ha's yMd writes a year's difference with root's pattern, "26-06-16 – 27-08-20", which its own day-first pattern read as 26 June 2016 to 27 August 2020.

• An interval date without an era takes the other date's era, where it took the reference date's: ja's "H5/06/16～5/06/20" is five days of 1993, where it ran to 2023. A narrow era name reads where it names one era, so "R 8/06/16 – 8/06/20" reads back.

• A Hebrew date in Elul is read beside its era. The year of an era is settled by asking the calendar about the date, and it was asked about CLDR's number for the month, 13, in a common year of twelve months, so de's "07.13.5786 AM", af's "07 Elul 5786 AM" and every interval ending in Elul were errors.

• A narrow month name reads where the format writes one and the calendar's narrow names are distinct: mn's "2026 VI" and "2026 оны VI/16 – VIII/20" read back. en's "J", shared by three months, is still no month.

• A format with a variant is read as the formatter writes it, standard pattern first: en-CA's Chinese short date "5/2/2026" is the fifth month's second day, where the variant was tried first, and its yMd interval "6/16/2026–6/20/2026" reads back.

• A skeleton's year is a number at every width and U a name at every width, so a y request never takes the year-name format: yMd for a Chinese date in en is "5/2/2026", where it was "5/2/bing-wu". yyyy and yy stay apart, so yyyy in en is "2024".

• A 24-hour hour beside a day period reads only where the two agree, as TR35 checks, so ksh's "4:00:00 n.M. GMT+5:30", four in the afternoon, is no longer read as 04:00.

• Localize.DateTime.Timezone.resolve/3 takes the reading whose zone is written so at the date: it's "Ora dell’Europa orientale (Kaliningrad)" is Kaliningrad in 2026, where it was Minsk. A name qualified by a city is that city's zone, so "Israel Time (Gaza)" is Gaza.

• A country or city in parentheses is read as a zone's qualifier only after a name the locale writes, so text that is no name before it is no zone. A 24-hour pattern took a time's day period for part of its zone: en-GB read "4:00:00 pm (India)" as 04:00 in India.

• A locale's GMT literal alone is read as GMT, as TR35's parsing reads "the absence of a numeric offset" in "localized or global formats": "غرينتش" in ar and ga's "MAG" are offset 0, where only "GMT", "UTC" and "UT" were.

• Localize.DateTime.Timezone.parse_zone/2, parse_offset/2 and resolve/3 read a number with no sign after the GMT literal as east ("GMT 3", "UTC5:30"), as TR35 allows. A zone inside a date or time still needs its sign, since the number could be the year or the hour.

• An offset's seconds are written by the localized GMT format and by Z to ZZZ: Los Angeles before standard time is "GMT-07:52:58", where it read back 58 seconds out. parse_offset/2 reads seconds after a one-digit hour and hours up to 23, so Juneau's "+15:02:19" reads.

• The long localized GMT format (OOOO, ZZZZ, and a zone name's fallback to it) has a two-digit hour in cs, fi and vmw, as TR35 gives the long format always: "GMT+05:30" and "UTC+05.30", where the one-digit hour of those locales' hourFormat, the short format's, wrote "GMT+5:30" and "UTC+5.30".

• resolve/3, parse_zone/2 and parse_offset/2 read an offset in any numbering system's digits, as TR35 has it: ar-EG's "غرينتش+٥:٣٠" and ne's "GMT+५:३०" read, where they were an unknown zone in the 67 locales with digits of their own.

• Localize.DateTime.Timezone.parse_zone/2 and resolve/3 return an error for bytes that are not UTF-8, where they raised an ArgumentError.

• A custom MF2 function receives its options under their names as strings, as Localize.Message.Function documents. It received an atom for any name an atom existed for, so the documented func_opts["format"] read nil.

• A zone name qualified by a place reads as that place's zone even where its country has a primary zone: "Chile Time (Punta Arenas)" is Punta Arenas, where it was Santiago. A metazone name shaped like a region format reads as the name, so ko's "사모아 표준시" is American Samoa.

• A standard or daylight name reads with the time its zone keeps at the date, as the formatter names it, where "Chile Summer Time (Punta Arenas)" read back an hour out. A standard name that is its metazone's only name ("Kyrgyzstan Time") follows the zone's clock.

• The location format writes a country the locale has no name for by its code, as TR35 and ICU4C do: Havana's zone is "CU" in su and "ora de CU" in oc, where it was "Havana". The code reads back in a locale that writes it.

• A location whose country's name has the shape of the fallback format is read as that country: fr-CA's "heure : Saint-Martin (France)" was read as France's zone, and ru's "Виргинские о-ва (Великобритания)" as the United Kingdom's.

• Localize.Interval.parse/2 reads two-digit years with the era written once: nl's Buddhist "16-06-69 – 20-06-69 BE" reads, where its second year was the year 69. The reading nearest the reference date is taken.

• The six zones whose data key is not their lowercase name, such as America/Port-au-Prince and Antarctica/McMurdo, take the city names their locale gives them, "بلانك-سابلون" in ar, where every locale used their own name.

• A zone name qualified by a place is read where the place or the name holds the fallback format's own text: pt-AO's "Hora de Greenwich (Côte d’Ivoire (Costa do Marfim))" was an error, and ko's "중부유럽 하계 표준시(독일)", whose name has the shape of the standard region format, was read as standard time.

• A date and time in a calendar other than Calendar.ISO takes the zone names of the instant it names, where its fields were read as ISO's: a Persian date in January 2026 in Asia/Almaty is "Kazakhstan Time", where it was "GMT+05:00". metazone_for/2 reads it in its calendar too.

• A time reads only an hour its field allows, as TR35 and a strict ICU do, where "45:30 PM" was 21:30 and "13:30 AM" 01:30 in 618 locales. "13:30 PM" is an error too.

• Localize.Time.parse/2 reads ISO 8601's times in every locale: "14:30" without seconds, which fi, da and 13 more did not read, and "T14", "T1430" and "T143045". z for Z and U+2212 in an offset read too.

• Localize.DateTime.parse/2 reads every ISO 8601 date-time form: week dates and ordinal days before the T, times without seconds or minutes ("2026-W25-2T10:30"), and the basic form ("20260616T103000"). MessageFormat 2's date and time literals take the same forms.

• Localize.Date.parse/2 reads the rest of ISO 8601's date forms: a week alone ("2026-W25"), as its Monday in ISO 8601's weeks, and basic-format week and ordinal dates ("2026W252", "2026166"). A year and month, or a year, reads as: :map in every locale.

• Localize.Time.parse/2 reads an hour only in the range TR35 gives its field, h 1 to 12 and K 0 to 11: "0:30 AM" at h:mm a and "12:30 AM" at K:mm a are errors, where they were read as 00:30 and 12:30. H and k were held to their ranges already.

• An interval writes only the fields its format names, as TR35's algorithm has it: :MMMd from 28 December to 3 January is "Dec 28 – Jan 3", and :yMMMHm on two June days at 10:00 is "Jun 2026, 10:00". A year, month or era the values differ in is written where the format asks for it.

• Localize.Time.to_string/2 writes a Time or NaiveDateTime at a standard format with the locale's standard time pattern, where it took its skeleton's, which differs in 44 locales at :short: bg's short time is "10:30", not "10:30 ч.".

• A date and time with no zone is written at :long and :full with Localize.Time.to_string/2's time, so it reads back in every locale: ja's full is "2024年4月3日水曜日 10:30:00", where the time was "10時30分00秒". fa, es and zh-Hant no longer leave "()" or "[]" for the missing zone.

• A date interval compares its two dates in the fields its format writes, as TR35 does, so a week format writes both weeks (format: :yw is "week 25 of 2026 – week 30 of 2026", where only the first was written) and a quarter is written once for two dates within it ("Q2 2026", where "Q2 2026 – Q2 2026" was written).

• Localize.Interval.parse/2 reads the year of a Chinese or Dangi interval as the related Gregorian year or as the calendar's own, whichever is nearer the reference year, so "11/8/2023 – 11/18/2023", which the formatter writes for two days of the Chinese year 4660, reads back, where it was the Chinese year 2023.

• An ISO 8601 offset or Z written hard against a time is kept: Localize.DateTime.parse("11/22/2023 14:30:45+02:00", locale: :en) is a DateTime two hours ahead of UTC, where the offset was dropped and a NaiveDateTime came back.

• Compiling Localize on Elixir 1.17 and 1.18 no longer logs "The on_load function for module Elixir.Localize.Nif returned: {:undef, …}" and an UndefinedFunctionError: Localize.Priv, which the NIF module's @on_load callback calls, is compiled and loaded first.

• Localize.Interval.to_string/3 and to_parts/3 take dates with only some fields, in CLDR's interval format for them: two months are "Jun – Aug" and a year and month "Jun – Aug 2026", where they were errors. A date and time with no year keeps its date.

• w and Y take a date without its day when every day it could be is in one week.

• A specific time zone name takes standard or daylight time from TR35's stdOffset and dstOffset where a metazone period names them, as CLDR 49 does for Europe/Dublin and America/Winnipeg, rather than from the time zone database's flag: Dublin's summer is "Irish Standard Time" however std_offset is set.

• Parsing no longer depends on map iteration order, which varies between VMs: standard formats are tried in Localize.DateTime.Format.standard_formats/0 order, and a place name two zones share resolves to the one Localize.Territory picks, else the alphabetically first.

• Localize.Locale.parent/1 returns a parent that names its CLDR locale, where it cleared the CLDR locale id with the child's subtags, so a caller walking up the locales no longer validates each parent against every locale, about 20 ms a step.

• Localize.Number.to_string/2 with an RBNF rule only an ancestor locale has, such as Hebrew and Roman numerals, takes a fraction of a millisecond where it took 40 to 50: the chain of locales a rule is looked up in is found once a locale, where each call revalidated every parent tag.

• A date or time pattern is read by code points, so a combining mark after a quote is literal text: nnh's long and full dates ("lyɛ̌ʼ 4 na …"), whose caron follows a quoted "lyɛ", parse, where the quote never closed.

• A numeric month written in an algorithmic numbering parses, as haw writes its short date's month in Roman numerals ("31/xii/24").

• A comma that is the only separator between two date fields is no longer read as optional, so en-ZW's "May 2019" is May 2019, where its "dd MMM,y" read it as 20 May 2019. A comma beside a space may still be left out ("May 5 2026").

• A Hebrew date written in Hebrew numerals parses, as he writes it ("כ״ב בטבת ה׳תשפ״ד" is 22 Tevet 5784): a hebr year is read by its letters' values, its thousands marked by a geresh, where none of he's Hebrew dates read back.

• Localize.Time.parse/2, and the time of Localize.DateTime.parse/2, read the time formats of the :calendar given before the Gregorian calendar's, so de's Chinese "10 vorm." parses as the formatter writes it. A :calendar that is not a calendar module is a Localize.UnknownCalendarError, as it is for a date.

• The localized GMT format writes its offset in the locale's digits, as TR35 and ICU do ("GMT-४" in ne, "غرينتش-٤" in ar-EG), or in those of -u-nu- or the formatter's :number_system. Localize.DateTime.Timezone.gmt_format/3 and non_location_format/3 take a :number_system option.

• Localize.Territory.territory_from_locale/1 returns the region of a -u-rg- subdivision, so en-u-rg-gbsct (Scotland) is :GB where it was :gbsct, and such a locale's currency, unit preferences and time zone names are its region's.

• The week fields Y, w, W, e and c honour a locale's -u-fw- and -u-rg-, which they ignored: Friday is e 5 in en-u-fw-mon. first_day_for_locale/1 and min_days_for_locale/1 follow TR35's algorithm in full, -u-ca-iso8601 and -u-sd- included.

• A datetime interval splits a skeleton into date and time fields, as TR35 does: one day's :yMMMdHm is "Jun 15, 2026, 10:00 – 14:30", where it was an error, and :Hm writes the times alone. A skeleton of date fields formats as a date interval, "Jun 15 – 16, 2026".

• A date or time its calendar lacks is a Localize.InvalidValueError in formatting, intervals, Localize.Calendar.localize/3 and relative time, by the calendar's valid_date?/3 and valid_time?/4. Some fields raised for one and others wrote it, "Feb 30, 2019" or hour 25 as "1:00 AM".

• A calendar whose year begins in another month, such as a fiscal year beginning in July, names its months for the months they are, period 1 "Jul" and "7", where they were named by their place in the year, "Jan" and "1".

• Localize starts inside an escript built with include_priv_for: [:localize], reading its data from a copy extracted into the user cache directory that rebuilds share; one built without it stops at startup saying so, where every process crashed on its first read. Closes #58.

• A collation table file that cannot be read is logged as a warning, as a missing one already was, where any other read error stopped Localize with a CaseClauseError.

• Localize.DateTime.Relative.to_string/2 counts the quarters, and the calendar weeks from the locale's first day for :mon to :sun, between two dates, where it formatted their difference in seconds as that many quarters or weekdays.

• Localize.DateTime.Relative.to_string/2 counts a number of seconds beyond the range of a float, where it raised ArithmeticError.

• Localize.Duration.new/2 counts years, months and days with the calendar's diff/3 and shift/6, giving the span Date.shift/2 adds to the earlier date: 14 January to 13 July is 5 months and 29 days, where it was 30. A date the calendar lacks is an error, where it raised.

• Localize.Duration.new/2 measures two zoned date-times as two moments, as ECMA-262 Temporal does: 10:00 UTC to 18:00 in Karachi is 3 hours, where it was 8. A time paired with a naive date-time no longer raises, and no pairing gives a negative duration.

• Localize.DateTime.Relative.to_string/2 returns an error for a DateTime built by hand without its offsets from UTC or its time zone, where it raised ArithmeticError.

• u writes the calendar's extended year, its extended_year/3, where it wrote the date's year: 15 June 1 BC in the Julian calendar, whose year is -1, is "0", as TR35 defines it. A calendar without extended_year/3 is refused, as one without any other answer is.

• A parsed range of dates is ascending or inverted by its calendar's days, where the dates' fields decided: in a calendar whose year turns after its first month, as a Julian year reckoned from 25 March does, 31 December to 1 January of the same year is no longer refused as inverted.

• Localize.Substitution.substitute/2 substitutes into a template of any shape, where it raised on one it did not list, such as el's zone fallback format "[{1} ({0})]".

• A zone in parsed text reads in the locale's own words and spelling, "heure d’été de l’Est nord-américain" or "غرينتش-4", and a standard or daylight name keeps its own offset, as ICU reads it. Of 52,560 zoned date-times formatted in every locale, all but 80 in nnh round-trip, where 14,099 did.

• Localize.Time.parse/2 reads a time written in the digits of the locale's number system, as the date parser does, so bn "১০:০৫ AM" and fa "۱۰:۰۵" parse, and with them the date-times of 67 locales that write their own digits.

• The date parser reads month, quarter, weekday and era names written in the locale's digits, as dz's abbreviated months ("༤" is April), ckb's short weekdays and ff-Adlm's Japanese eras are, where transliterating the input's digits left them unmatched.

• Localize.Time.parse/2 tries the locale's standard formats first, then its available formats with those carrying a zone or a flexible day period last, where their order followed a map, so ms "11:59 PTG" is 23:59 rather than 11:59 in a zone "PTG".

• A flexible day period reads as the period its hour falls in, so fr's "9:05 matin" is 09:05, not 21:05, and as AM or PM where the locale names none. A word the locale does not name is no longer read as the morning.

• Localize.Interval.to_string/3 and to_parts/3 format with the formats of the endpoints' calendar — its interval patterns, date and time formats and date-time pattern — where they used the Gregorian calendar's, and return an error for endpoints in two calendars.

• An interval across a change of era writes each date's era where its format has one: format: :GyMMMd is "Dec 31, 1 BC – Jan 1, 1 AD", and the Japanese calendar's formats, which write the era with the year, "Apr 30, 31 Heisei – May 1, 1 Reiwa" across the change within 2019.

• An interval whose endpoints differ in no field it shows is the date at the requested standard format, as Localize.Date.to_string/2 and ECMA-402 write it: ko "2023. 4. 1.", where it was "2023/4/1". A date-time interval formatted whole honours :style.

• Localize.DateTime.parse/2 returns the date-time where it raised for every calendar but Calendar.ISO, and reads a date-time pattern that puts the time first, as vi's "{0} {1}" does.

• The date parser tries the locale's standard formats first and then its available formats most specific first, where their order varied between runs, and reads a yy year beside the era of a calendar numbering its years as they are in the century around the reference year ("01.04.66 BE" is 2566 BE).

• Localize.DateTime.to_string/2 and Localize.Time.to_string/2 resolve formats in the value's calendar — its date-time pattern, available formats and append items — where they used the Gregorian calendar's, and Localize.DateTime.parse/2 reads the calendar's date-time pattern as well as the Gregorian one.

• The date and interval parsers read a lunisolar date as the formatter and ICU4C write it: r, U, leap months ("Mo2bis", "闰二月") and zh's and ja's Han numerals. Where a locale writes both the calendar year and the related year, as ko does, the nearer reading is taken.

• A date read without its year is completed with the reference date's year in the calendar it is read in, so "15 Nisan" in the Hebrew calendar is in 5786 where it was in the Hebrew year 2026, and a two-digit year is read in the century around it in every calendar.

• Era names come from the CLDR calendar a calendar's info/0 names as :era_calendar_type, so Calendrical's lunisolar Japanese calendar names its eras (令和), where it returned an error. A year written without its era reads as one of the reference date's era, as ICU reads it.

• The date parser reads a year of an era that begins before the calendar's first year from the calendar year it begins in, so "Hedar 15, 5495 AA" is the Ethiopic year -5, as Calendrical numbers it.

• A lunisolar month written as a number is its traditional number, and a leap month is in CLDR's numeric leap pattern, as ICU4C writes them — the Chinese leap second month is "2bis" in en and "闰2" in zh where it was its place in the year. A partial lunisolar date writes its related and cyclic year.

• The date parser reads a year written with its sign, as a calendar without a before era writes one below 1 — "Mar 15, -456 BE" in the Buddhist calendar — and never pivots a signed year.

• The date and interval parsers read a year with its era in every calendar, as the formatter writes it — "Jun 1, 44 BC" is -0043-06-01 where it was 2044-06-01 and "1 BC" is year 0 — and no longer pivot a two-digit year its era qualifies.

• A year before a Calendrical calendar's first era counts back from the era, as TR35 and Calendar.ISO count it — Calendrical.Gregorian year 0 is "1 BC" and Calendrical.Roc year -5 "6 B.R.O.C." — where it showed the year as it is, "0 BC".

• A partial date shows its era and year of era as its days do — %{year: 2025, month: 1} with :GyMMM is "Jan 2025 AD" where the era was blank, and %{year: 0} is year "1" — and a Japanese one whose days span two eras returns an error naming the fields that settle it.

• The short localized GMT format of a whole hour keeps the offset pattern up to its hour field, as ICU does, so he's "GMT-5" carries one left-to-right mark where it carried two.

• A binary that is not UTF-8 is an error wherever Localize reads text — number and unit parsing, number and date/time patterns, territory names, collation and inflection — where it raised ArgumentError or UnicodeConversionError. Localize.Unit.parse(<<255>>) returns Localize.InvalidValueError.

• A MessageFormat 2 date/time literal keeps the UTC offset it carries, where |2006-01-02T15:04:06-05:00| was read as a floating time and its offset dropped.

• A fixed UTC offset carried under a UTC identifier, as a parsed ISO 8601 offset and Calendrical's fixed offsets are, names its zone in the localized GMT format ("GMT-5"), where it was named "UTC".

• Localize.DateTime.Timezone.metazone_for/2 takes a map whose fields name no real date and time, returning the zone's current metazone, where it raised.

• Localize.Locale.parent/1 gives a parent found by dropping a subtag its own CLDR locale rather than the child's, so ar-SA, de-AT, fr-CA, es-419 and zh-Hant-HK spell numbers out with their language's RBNF rules instead of failing. A validated und walks to root rather than to English.

• Localize.DateTime.parse/2 and Localize.Time.parse/2 with as: :map give a fixed offset such as "GMT+5" the DateTime zone fields the struct form resolves, where the map kept time_zone: "GMT+5" with no offset; a named zone resolves too when the input gives its full date.

• Localize.Time.parse/2 and Localize.DateTime.parse/2 read a time in the locale's -u-hc- hour cycle ("24:30" under h24) and resolve a flexible day period's hour by CLDR's day period rules. Japanese "夜中0:30" is 00:30, where it parsed as 12:30.

• Localize.Date.parse/2, Localize.DateTime.parse/2 and Localize.Date.parse_range/2 parse a date with an era, whose patterns never compiled, and one whose weekday does not lead its pattern. A month abbreviation that is also a weekday name (es "mar") is no longer stripped.

• Localize.Date.parse/2 resolves a month name to that month in the parsed year, so a Hebrew month name parses to its position in an ordinary or a leap year, and "Adar II" parses.

• A semantic skeleton passed as :format for a partial date or time is used rather than replaced by a skeleton derived from the fields present.

• prefer: :menu on Localize.Language.display_name/2 composes CLDR's menu="core" and menu="extension" halves where a locale ships no alt="menu" string of its own, so "ku" renders "Kurdish (Kurmanji)" rather than the unqualified "Kurdish". Affects 571 language entries across 446 locales.

• Localize.DateTime keeps a width the matched format's own skeleton asks for, as Localize.Date did, so fr :yyMd renders "06/07/24" not "6/7/24". A zone keeps its width the same way, so el :yMdHmsv names the zone in full, as its Hmsv format does.

• A skeleton's weekday matches the locale's weekday formats whether spelled E, e or c, and a year whichever of y, Y, u, U or r, taking the width asked for. en :EEEE renders "Saturday" where it gave "Sat", and ja :U "2024年".

• j and C carry TR35's day-period width, three or four letters wide and five or six narrow, so en :jjjjj renders "2 p". An a beside an hour sets only the width of the locale's own day period, TR35 treating ha as h, so zh-Hant :ha keeps its "Bh時".

• A skeleton no available format can build on starts from its first field and appends the rest, as CLDR's reference generator does, so :G renders "AD" and :QQQQ "3rd quarter" where both errored.

• A locale passed to Localize.Inflection must be a well-formed identifier. One containing "../" reached files outside the inflection data directory, loaded them, and created a new atom for every spelling of the path.

• Quoted text in a matched format survives width adjustment: dsb's jjm format "'zeg'. H:mm" rendered "eg. 14:30", its quoted z read as a zone field and deleted.

• Skeleton resolution is covered by CLDR's four skeleton conformance files, 2,871 Gregorian cases, which had not been exercised. All agree with CLDR's reference generator but 116, each recorded with its TR35 reason: hour widths, J padding, C in Indian locales and en yyyy.

• Full UCA conformance restored: all 210,155 pairs in both CLDR collation conformance files sort correctly, where 637 and 536 failed. FractionalUCA.txt and the UCD property files had been hand-vendored at Unicode 17 and are now copied by the pipeline.

• Localize.Locale.LocaleDisplay.display_name/2 renders a locale in root (or und) as bare subtag codes per TR35's code fallback — display_name("nl-BE", locale: :root) is "nl (BE)", where it answered in English. root is now accepted wherever und is.

• Month names come from the calendar's cldr_month/2, so Hebrew months are named correctly in ordinary and leap years ("Adar II" included) and a Chinese leap month takes the leap-month pattern ("Second Monthbis"), where they were looked up by month number.

• The Localize.FormatError message for a selector without an annotation is rendered. Its example declaration was being formatted as a live placeholder, which failed, so the raw template was returned and a warning logged.

• Public functions return {:error, exception} — usually Localize.InvalidValueError — for options that are not a keyword list and for arguments or option values of the wrong type, where they raised; predicates answer false.

• Localize.Message.format/3 returns a Localize.FormatError where it raised when a placeholder, :string or a :string selector was given a value with no string form — a tuple, map, pid, function, a list that is not chardata, or a bitstring that is not whole bytes.

• Localize.to_string/1,2 and Localize.List return Localize.InvalidValueError for an improper list and for a bitstring that is not whole bytes, where they raised FunctionClauseError.

• Localize.Message.format/3 with backend: :nif falls back to the Elixir interpreter for bindings other than strings, 64-bit integers and floats, where some raised and others were misformatted. The NIF decodes JSON \b, \f and \u escapes and exponent-form numbers, which reached ICU as text.

• Localize.Nif.mf2_format/3 returns {:error, exception} for arguments that are not a map or JSON object of strings, 64-bit integers and floats, and for a message or locale that is not a string, where it raised.

• Localize.Message.format/3 and format_to_iolist/3 return an error for an improper binding list, where both backends raised, and the NIF backend skips a list element that is not a {name, value} pair, as the interpreter does.

• Localize.Currency.current_currency_for_territory/1 returns CLDR's primary currency where several are current, where it depended on atom-creation order (LS gave LSL, ZW USD), and gives ML its XOF. The territory currency data carries each currency's CLDR position as :order.

• Localize.Currency.currency_strings/2, and so currency parsing, leaves out a narrow symbol that several current currencies share, such as "kr" in en, where it went to whichever currency came first in atom-creation order. One current currency among historic ones still takes it.

• Currency parsing takes the longest matching currency string by bytes rather than graphemes, so a plural spelled with as many graphemes as its singular (in te, mr, ml and 14 other locales) no longer matches as the singular and leaves the rest of the word in the remainder.

• Localize.Number.System.number_system_names_for/1 and Localize.Number.Format.format_system_types_for/1 return systems in type order (default, native, traditional, finance), where they followed atom-creation order.

• The module mix localize.unit.gen_conversions generates lists each unit once in known_units/0, where the simple base units appeared twice.

• Localize.Territory.to_territory_code/2 matches a name as written before its normalised form and, where territories share it, prefers a country to a region, then the first code alphabetically. In scn the name South Africa and Southern Africa share gives :ZA.

• Fuzzy currency matching takes the alphabetically first of equally close currency strings, where it took whichever came first in map order.

• Functions taking a Localize.LanguageTag, including every :locale option, no longer raise on a hand-built struct with wrong-shaped fields: a nil list or map is empty, a string subtag is its atom, and anything else returns Localize.InvalidLocaleError.

• Interpolating a parsed Localize.LanguageTag into a string gives its BCP 47 form, where it raised because the tag had no canonical id yet.

• Localize.Territory.territory_from_locale/1 takes the territory of a language tag struct that has none from its likely subtags, so a parsed "fr" gives :FR where it gave the default locale's :US.

• A locale that Localize holds data for now resolves to itself. resolve_cldr_locale/1 asked the language matcher even for an exact identity, so ar-EG, which formats in arab digits, resolved to ar, which uses latn.

• root is accepted wherever und is. TR35 makes it a synonym for und, but CLDR's alias data does not carry it, so Localize.validate_locale("root") failed while Localize.Locale.cldr_locale_id_from("root") succeeded.

• mix localize.download_locales rejects a name that is not a CLDR locale rather than turning it into an atom, and unit preference lookups no longer create atoms from the prefixes of a usage.

• Locale downloads retry a CDN server error, timeout or dropped connection up to three times with exponential backoff, where one failure was final; a 404 still fails at once. :http_retries, :http_retry_delay and :http_ip_family configure the retries and the address family.

• Skeleton formats honour the field widths asked for. TR35 matches a skeleton then adjusts its widths to the request; only the first step happened, so format: :MMMM rendered "Jul" in en where the literal pattern "MMMM" rendered "July".

• A skeleton combining a date and a time adjusts both halves' field widths to the request, where a requested zone symbol took the matched format's — :MMMMdjmsO gave "GMT" not "GMT+0". Every Gregorian case in CLDR's datetime conformance fixture now passes, from 47 of 78.

• Skeleton matching is deterministic. Where two formats sat the same distance from a skeleton the winner came from the formats map's iteration order, which depends on when the atom keys were created — so one skeleton could resolve differently between runs.

• A matched format keeps a field width the locale states deliberately. TR35 leaves a pattern field alone where the matched availableFormats id already carries the requested width, so ru's yMd renders dd.MM.y rather than being narrowed to d.M.y.

• Resolving a date-time skeleton no longer creates atoms. Localize.DateTime.Format.Match.split_fractional_seconds/1 interned the remainder left after stripping the fractional-second field; it now resolves against existing atoms only, with identical output.

• A skeleton whose date and time halves no single available format covers joins them at the length TR35 derives from the requested date fields rather than always at :medium.

• :date_format and :time_format resolve a skeleton through TR35 matching, where a missing skeleton errored. A skeleton date format joins through the locale's date-time pattern, so ja renders "2026年6月15日 14:30".

• Localize.DateTime.to_string/2 and to_parts/2 keep both halves of a map holding some date and some time fields, joined through the locale's wrapper, where %{year: 2026, month: 6, hour: 14} rendered "6/2026". A partial value given a skeleton is formatted with it.

• Partial times keep the locale's hour cycle, so %{hour: 14, minute: 30} is "14:30" in de rather than "2:30 PM". A -u-hc- override now applies to partial times and throughout Localize.DateTime, which ignored it.

• Localize.Time, Localize.DateTime and Localize.Interval render a -u-hc-h11 or -u-hc-h24 cycle with the K or k hour ("0:30 AM", "24:30") and resolve j in an interval skeleton. Under -u-hc-, an explicit h or H keeps the cycle it names, as in ICU.

• Time skeletons resolve day periods as ICU does: ha renders "h a" and hb "h b" where both gave a flexible day period, and an H or k skeleton drops a requested one. J drops it as TR35 requires and C ignores a -u-hc- override.

• Localize.DateTime.to_string/2 applies a -u-hc- hour cycle to a skeleton that matches an available format exactly or takes append items, and renders an X or x zone field requested by a skeleton, which it dropped.

• b and B judge noon and midnight at the precision their pattern shows, as ICU does, so "h B" renders 12:05 as "12 noon". VVV renders Etc/UTC as the unknown location, "Unknown Location" in en, rather than "UTC".

• S has exactly as many digits as the field has letters, as TR35 specifies, where it stopped at six and at the value's precision, so ss.SSS on 45.9 seconds is "45.900". U without cyclic year names formats as y, and YYYYYY pads rather than rendering empty.

• Timezone format symbols follow TR35: V is the BCP 47 short identifier ("usnyc"), VVV the exemplar city ("New York") and VVVV the generic location format, where all three returned the IANA name or a GMT offset. An alias like US/Eastern resolves to its canonical zone.

• The generic location format names a country where TR35 requires one — a single-zone territory, or a zone in primaryZones — so VVVV renders Europe/Rome as "Italy Time". primaryZones is new supplemental data, read from metaZones.xml because the JSON omits it.

• v and vvvv fall back to the generic location format before the localized GMT format, which TR35 specifies for the generic symbols only, so Asia/Kolkata is "India Time" rather than "GMT+05:30". The specific symbols z and zzzz still fall straight through to GMT.

• ZZZZ spells a zero offset as "GMT+00:00", matching OOOO as TR35 requires of the localized GMT formats. A metazone with no daylight name also resolves a generic request to its standard name, so vvvv is "Greenwich Mean Time" for Etc/GMT and "India Standard Time" for Asia/Kolkata.

• An unknown timezone offset renders the locale's gmtUnknownFormat — "GMT+?", translated where the locale translates it — instead of a hard-coded English "GMT".

• The short localized GMT format drops the hour's leading zero when the offset has minutes, as TR35 specifies, so O for India is "GMT+5:30" rather than "GMT+05:30".

• Localize.Duration.to_time_string/2 no longer raises on a field longer than two letters, such as "hhh:mm"; the field formats as U+FFFD, as in a date pattern.

• Date intervals use the locale's interval pattern where CLDR ships a matching one, adjusted to the requested widths, rather than gluing two full endpoints — de at :medium renders "03.–05.05.2026". TR35's closest-match step was skipped.

• An interval whose endpoints differ in no field it shows is one value, as TR35's interval algorithm has it, where fields: :year_and_month gave "Jul – Jul 2024". A selection of fields without a year writes none for dates of two years, so fields: :month_and_day across the new year is "Dec 30 – Jan 2".

• Time intervals across noon take CLDR's day-period pattern, "10:00 AM – 2:00 PM" rather than "10:00 – 2:00 PM", and an :h interval within one hour formats a single time. A skeleton the interval table lacks, such as :hms, joins both times through the fallback pattern.

• Same-day datetime intervals join the date, shown once, to CLDR's time interval pattern as TR35 specifies, so en :short is "7/6/24, 10:00 – 10:30 AM" rather than "7/6/24, 10:00 AM – 10:30 AM". Datetimes differing only in seconds format as an interval at :medium rather than as one value.

• Localize.DateTime.Relative.to_string/2 and to_parts/2 return {:error, %Localize.InvalidValueError{}} for a value that is not a number, date, time or datetime, and for options that are not a keyword list, rather than raising FunctionClauseError.

• Localize.DateTime.Relative.to_string/2 and to_parts/2 measure a value against a :relative_to of another type where the conversion is unambiguous, and return Localize.InvalidValueError otherwise. The baseline was silently replaced by the current time.

• Localize.DateTime.Relative.to_string/2 and to_parts/2 format the number for the locale ("in 1,000 days", with ECMA-402 parts) and select the pattern by the displayed number's plural category. A float with :unit is a count of that unit, where it was read as seconds.

• A display name with no entry for the requested preference and none for :standard falls back to a stable key rather than whichever the map yielded first, which depended on atom creation order in the VM.

• Localize.Number.Rbnf.rule_names_for_locale/1 returns its names sorted. On OTP 26 and later their order followed the order the VM had created the atoms, so it varied between runs.

• Localize.Number formats a non-default numbering system with the data CLDR gives the locale for it: fa-u-nu-latn is "1,000.5", not "1٬000٫5", and en-u-nu-arab "١٬٠٠٠٫٥", not "١,٠٠٠.٥".

• The long currency format no longer raises in sd and ckb, whose arab has no unit patterns and now takes their latn ones, and writes a currency with no display name by its code, as TR35 specifies ("٣٫٠٠ USD" in ckb).

• Number patterns give each currency sign width its TR35 meaning — ¤¤ the ISO code, ¤¤¤ the plural name, ¤¤¤¤¤ the narrow symbol — and take the currency's decimal places and CLDR's currency spacing, so ¤#,##0.00 gives "CHF 1,234.56" and "¥1,235".

• Localize.Number.to_string/2 rounds significant digits and scientific mantissas half-even, or by :rounding_mode, where it rounded half-up. A mantissa shows the digits TR35 derives from its pattern, so "##0.##E0" renders 12345 as "12.3E3".

• Localize.Number.to_string/2 and to_parts/2 format a pattern with quoted literal text, such as #,##0 'units', where the pattern lexer looped and exhausted memory. A pattern with a character no pattern syntax accepts, such as a trailing *, returns an error.

• Localize.Number.to_string/2 keeps the whitespace a pattern ends with, as ICU does and as to_parts/2 already did. A :wrapper function receives a quoted pattern character tagged :literal, which it never received.

• Localize.Number.resolve_currencies/2 and resolve_currency/2 match a currency name or code only as a whole word, so "100 US dolars" no longer resolves to the Argentine peso from the "ars" it ends with.

• -0.0 keeps its sign, :max_fractional_digits applies to a scientific mantissa, and compact formatting keeps two significant digits below 1 and groups on ICU's MIN2 rule.

• Localize.Number.to_string/2 no longer raises on a very small float with a large :max_fractional_digits — to_string(1.0e-308, max_fractional_digits: 400) raised ArithmeticError because reconstructing the value divided by a power of ten outside the double range.

• Compact number formatting in Swahili was wrong by a factor of ten, and of a thousand for some ranges. The compact divisor counts zeros in the pattern, which included the negative subpattern — elfu 000;elfu -000 read as six zeros rather than three.

• Plural selection now keeps a Decimal's fraction operands. pluralize/3 converted to a float first, and TR35 selects on the visible fraction digits and their value, so 1.2 was treated as "1.200" and chose other where Serbian, Croatian and Bosnian require few.

• Localize.Unit.to_string/2 selects the plural form of a rounded number by the digits the formatter displays, so hr 0.0045 hours is "0,004 sata" rather than "0,004 sati".

• Unit preferences read the -u-ms and -u-mu keywords, in TR35's order mu > ms > rg > (likely) region: en-u-rg-uszzzz-ms-metric gives celsius and en-US-u-rg-uszzzz-ms-uksystem imperial gallons.

• A unit whose quantity CLDR ships no preferences for falls back to base units rather than erroring: preferred_units/2 on ampere gives [:ampere], on candela-per-cubic-foot ["candela-per-cubic-meter"]. Derived compound base units come back as strings, not atoms.

• A unit usage supplied as a string resolves instead of silently falling back to :default. Every usage CLDR defines now has an interned atom, which Localize.Unit.Preference.known_usages/0 lists, so usage: "fluid" returns imperial units for en-GB where it returned cubic inches.

• RBNF alternation branches are evaluated against the number rather than the remainder. A branch carrying a quotient substitution saw 0, so Russian's 201 spelled "нольсти" instead of "двести"; Ukrainian, Polish, Czech and others were affected the same way.

• RBNF fraction digits spell with the current rule set, a fraction rule's bracketed integer part survives, plural selection uses the numerator, and the >>> preceding-rule chain is built in full.

• RBNF optional rule text renders unconditionally where ICU would not have split the rule in two — its base value must be positive and an even multiple of its divisor — so Afrikaans spells the year 1100 "elf honderd nul".

• RBNF rule selection implements ICU's rollback rule: a rule taking a remainder is passed over for the one below when the number divides exactly but the rule's own base value does not. Bulgarian's financial cardinals no longer spell a trailing "и нула".

• Localize.Message.format/3 selects a plural or ordinal variant by the number as its :number, :integer, :offset or :percent function displays it, so Russian {2 :number minimumFractionDigits=1} is other. An :integer operand given as a Decimal formats rather than raising.

• MessageFormat 2 literals keep all their code points, as TR35 requires, where the parser normalized them to NFC; keys still match a selector's value in NFC. Localize.Message.Print.to_string/2 quotes a literal that is not an MF2 name, so a canonical message parses back unchanged.

[1.3.0] — September 21st, 2026

Added

• Localize.Date.parse/2, Localize.Time.parse/2 and Localize.DateTime.parse/2 parse a localized date, time or datetime string back to a value. They delegate to calendrical, which the application must add as a dependency.

• Localize.DependencyRequiredError is returned when an operation needs a companion package the application does not depend on, naming the :package and the :operation. It is what the new parse/2 functions return when calendrical is absent.

Changed

• Breaking. Localize.validate_territory/1 returns the canonical territory code, so validate_territory("AN") is now {:ok, :CW} where it was {:ok, :AN} — likewise SU to :RU, DD to :DE, and CS and YU both to :RS. This matches validate_locale/1, which already resolved them.

Fixed

• Localize.Utils.Math.mod/2 and amod/2 carry overloaded contracts, so integer arguments type as integer results under dialyzer. Downstream calendar arithmetic no longer types as float-possible when it flows through these functions.

• Localize.validate_territory/1 accepts territory codes that CLDR replaces rather than lists: "UK", and the alpha-3 and numeric forms "GBR" and "826", were all rejected and now resolve to :GB. This matters for anything mapping a ccTLD to a territory, since .uk is the domain while GB is the code.

• Localize.Interval.to_string/3 and to_parts/3 no longer raise FunctionClauseError for en-CA with fields: :month_and_day, format: :short. CLDR publishes an alt="variant" interval pattern for en-CA, and it is now resolved as a single date's pattern is, honouring :prefer.

• en-CA skeleton formats such as :yMd and :MEd render the locale's standard pattern, 2026-05-03, rather than the day-first variant 3/5/2026 they returned whatever :prefer asked for. prefer: :variant still selects the variant.

[1.2.0] — August 16th, 2026

Changed

• Breaking. Localize.Number.Parser.scan/2 now treats a space as a grouping separator in locales that group with one, so runs of digits that it previously returned separately can come back as a single number. Under fr, "chambres 12 14 16" was ["chambres ", 12, " ", 14, " ", 16] and is now ["chambres ", 121416]; pass lenient: false to require exact grouping sizes and get the old result. This is what lets "1 234,5" be found as one number, which is the point of the change.

• Breaking. Localize.Number.parse/2 and scan/2 validate that grouping separators sit in plausible positions, matching ICU, so input that was previously accepted can now fail. Under fr, parse("3 4") was {:ok, 34} and is now an error, because a single digit is not a group in any locale.

• Localize.Number.parse/2 and Localize.Number.Parser.scan/2 take a :lenient option governing that validation. true, the default, requires each group to be at least two digits, which is ICU's lenient rule; false requires exactly the locale's grouping size — three for most locales, and the 3-then-2 of en-IN.

Fixed

• Timezone display names use the exemplar city CLDR ships rather than one derived from the IANA identifier. The lookup matched %{city: _} where the zone data keys :exemplar_city, so it never fired: 48 zones in en and 190 in ja were named from the identifier instead, losing renames (America/Godthab is "Nuuk"), accents ("Córdoba"), and in non-Latin locales the script entirely.

• Timezone display names resolve three-part identifiers such as America/Indiana/Knox, whose leaf CLDR keys by string one level deeper. They were split into two parts, so the lookup sought a city named "Indiana/Knox" and fell back to "Knox" rather than CLDR's "Knox, Indiana".

• Localize.Number.Parser.scan/2 finds a grouped number written with an ordinary keyboard space in a locale that formats with U+202F. Under fr, scan("1 234,5") was [1, " ", 234.5] and is now [1234.5].

• Localize.Number.parse/2 treats every character in [:Zs:] as a grouping space, per TR35's loose matching for lenient parsing. It previously accepted only U+0020 and the locale's own separator, so a fr number carrying U+00A0 or U+2009 — as copied out of formatted output — failed to parse.

• Localize.Number.parse/2 ignores every character in [:Cf:], per the same passage's instruction to ignore format characters, "in particular ... any RLM, LRM or ALM used to control BIDI formatting". CLDR writes the minus sign of ar, he, fa and 16 other locales as a BIDI mark followed by the sign, so a negative number copied out of that text previously failed to parse.

• Localize.Number.parse/2 applies CLDR's parseLenients character folds, which were generated into the locale data but never read. The minus, plus, comma and full-stop families now fold to their canonical form, so the 18 locales writing minusSign as U+2212 — fa, fi, sv and no among them — parse their own negative numbers back. Per TR35 the fold applies to the locale's own separators as well as the input, which is what lets de-CH accept both spellings of its apostrophe group separator.

Added

• Localize.DateTime.Timezone.exemplar_city/3 returns the localized exemplar city for an IANA timezone identifier. derive: false returns an error rather than deriving a name from the identifier, distinguishing a name CLDR vouches for from one this library invented.

[1.1.1] — August 16th, 2026

Fixed

• Localize.Unit.to_string/2 selects the plural category from the rendered digits rather than the input value, as TR35 defines the plural operands over the source number — "the visual appearance of the digits of the result". The float 1.0 renders as 1 and is now "1 hectare" rather than "1 hectares", and conversely 1 with fractional_digits: 2 renders as 1.00 and is now "1.00 hectares" rather than "1.00 hectare".

• Localize.Unit.localize/2 now resolves preferred units whose name is more than one word. It converted the atoms from Localize.Unit.Preference.preferred_units/2 with Atom.to_string/1, yielding "cubic_inch" where the parser wants "cubic-inch", so 35 of CLDR's 90 preferred units failed with a Localize.ParseError — taking the default usage of speed, volume, area, energy and pressure with them.

Changed

• The package now declares Unicode-3.0 alongside Apache-2.0, and LICENSE.md gains a "Unicode Data" section setting out which CLDR and UCD data is embedded, what it becomes, and reproducing the Unicode copyright and permission notice as that license requires. Modules emitted by mix localize.unit.gen_conversions carry the same dual-license SPDX header, so a consumer running reuse lint over the generated file no longer needs a .license sidecar.

[1.1.0] — August 11th, 2026

Fixed

• The Localize.Currency.t/0 type now declares :iso_digits as non_neg_integer() | nil. Historic currencies (for example :BGN) have no ISO 4217 minor-unit definition and carry nil, which the module's own is_nil/1 guards already handle; the previous non_neg_integer() type caused false pattern_match warnings in downstream code that guards against nil.

Added

• mix localize.unit.gen_conversions generates a dependency-free unit conversion module from CLDR data, for embedded targets where compiling Localize costs more than the project itself. There is no unit selection to make: Localize's own parser is inlined into the generated module, so it accepts every identifier Localize.Unit accepts — prefixed, powered and -per- compound alike — through to_base/2, resolve/1 and a compile-time ~u sigil.

[1.0.1] — August 2nd, 2026

Fixed

• Localize.LanguageTag.best_match/3 now prefers a territory's own language when candidates are otherwise equidistant, so sgs (Samogitian, spoken in Lithuania) matches lt rather than en-LT. The distance trie scores every candidate sharing the desired script and territory identically, which previously left the winner to depend on the order of the supported list.

• Localize.ParseError reports an over-cap input as reason: :input_too_large with the byte counts in new :size and :limit fields, instead of interpolating them into a prose :reason string that its own type never allowed. The message, number and unit-identifier parsers all use it, and the oversized input is no longer retained on the exception.

[1.0.0] — July 31st, 2026

The first stable release. MF2 message validation is separated from parsing: Localize.Message.Parser.parse/1 checks syntax, Localize.Message.Validator.validate/1 checks the TR35 data-model rules, and everything that formats or serializes a message runs both. A message like .local $count = {$count :number} — a declaration that reads the variable it declares, which is a Duplicate Declaration error rather than a valid annotation of an external variable — is now rejected wherever it appears rather than only when formatted. The construct for annotating an external variable is .input {$count :number}.

Added

• An ecosystem guide sets out the library's shape: a set of structured, locale-aware types, and the four operations — formatting, parsing, ordering and serialization — that apply both to them and to most of Elixir's own types. It tabulates which library provides each operation for each type.

• Localize.Message.Validator.validate/1 is public, checking a parsed message against the TR35 data-model rules. Localize.Message.Parser.parse/1 remains syntax-only, so tooling that must accept invalid input — to_tokens/2 and the highlighters built on it — parses without validating, while everything that formats or serializes composes the two and reports syntax errors before data-model ones.

Fixed

• Duplicate Declaration is now caught wherever a message is used, not only when it is formatted. .local $count = {$count :number} reads the variable it declares, so it was rejected by format/3 but serialized happily by canonical_message/2 and accepted at compile time as a Gettext msgid. Use .input {$count :number} to annotate an external variable.

• Three further TR35 data-model rules are now enforced: Missing Selector Annotation (a selector that does not resolve, directly or through a chain of locals, to a declaration carrying a function), Variant Key Mismatch (a variant whose key count differs from the selector count), and Missing Fallback Variant (no variant with only * keys). None was detected previously — the first two were documented as enforced during match evaluation and were not, and all three could be formatted or serialized without error.

• Localize.Message.canonical_message/2 no longer serializes a message that violates the data-model rules; it previously round-tripped every invalid form, including a .local declaration reading the variable it declares. The compile-time Gettext interpolator validates too, so a mis-authored msgid fails the build rather than surfacing at runtime.

• The MF2 working-group data-model-errors.json conformance cases now assert the specific error reason rather than merely that some error occurred. The WG cases pass no bindings, so an incidental unbound-variable error satisfied the old assertion — which is how three unimplemented rules stayed green.

• Localize.validate_territory/1 now accepts integer M49 codes as its typespec and documentation always promised — validate_territory(1) returns {:ok, :"001"}. An integer previously raised FunctionClauseError because the validator's guard omitted is_integer/1, even though its normalization already zero-padded integers. Numeric codes may also be given as strings ("001"); note that country-level M49 numbers such as 840 are not in CLDR's territory validity set, which uses the alpha-2 code ("US") there.

[1.0.0-rc.7] — July 28th, 2026

This release settles the :format / :style option naming across the library. The rule is now uniform: :format is how a value is rendered, :style is which variant of a name or pattern you get, and an option that selects something else again — Localize.Interval's choice of which date fields appear — is named for what it selects. Every rename below is a hard break with no alias; each entry names its replacement.

Changed

• Breaking: Localize.Duration.to_string/2 and to_parts/2 rename the per-unit width override from :styles to :formats, so the whole-duration width and its per-unit overrides share one name (format: :short, formats: [hour: :long]). The :styles key, introduced in 1.0.0-rc.2 and never in a stable release, is now ignored like any other unknown option.

• Breaking: Localize.Calendar.localize/3 returns {:ok, name} or {:error, exception} instead of a bare string, nil, or an error tuple, and gains localize!/3 for the bare name — the old union meant a template interpolating the result raised Protocol.UndefinedError when the locale was invalid. It now derives the part's value and delegates to display_name/3, so the two agree: its width option is :style (was :format), its default width is :wide (was :abbreviated), and an unknown part returns an error rather than raising FunctionClauseError.

• Breaking: The calendar part and type names are unified on :day_of_week and :day_period: Localize.Calendar.display_name/3 takes :day_of_week (was :day) and localize/3 takes :day_period (was :am_pm). An unknown part or type now returns an error listing the valid names rather than raising FunctionClauseError.

• Breaking: The day-period variant selector is day_period: :variant on Localize.Calendar.display_name/3 and localize/3, and on the date/time formatters that pass it through (Localize.Time.to_string(~T[15:00:00], format: "h a", day_period: :variant) renders "3 pm"). The :am_pm and :period aliases are removed, so every variant option is now named for the part it applies to, as :era already was.

• Breaking: Localize.Interval.to_string/3 renames its :style option to :fields, because it selects which date fields appear (:date, :month, :month_and_day, :year_and_month) rather than a width — :format remains the width axis, and the two are now named for what they do. Localize.Interval.date_styles/0 becomes known_fields/0, and Localize.DateTimeIntervalFormatError carries :fields with reason :unknown_fields in place of :style / :unknown_style.

Documentation

• Localize.DateTime.to_string/2 documents its :style, :date_format, and :time_format options, which were live but absent from the docs. :style selects the date/time wrapper (:at renders "April 8, 2026 at 12:00:00 PM", and falls back to the standard wrapper for :medium and :short, which CLDR does not define it for).

Fixed

• Localize.Calendar.display_name/3 reports an unusable :style as a :style error listing the widths the field actually has, instead of blaming the value: display_name(:month, 3, style: :bogus) said value: 3, expected: "1..13". style: :short now resolves wherever CLDR carries it (the day parts) rather than silently returning nil.

• Localize.Unit.to_string/2 no longer lets a stray :style option reach the SI-prefix and custom-unit paths, where it produced "5 MegaJoule" for style: :short instead of the correct "5 Megajoule". The option has been ignored since 1.0.0-rc.0 and is now ignored everywhere, as documented.

• Localize.Duration.to_string/2 and to_parts/2 join duration parts with CLDR's unit list patterns matched to the format width, per ECMA-402 Intl.DurationFormat, instead of the standard "and" conjunction: :en now renders "3 days, 2 hr" (was "3 days and 2 hr") and "3d 2h" for format: :narrow.

• Per-compound units whose denominator carries a constant keep that count in every width: curr-usd-per-30-day renders "$10.00/30 days" for `format: :short`, where the denominator's precomposed `per_unit_pattern` ("{0}/d") previously swallowed the count and gave "$10.00/d". Counted denominators now compose through the locale's compound.per pattern, which also stops a numerator whose symbol contains the denominator noun being corrupted (narrow candela-per-30-day gave "10c30 d/30 d", now "10cd/30 d").

[1.0.0-rc.6] — July 27th, 2026

Fixed

• A cached locale left over from an earlier release is now reported as stale rather than missing: Localize.LocaleIsStaleError names both data versions and how to refresh, where the previous Localize.LocaleNotFoundInCacheError sent the reader looking for a file that was present all along. A genuinely absent locale still reports as not found.

Changed

• Metazone data is updated to tzdata 2026c: Africa/Casablanca and Africa/El_Aaiun resume Western European Time from 2026-09-20, so time zone names for those zones are correct on and after that date.

[1.0.0-rc.5] — July 27th, 2026

Fixed

• All sixteen CLDR unit grammar cases are now normalized into the locale data (previously only seven were), so Localize.Unit.to_string/2 with grammatical_case: values like :prepositional (ru), :partitive (fi), or :terminative (hu) formats correctly instead of silently falling back to nominative. The locale data version is bumped to 48.2:2 and all locale data is regenerated.

• Compound unit grammatical-case and gender patterns are now merged deterministically during locale data generation; the previous shallow merge silently dropped case entries, with the surviving subset depending on OTP map iteration order.

• The BCP 47 validity data generator no longer crashes on deprecated timezone codes (those with a preferred replacement, such as camtr → cator); the generated validity data is unchanged, but it can once again be regenerated from source.

• Localize.Unit.parse/2 resolves unit symbols that map to compound identifiers — "1 m/s" → meter-per-second, "3 kWh" → kilowatt-hour — instead of failing on the internal underscore key form. Closes #42.

• Times-compound units with no precomposed CLDR pattern (tonne-kilometer) now format as their localized name ("5 metric ton-kilometers", "5 t⋅km", "5 tonnes-kilomètres") instead of the raw identifier, composed per the CLDR grammatical derivation loaded from grammaticalFeatures.xml. Closes #43.

• Per-compound units whose denominator has no per-unit pattern now localize through the locale's compound.per pattern (Polish "5 jardów na milimetr") instead of falling back to an English "per".

• Localize.Unit.define_unit/2 accepts a derived unit as base_unit (e.g. "day") and folds it to its fundamental base at registration, so the custom unit is convertible and compatible?/2 returns true. Closes #44.

• Person-duration units (year-person, month-person, week-person, day-person) format as their base unit ("5 years"), matching ICU, instead of the raw identifier.

• SI-prefixed units with no precomposed CLDR pattern (megajoule, gigajoule, nanogram) now compose their display from the prefix and base unit ("5 MJ", "5 megajoules", with CLDR combineLowercasing for capitalising locales) instead of the raw identifier. Closes #46.

Changed

• Generated locale ETF files and the download-integrity hash manifest are now serialized with the term_to_binary :deterministic option, making the bytes reproducible across operating systems, architectures, and OTP versions. This lets the manifest generated during development match the data generated in CI and served from the CDN, so runtime download verification succeeds regardless of where each was produced. All bundled supplemental, validity, and collation ETF data is regenerated with the same option.

• Compiling a number format pattern is ~40% faster on a cache miss: the regexes used to analyse the pattern are compiled once at startup rather than recompiled on every call. Formatting is unaffected (compiled patterns are already cached).

• Formatting and parsing read locale data with the validated Localize.LanguageTag.t/0 rather than its locale id, so none of the reads a single call makes — 18 for a date, 100 for an interval of two date-times — resolves the locale again. Localize.Date.to_string/2 is about 2.5 times faster and Localize.Interval.to_string/3 about a quarter faster; a locale given as an id or a string is still validated once, at the boundary.

• A standard format name is no longer matched as though it were a skeleton. Asking for :short, :medium, :long or :full on a value holding fewer fields than that format writes spelled the name out as fields — "medium" as month, weekday, day — and ranked it against the locale's formats before failing, so an interval of two partial date-times is now about five times faster (342 µs to 70 µs for two values of one day holding an hour apiece).

• Skeleton matching breaks a tie between two equally ranked formats by format id, where the winner followed the order the locale's format table happened to be read in and so could differ between VM instances.

• Localize.Locale.get/3 reads the locale data and loads the locale only where that read does not resolve, rather than confirming it is loaded first: an already-loaded locale is by far the common case and the check cost more than the read. A key path that is genuinely absent pays one extra read.

• Locale data files are about 81% smaller — en.etf is 121 KB where it was 655 KB — as they are compressed, and each carries its format tables' keys already tokenized for skeleton matching, which matching derived on every call. Loading a locale pays about 8% more for the one decode it does.

• Reading a time keeps the patterns it may be written with, in the order it tries them, beside the regexes already compiled from them. Ranking those patterns runs a regex over each of them, and a date and time is read by trying its time half at every boundary the text allows, so the list was gathered and ranked again for each of those attempts: Localize.Time.parse/2 is about seven times faster (302 µs to 44 µs) and Localize.DateTime.parse/2 about twice (505 µs to 236 µs).

• A time half carrying no digit is refused before the locale's patterns are tried. A time is read from an hour, so no pattern can read text with no digit in it, where splitting a date from a time leaves halves like "AEST" to be read against every pattern the locale has before failing.

• A date and time is read with each distinct time half read once, where a reading ran for every split that offered it. The splits a text allows share time halves — a date half with its trailing separator and one without leave the same text behind — and the time half is read first, so text that no split reads at all is about twice as fast to refuse.

[1.0.0-rc.4] — July 24th, 2026

Added

• Localize.Unit.parse/2 and parse_unit_name/2 (with bang variants) parse strings like "1kg", "2,5 kg" or a localized "2 Tage" into units, matching locale unit names, canonical identifiers and custom units, with :only/:except filters disambiguating names like "2w" (watt versus week) — the migration path from Cldr.Unit.parse/2.

Fixed

• Custom units with hyphenated names ("double-cubit") resolve everywhere a unit identifier is accepted: registered names match wholesale in the unit parser instead of being split at hyphens by the compound grammar.

[1.0.0-rc.3] — July 23rd, 2026

Added

• Localize.Interval.to_parts/3 and to_parts!/3 decompose date, time, and datetime intervals into typed parts with ECMA-402 :source tagging, across split patterns, fallback patterns, and equal-endpoint collapse. Open intervals (a nil endpoint) are not supported in parts form.

• Localize.Unit.to_range_parts/3 and to_range_parts!/3 decompose a unit range: the numeric range parts keep their sources and the unit pattern text carries source :shared.

• Localize.Duration.to_parts/2 and to_parts!/2 decompose a duration into per-field unit parts (numeric segments carry a :unit key) joined by :literal list separators.

• Date, time, and datetime formatting accept a :number_system option: any CLDR numbering system renders all numeric fields ("Mar ๑๕, ๒๐๒๕" with :thai), equivalent to a -u-nu- locale extension.

[1.0.0-rc.2] — July 23rd, 2026

Added

• Date/time skeletons accept fractional seconds (S–SSS): per TR35 the field is stripped for matching and appended to the resolved pattern's seconds field ("9:30:12.34 AM" for :hmsSS in en).

• Localize.Date.to_parts/2, Localize.Time.to_parts/2 and Localize.DateTime.to_parts/2 (plus bang variants) decompose dates and times into typed field parts per ECMA-402 formatToParts, across standard formats, skeletons, pattern strings and combined date+time wrappers.

• Localize.Number.to_range_parts/3 and to_range_parts!/3 return typed range parts with ECMA-402 :source tagging (:start_range, :end_range, :shared) and :approximately_sign handling.

• Localize.Number.to_parts/2 decomposes the :currency_long and :currency_long_with_symbol formats; the pluralized currency name is a :currency part.

• Localize.Unit.to_parts/2 and to_parts!/2 decompose a unit into its number parts plus :unit and :literal segments per ECMA-402.

• Localize.Unit.to_range_string/3 and to_range_string!/3 format two like units as a range ("2–5 kilometers", fr "0–1 jour"), selecting the pattern's plural category from the TR35 plural-range rules.

• Localize.Number.PluralRule.Range selects the TR35 plural category for numeric ranges (plural_rule/3 for categories, plural_rule_for/3 for numbers).

• Localize.List.to_parts/2 and to_parts!/2 return :element and :literal parts for list formatting per ECMA-402 Intl.ListFormat formatToParts.

• Localize.DateTime.Relative.to_parts/2 and to_parts!/2 return relative-time parts; the number part carries a :unit key matching the JS part shape.

• Localize.Duration.to_string/2 accepts per-unit :display (:auto / :always) and :styles (:long / :short / :narrow) overrides, mirroring ECMA-402 DurationFormat per-unit options.

Fixed

• :rounding_priority :auto (and the unset default) ignores fraction-digit bounds entirely when a significant-digit bound is present, per ECMA-402; previously a binding fraction bound still truncated the significant-digit result.

• The separator between adjacent seconds and fractional-second pattern fields is the locale's decimal separator per TR35 (de renders "09:30:12,34"); previously a period was hardcoded.

[1.0.0-rc.1] — July 23rd, 2026

Added

• Localize.Number.to_parts/2 and to_parts!/2 format a number into typed segments per ECMA-402 formatToParts, covering decimal, currency, percent, scientific, compact and algorithmic-system output.

• Localize.Number.to_string/2 accepts :minimum_integer_digits (zero-pad the integer part, ECMA-402 minimumIntegerDigits), :trailing_zero_display (:strip_if_integer per trailingZeroDisplay), and :rounding_priority (:more_precision / :less_precision per roundingPriority).

• Localize.DateTime.Relative.to_string/2 accepts numeric: :always to force numeric output ("1 day ago" instead of "yesterday"), per ECMA-402 RelativeTimeFormat.

• Localize.Collation.known_collations/0 and Localize.DateTime.Timezone.known_timezones/0 (re-exported on Localize) return the CLDR collation and canonical IANA time zone inventories for Intl.supportedValuesOf/1.

• The MF2 numeric functions accept the TR35 minimumIntegerDigits, minimumSignificantDigits, maximumSignificantDigits, trailingZeroDisplay and roundingPriority options, mapped onto the corresponding Localize.Number.to_string/2 options.

Changed

• The :currency_long formats apply the currency's fraction digits and select the plural name from the displayed value per ECMA-402 currencyDisplay: "name": to_string(1, format: :currency_long, currency: :USD) renders "1.00 US dollars" (previously "1 US dollar").

• Relative time offsets of zero format with the future pattern ("in 0 days") per ECMA-402 and ICU.

[1.0.0-rc.0] — July 22nd, 2026

Added

• Localize.Number.to_string/2 accepts a :sign_display option (:auto, :always, :except_zero, :negative, :never) mirroring ECMA-402's signDisplay across decimal, currency, percent, scientific and compact formats.

Changed

• Number.System.system_name_from/2 resolves any CLDR numbering system for any locale instead of returning a :not_for_locale error, and Format.formats_for/2 and Symbol.number_symbols_for/2 inherit missing data from the locale's default system per CLDR root aliasing.

Fixed

• The implicit negative subpattern is now the minus sign prefixed to the whole positive pattern per TR35, so Localize.Number.to_string(-1, currency: :USD) renders "-$1.00" (previously "$-1.00") matching ICU and Intl.NumberFormat.

• Localize.Number.to_string/2 honours any CLDR numbering system via -u-nu- or :number_system, per TR35/ICU: en-u-nu-thai renders Thai digits instead of an UnknownRbnfRuleError, and algorithmic systems (zh with :hans, en-u-nu-roman) format via their RBNF rules.

• The MF2 numeric functions honour an algorithmic numberingSystem (hans, roman, …) via the system's RBNF rules, matching Localize.Number.to_string/2 and ICU.

• Localize.Unit.to_string/2 with backend: :nif honours the :format option: the NIF call now receives the requested width, so format: :short renders "100 m" on both backends instead of falling back to the long form.

• Localize.Duration.to_time_string/2 honours TR35 single-quote literals in patterns, so format: "h'h' m'm'" renders "37h 48m" instead of substituting the quoted letters as field symbols.

Removed

• The deprecated locale-scoped delegates are removed: Language.available_languages/1 and known_languages/1 (use languages_for/1 / language_names_for/1), Script.available_scripts/1 and known_scripts/1 (use scripts_for/1 / script_names_for/1), Subdivision.available_subdivisions/1 and known_subdivisions/1 (use subdivisions_for/1 / subdivision_names_for/1), and Territory.available_styles/0 (use known_styles/0).

• The Currency positional filter forms are removed: currencies_for_locale/3, currencies_for_locale!/3, currency_strings/3 and currency_strings!/3, along with the positional second argument of the arity-2 forms. Pass the :only and :except options instead; a positional filter now raises ArgumentError so it cannot be silently misread as empty options.

• The deprecated option aliases are removed: Localize.Duration.to_string/2 :style (use :format), Localize.Unit.to_string/2 :style (use :format), Localize.quote/2 :style (use :format), and Localize.Unit.display_name/2 :format (use :style). The former alias keys are now ignored like any other unknown option.

[0.50.0] — July 15th, 2026

Added

• Localize.LanguageTag.remove_likely_subtags/2 and !/2 accept favor: :script | :region to select the TR35 removal variant (zh-Hant-TW minimizes to "zh-Hant" or "zh-TW"), verified against the full CLDR likely-subtags test data.

• The MessageFormat working group's :test:function, :test:format and :test:select registry functions are implemented, so the WG conformance suite's selection-mechanics and fallback cases now run.

• The MF2 numeric functions accept the signDisplay option (auto, always, exceptZero, negative, never), with the plus sign taken from the locale's number symbols.

• An MF2 pattern expression that re-annotates a declared variable operates on the declaration's original value, and numeric functions inherit unset options from a numeric declaration — .local $x = {41 :integer signDisplay=always} rendered with {$x :offset add=1} produces "+42".

• The locale download base URL can be overridden with config :localize, locale_base_url: "..." for deployments mirroring the locale files; downloads are verified against the bundled hash manifest regardless of source.

Changed

• An unannotated MF2 placeholder with a numeric operand formats with the locale-aware :number default ({$pi} renders "3.142" in en and "3,142" in fr), matching the MF2 implicit formatting rules; previously the value was stringified verbatim.

• MessageFormat 2 follows the specification's error semantics: unknown functions are an error (Localize.FormatError reason :unknown_function) instead of formatting the operand, and data-model validation rejects duplicate declarations, duplicate option names, and duplicate variants (NFC-normalized keys) with dedicated error reasons.

• MessageFormat 2 function validation is strict per TR35: the select option must be a literal set directly on the selector expression, digit-size options must be non-negative integers, string operands of numeric functions must match the number-literal production, and :currency, :unit, :date, :time and :datetime are rejected as selectors.

• Localize.Number.Format.Options is documented again: validate_options/2 is the supported way to pre-resolve formatting options for hot loops (as the Performance guide describes), so the module is part of the public API.

• The TR35 conformance guide documents the MessageFormat 2 working-group suite exclusions precisely: unknown-function fallback, duplicate declaration/option validation, select and digit-size option validation, u:dir/u:id expression options, and the :isolate bidi strategy deviation.

Deprecated

• Localize.Currency.currencies_for_locale/2,3, currencies_for_locale!/2,3, currency_strings/2,3 and currency_strings!/2,3 take the include/exclude filters as :only and :except options instead of positional arguments. The positional forms still work but are deprecated and will be removed by Localize 1.0 and no later than December 2026.

Fixed

• Calendar- and provider-module probes in date/datetime formatting (era year, day of era, ISO week and day of year, day of week, CLDR calendar type) and Localize.Locale.Provider.allow_download?/1 ensure the module is loaded before function_exported?/3, so a cold module no longer silently takes the gregorian or default fallback branch.

Security

• Localize.Locale.Provider.locale_file_name/1 rejects locale identifiers that do not have the shape of a CLDR locale id, as defense in depth for the cache-path and download-URL interpolations.

[0.49.0] — July 12th, 2026

Fixed

• Change the namespaces on the leex lexers and yecc parsers to avoid module name clash with ex_cldr versions. Thanks to @jerryluk for the PR. Closes #40.

• The coverage ignore list follows the renamed lexer/parser modules, restoring measured coverage above the 90% CI threshold; a guard test now fails when an ignore-list entry names a module that no longer exists.

[0.48.0] — July 8th, 2026

Added

• Localize.Unit.to_string/2 accepts humanize: true to render any unit in the unit people expect for its magnitude: bit-, byte-, hertz- and watt-based units scale through the humanize/2 prefix ladder (honouring system: :si | :iec) and all other units render through usage-based preferences. An explicit :usage option keeps precedence for preference-scaled units.

• Localize.Unit.humanize/2 and humanize!/2 also scale hertz- and watt-based units through the SI prefix ladder ("2.5 gigahertz", "3.2 gigawatts") — like bits and bytes, these are locale-invariant quantities that CLDR's unit preferences do not cover. IEC prefixes remain restricted to bit- and byte-based units.

[0.47.0] — July 7th, 2026

Added

• Localize.Unit.humanize/2 and humanize!/2 convert a byte- or bit-based unit to the prefix that best fits its magnitude, so 1_500_000 byte formats as "1.5MB" with format: :narrow. The :system option selects :si (powers of 1000, default) or :iec (powers of 1024) prefixes.

• Localize.Number.to_string/2 accepts format: :short and format: :long as ex_cldr-compatible aliases, resolving to :decimal_short / :decimal_long, or to :currency_short / :currency_long when a :currency is specified.

• mix localize.update_cldr orchestrates the CLDR data-update pipeline (copy sources → generate supplemental → compile gate → generate locales → test gate), with --check preflight, --locales subsetting, and each step isolated in a fresh VM. The full update process is documented in the consolidated CLDR Update Guide (CLDR_UPDATE_INTEGRATION.md).

• A Claude Code skill covering all major subsystems (numbers, dates/times, units, lists, collation, MessageFormat 2, locale validation and configuration), installable via /plugin marketplace add elixir-localize/localize. All 300+ skill examples are execution-verified against the library.

Fixed

• Timezone formatting consults zone-level names before metazone names per TR35, so a UTC DateTime renders "UTC" / "Coordinated Universal Time" instead of "GMT" / "Greenwich Mean Time", and Europe/London in summer renders "British Summer Time" instead of "GMT+01:00". Thanks to @gmile for the PR. Closes #37.

• Date and time formatting applies the locale's default numbering system to all numeric fields, so locale: :mr renders "१५ मार्च, २०२१" (likewise bn, fa, my and others) matching ICU. Pattern-level numbers= and caller :number_system_overrides keep precedence. Thanks to @gmile for the PR.

• A -u-nu- locale extension overrides the default numbering system in date and time formatting per TR35: "mr-u-nu-latn" renders latn digits and "en-u-nu-deva" renders deva digits, including when the locale is set with Localize.put_locale/1.

• Territory-specific collation tailorings apply from locale data: sorting with locale: "fr-CA" now uses French Canadian backwards accent comparison. Previously the lookup used only the bare language, silently dropping fr-CA's [backwards 2] override.

• Localize.Calendar.first_day_for_locale/1 honours the -u-fw- extension per TR35: "en-u-fw-mon" returns 1 (Monday) instead of the territory default.

[0.46.0] — July 6th, 2026

Changed

• Full compile time drops from ~66s to ~3.5s: the RBNF lexer grammar no longer explodes the generated DFA (its generated Erlang shrinks from 891KB to 41KB), and the language/subdivision validity checks compile to a single map lookup instead of thousands of guard clauses. Token streams and validation results are unchanged.

• The collation tailoring table loads at runtime on first use instead of being embedded at compile time, shrinking the library's largest beam from 1.7MB to 44KB.

• Every module that embeds ETF data at compile time now declares the file with @external_resource, so a CLDR data regeneration correctly recompiles the timezone, time-preference, validity and script-mapping modules.

[0.45.0] — July 5th, 2026

A quality release: the codebase now passes mix credo --strict with zero findings (enforced in CI), the full MessageFormat 2 working-group conformance suite runs against the formatter, and the documentation gains four new guides. A test-coverage push from 70% toward 90% surfaced — and this release fixes — more than twenty conformance and correctness bugs across date/time, number, unit, collation and language-tag handling.

Upgrading from 0.42 or earlier? Version 0.43.0 renamed the inventory functions from the available_*/known_* names to the uniform known_*/supported_*/*_for scheme and swapped two :format/:style option names. Every old name still works as a deprecated delegate until Localize 1.0 — see the 0.43.0 entry below for the full list.

Added

• The complete MessageFormat 2 working-group conformance suite (16 test files including all nine functions/ suites) now runs against the formatter: 250 cases asserting formatted output and expected errors, with unimplemented features excluded and documented per case.

• Four new guides: plural rules, list formatting, locale validation and matching, and display names. Every example is execution-verified.

• Localize.Territory.territory_names_for/1 and territories_for/1 return the localized territory-name inventory for a locale, completing the *_for family across languages, scripts, subdivisions and territories.

• CLDR metazone data joins the supplemental-data pipeline: Localize.DateTime.Timezone.metazone_for/2 returns the metazone for an IANA zone at a given instant, and zone_for_metazone/2 returns a metazone's representative zone per territory. The z/v format symbols now draw on the full 191-metazone CLDR mapping instead of a 20-zone builtin table.

• A documentation depth pass adds around 150 execution-verified doctest examples and 40 ### Options sections across the number, unit, date/time, locale, territory, list, collation and message modules, and corrects stale claims (RBNF number-system conversion, locale defaults, the validate_locale/1 matching warning).

• A test-coverage push adds around 1,700 tests across exceptions, collation, date/time formatting, MessageFormat 2 tooling, language-tag validity, number/unit internals and the runtime plumbing, raising runtime-library line coverage from 70% to 91%. The 90% threshold is now enforced in CI.

Changed

• The MF2 :offset function follows the specification: it takes exactly one of the add or subtract options (non-negative integer) and adjusts the operand for both formatting and selection. The previous ICU-style offset= option, which only subtracted during selection, is replaced.

• The MF2 numberingSystem function option accepts any valid CLDR numbering system, matching Intl/ICU: {$n :number numberingSystem=thai} renders Thai digits in any locale. Unknown system names still return an error; the :number_system option of Localize.Number.to_string/2 is unchanged.

• Credo (strict) added to the CI lint stage with a committed .credo.exs. Policy: the Design.AliasUsage check is disabled (Localize module names such as List, Date and String shadow the stdlib when aliased; aliasing is applied opportunistically where safe), nesting depth stays at the default maximum of 2, and complexity/apply/arity exceptions are documented inline at each site.

• Deeply nested functions across the library were refactored into multi-clause private helpers with pattern matching (~120 helpers). Behavior is unchanged; the full test suite, dialyzer and doc builds gate the refactor.

• Logger configuration for this project's dev/test environments now renders the domain: :localize metadata attached to Localize log messages.

Fixed

• The U (cyclic year) and r (related Gregorian year) format symbols work: U renders the localized sexagesimal name (丙午, "bing-wu") from the calendar's cyclic name sets and r the Gregorian year in which the calendar year begins, both probing the date's calendar module per the Calendrical protocol. Previously both rendered the raw year number.

• Date/time skeleton matching compared candidate format fields against the wrong skeleton fields, making format selection nondeterministic across VM runs (format: :yMdHm could render "Jul" or "July" run to run). Selection is now deterministic, prefers the exact skeleton, and matches text-field widths by class (E ≡ EEE) per TR35.

• The "alt" language code (Southern Altai) was unreachable: the data pipeline stored it as the atom :alt (a collision with the alt-variant style key), so Localize.Language.display_name("alt") returned an error. Fixed at data load; the pipeline fix lands with the next CLDR data regeneration.

• -t- extension dates encode with zero padding (ja-t-it-m0-ungegn-20070315 round-trips exactly); previously single-digit months and days encoded with an embedded space, producing an invalid tag.

• Localize.validate_locale("en-u-vt-00a4") no longer raises during canonical-id formatting, and Localize.LanguageTag.parse("zh-min-nan") no longer raises ArgumentError (the grammar dropped the extended-language tags for multi-subtag forms).

• CLDR {1}…{0}… substitution patterns with two literals placed the substituted items in the wrong order.

• Collation reorder: [..., :others] places unmentioned scripts at the :others position per TR35; previously they kept unremapped weights, producing orderings incomparable with the reordered scripts.

• The collation max_variable option takes effect in the Elixir backend: :space narrows and :symbol/:currency widen the shifted range per the UCA. Previously the setting was ignored and shifting was fixed at the punctuation boundary.

• Compound unit identifiers canonicalize in the TR35 unitQuantity order, so "kilowatt-hour" keeps its CLDR pattern and renders "2 kilowatt-hours" instead of "2 hour-kilowatt".

• :currency_long_with_symbol renders both the symbol-formatted number and the currency name ("$123.00 US dollars"); both long currency formats now derive the currency from the locale when no :currency option is given.

• Localize.Interval.to_string/3 returns an error for mixed endpoint kinds (e.g. a Date and a Time) instead of rendering malformed output, and equal Time endpoints honour the :time_format option in the single-time fallback.

• The Q and q date-format symbols were swapped: Q now renders the format-context quarter and q the stand-alone quarter per TR35. Visible only in locales whose quarter names differ by context.

• Doubled apostrophes inside quoted date-format text render a literal apostrophe ('o''clock' → "o'clock"); previously the escape was dropped.

• Zone format symbols (Z, O, v, V, x, X) render empty for values without a time zone, matching z; previously they fabricated a UTC zone.

• Localize.Duration.new/2 accepts NaiveDateTime pairs (previously raised) and rejects reversed Time pairs with an error instead of returning a negative duration.

• RBNF plural substitutions ($(cardinal,…)$) select the plural category on the quotient of the rule divisor per ICU: Russian 2,000,000 spells out as "два миллиона", not "два миллионов".

• Requesting a spellout ruleset a locale does not have returns Localize.UnknownRbnfRuleError — with its available: field now populated — instead of silently formatting digits.

• The :spellout format resolves to spellout-numbering (ICU's default ruleset) deterministically; previously the choice among a locale's gendered rulesets varied across OTP releases (German 1.5 could spell "eine", "ein" or "eins" depending on the VM).

• Numeric collation computes the value of non-ASCII digits from their Unicode block's zero digit: Arabic-Indic "٢" sorts before "١٠" and "٠" compares equal to "0"; previously digit values were computed modulo 10 of the codepoint, wrapping mid-block.

• :fractional_digits applies to numbers with a zero integer part: Number.to_string(0.4, fractional_digits: 0) returns "0" (previously "0.4"), with float and Decimal inputs rounding identically across all rounding modes.

• Localize.Utils.Map.extract_strings/2 no longer drops strings that precede a nested list or map, and underscore_keys(nil) returns nil instead of raising.

• Number.to_range_string/3 with approximate: true formats the full range ("~3–5"); previously the range end was silently dropped.

• Number.PluralRule.plural_type/2 returns a bare category atom on both backends; the NIF backend previously returned an {:ok, atom} tuple.

• Converting a mixed unit to another mixed unit works (foot-and-inch → yard-and-foot-and-inch); previously it always returned a :mixed_units error.

• Unit plural categories for Decimal values honour the visible fraction (Decimal "1" renders "1 meter"), and denominator units keep their SI prefix and power ("per 100 kilometers", not "per 100 meter").

• Localize.Utils.Math.power/2 with a fractional exponent between 0 and 1 returned the reciprocal (power(4, 0.5) gave 0.5); Decimal bases now always return Decimals.

• Locale downloads run in a dedicated :localize httpc profile with the proxy set per request, so a configured proxy no longer leaks into later requests or into the host application's default httpc profile.

• Display names of parsed (unvalidated) language tags with -t- extensions or multi-part -u- values no longer crash or mangle subtags, and multiple -u-dx- scripts render translated and list-separated.

• Localize.Date.to_string/2 no longer overwrites a user-supplied :number_system_overrides option.

• Small fixes: UnknownSubdivisionError carries the original input instead of nil; UnknownCurrencyError for a binary code always carries the binary (previously the atom when it happened to exist); MF2 match results deduplicate their bound-variable lists; Localize.Utils.Json.decode!/1 raises ArgumentError on trailing data instead of a bare MatchError.

• Language tags with duplicate singleton subtags (en-u-ca-gregory-u-nu-thai) are rejected with a parse error per RFC 5646; previously the second occurrence was silently dropped.

• Grandfathered language tags resolve to their preferred values from the CLDR alias data: i-klingon canonicalizes to tlh (displaying "Klingon"), zh-min-nan to nan, en-GB-oed to en-GB-oxendict, and the sign-language tags to their ISO codes. Previously irregular grandfathered tags parsed to an empty tag.

• The MF2 Elixir backend reports the same errors as the NIF backend: an unbound variable used as a function option value returns a bind error, and an invalid :locale option returns a locale error; both were previously silently ignored.

• Per-compound units without a direct CLDR pattern compose from the numerator and the per-pattern: foot-per-second renders "2 feet per second" instead of the raw identifier.

• MF2 :percent selection multiplies the operand by 100 before plural-category selection, matching the formatted value per the specification.

• An MF2 .match on an unbound variable returns an unresolved-variable error instead of silently selecting the fallback variant.

• A duplicated boolean assertion in the message custom-function tests masked half of an intended check; general mechanical cleanups (map_join, empty-enum checks, number underscores, redundant with clauses) applied throughout.

[0.44.0] — July 4th, 2026

This release closes the TR35 conformance gaps in the date/time formatting layer and fixes locale-fidelity bugs surfaced by newly-wired conformance data.

Added

• Flexible day periods: the B format symbol selects CLDR day periods ("in the morning", "mittags", "noon", "midnight") from the day-period rules now in the supplemental data pipeline, and b renders noon/midnight at the exact points. Languages without rules fall back to AM/PM.

• Localize.LanguageTag.U.parse/1 and parse!/1 parse a standalone BCP 47 -u- extension string (with or without the u- singleton) into a validated Localize.LanguageTag.U struct, using the same canonicalization as Localize.validate_locale/1. Localize.LanguageTag.U.encode/1 is now a documented public function.

• Downloaded locale files are verified against a SHA-256 hash manifest bundled with the package (priv/localize/locale_hashes.etf, generated by mix localize.generate_locale_hashes at release time), before any decode or cache write. A mismatch or missing entry fails the download with Localize.LocaleIntegrityError; when no manifest is present a one-time warning is logged and verification is skipped.

• The rbnf conformance suite now runs the vendored ICU reference data for de, es and fr in addition to en, and the likely-subtags suite asserts the CLDR FAIL rows.

Fixed

• Localize.Validity.U.encode/2 emits the preferred BCP 47 spelling instead of a deprecated alias (:islamic_civil encodes as "islamic-civil", not "islamicc"), and decode/2 accepts struct-field atom keys and the canonical hyphenated calendar spellings ("islamic-civil").

• Week fields honour the locale's week configuration: w and Y compute week-of-year from the locale's first day and minimum days (2023-01-01 is week 1 in en, week 52 of 2022 in de), and W computes week-of-month accordingly. Previously all three were ISO-only.

• Multi-replacement territory aliases follow TR35 Annex C: hy-SU canonicalizes to hy-AM via the likely territory, uk-SU to uk-UA, sr-YU to sr-RS; previously the first entry (RU) was always taken.

• RBNF decimal-format substitutions (=#,##0=) format with the rule's locale instead of the process locale, so fr digits-ordinal renders "1 141e" and de "1.141." rather than the English "1,141".

• Likely-subtags no longer fabricates mappings for languages without one: private-use languages (qaa) pass through unmaximized per the CLDR test data instead of inheriting the und mapping.

• Locales whose language has no CLDR match resolve to root (und) data instead of the alphabetically nearest wrong language — tlh no longer formats with Afar data.

• Compact formats no longer raise on a negative :fractional_digits option.

Changed

• mix test --cover now excludes build-time tooling (the data-generation pipeline, mix tasks, compile-time parser generators) from coverage measurement so the number reflects the runtime library.

[0.43.0] — July 4th, 2026

This release settles the public API naming and error conventions ahead of 1.0. Every renamed function keeps its old name as a deprecated delegate that will be removed by Localize 1.0 and no later than December 2026.

Deprecated

The naming rule is now uniform: known_* is the locale-independent CLDR universe, supported_* reflects configuration, and *_for is data localized into a display locale. The renamed functions are:

• Language.available_languages/1 → Language.languages_for/1.

• Language.known_languages/1 → Language.language_names_for/1.

• Script.available_scripts/1 → Script.scripts_for/1.

• Script.known_scripts/1 → Script.script_names_for/1.

• Subdivision.available_subdivisions/1 → Subdivision.subdivisions_for/1.

• Subdivision.known_subdivisions/1 → Subdivision.subdivision_names_for/1.

• Territory.available_styles/0 → Territory.known_styles/0.

Two option names are also swapped for consistency; the deprecated keys remain accepted until 1.0:

• The :style option of Localize.Duration.to_string/2 and of Localize.quote/2 is deprecated in favour of :format.

• The :format option of Localize.Unit.display_name/2 is deprecated in favour of :style.

Changed

• Language.display_name/2 and Script.display_name/2 return {:error, %Localize.InvalidValueError{}} for an invalid :style or :fallback option instead of raising; the ! variants raise as before.

• Localize.quote/2 returns an error for an unknown format instead of silently returning the input string unquoted.

• The backend: :nif paths of Number.to_string/2, Number.PluralRule.plural_type/2, Unit.to_string/2 and Message.format/3 now validate the locale through Localize.validate_locale/1 and pass ICU the canonical BCP 47 string, so both backends resolve aliases and -u- extensions identically.

• Internal implementation modules (Localize.Utils.*, collation internals, data plumbing) are no longer part of the documented API. The hex package metadata links now point at hexdocs.

Added

• Localize.Territory.known_territories/0 returns all CLDR territory codes.

• Localize.validate_currency/1 delegates to Localize.Currency.validate_currency/1 so all validators are available on the top module.

• Bang variants: Number.to_at_least_string!/2, Number.to_at_most_string!/2, Number.to_approximately_string!/2, Calendar.display_name!/3 and Unit.display_name!/2.

[0.42.0] — July 4th, 2026

Changed

• Compact decimal/currency formats (:decimal_short, :decimal_long, :currency_short) now apply the ECMA-402/ICU default precision of at most two significant digits on the mantissa: 1234 renders "1.2K" (previously "1K"). Pass :fractional_digits or :max_fractional_digits to override.

• The json_polyfill dependency is no longer declared conditionally at publish time. On OTP 26, add {:json_polyfill, "~> 0.2 or ~> 1.0"} to your own dependencies; the supervisor raises at application start with instructions if the :json module is missing.

Fixed

• Compact-format plural selection now uses the mantissa as displayed, per TR35, fixing grammatically impossible output such as es "1 millones" for 1,050,000. Exact-match count="1" compact patterns (fr 1000 → "mille") are now selected, matching ICU.

• Plural rules for compact values {mantissa, exponent} now compute the n/i/v/w/f/t operands after shifting by the exponent per the TR35 operand table, and Decimals with positive exponents (1e6) no longer report phantom visible fraction digits.

• BCE years render era-relative for Calendar.ISO dates: ISO year -1 formats as "2 BC", year 0 as "1 BC" (previously "-1 BC"/"0 BC").

• Significant-digit rounding no longer forces a trailing fraction digit when the rounded value is integral: 1234.567 at 3 significant digits renders "1,230" (previously "1,230.0"), and minimum significant digits now pad trailing zeros ("1.00" at min 3).

• A corrupt or truncated locale cache file is treated as a cache miss/stale instead of raising, and cache writes are atomic (write-temp-then-rename) so a crash mid-write can no longer tear a cache file.

• Locale downloads no longer follow HTTP redirects — the CDN URL is fully known, so a redirect is always refused.

• An unknown :usage option to Localize.Unit.Preference.preferred_units/2 no longer creates atoms from user input; it falls back to :default preferences per TR35.

Added

• The hex package now includes the NIF sources (c_src/), so LOCALIZE_NIF=true builds from the published package.

[0.41.3] — July 1st, 2026

Changed

• Localize.LanguageTag's canonical_locale_id field — and therefore Localize.LanguageTag.to_string/1 — now holds the canonical-syntax form of the requested locale (aliases resolved and subtags ordered, but neither maximized nor minimized), so "en" stays "en" and "en-US" stays "en-US" instead of collapsing to the minimal identity form. Locale identity and data lookup are unaffected; they key off cldr_locale_id.

• Localize.Language.display_name/2 now follows the TR35 display-name algorithm, which canonicalizes rather than adds likely subtags: a bare language keeps its own name ("en" → "English", "es" → "Spanish"), while an explicitly supplied region or script still resolves to the region-specific CLDR name ("en-GB" → "British English", "pt-BR" → "Brazilian Portuguese"). A string and an equivalent Localize.LanguageTag return the same result.

• Localize.Language.display_name/2 and Localize.Locale.LocaleDisplay.display_name/2 both now validate their input through Localize.validate_locale/1 and drive the display off canonical_locale_id, so a string and an equivalent (maximized) Localize.LanguageTag render identically and no likely subtags leak into the output (a validated "en" tag is "English", not "English (United States)").

Fixed

• Localize.Language.display_name/2 and Localize.Locale.LocaleDisplay.display_name/2 now break the two-subtag candidate tie toward the earlier subtag per TR35, trying lang-script before lang-region.

• Localize.validate_locale/1 now accepts a -u-rg- region override that uses a subdivision id (e.g. "en-u-rg-gbeng"). The subdivision value was being suffixed with the "zzzz" region filler and rejected as an unknown locale.

[0.41.2] — July 1st, 2026

Fixed

• Plural rules now resolve likely subtags before selecting a rule set. Localize.Number.PluralRule.Cardinal and Ordinal (pluralize/3, plural_rules_for/1, plural_rule/3) and Localize.Number.PluralRule.plural_type/2 validate the locale through Localize.validate_locale/1 instead of a bare parse, so a string and an equivalent Localize.LanguageTag select the same category and region-specific rules apply — e.g. plural_rule(0, "pt-PT") is now :other (Portugal) rather than :one (the base pt/Brazil rule). This also corrects plural selection in message formatting.

• Localize.Territory.contains?/2 now validates both arguments, so string and atom territories are equivalent (contains?("EU", "DK") matches contains?(:EU, :DK)); it returns false for an invalid territory instead of silently treating a string as unmatched. It now also accepts territory strings, matching its sibling relationship functions.

• Localize.Collation.Options.from_locale/1 now canonicalises its input through Localize.validate_locale/1, so a string, atom, and equivalent Localize.LanguageTag yield identical collation options and legacy aliases resolve correctly ("iw" behaves as "he", "pt_BR" as "pt-BR").

[0.41.1] — June 30th, 2026

Fixed

• Localize.Language.display_name/2 now normalises its input through Localize.validate_locale/1, so a string and an equivalent Localize.LanguageTag return the same name ("en-GB" and LanguageTag.new!("en-GB") both give "British English") and region-specific codes resolve with fallback ("pt-BR" → "Brazilian Portuguese", "ar-SA" → "Arabic" instead of raising). A malformed locale now returns Localize.InvalidLocaleError rather than Localize.UnknownLanguageError. Thanks to @DVSLabs for the report. Closes #36.

[0.41.0] — June 3rd, 2026

Changed

• Breaking: Localize.Number.Format.Compiler now rejects scientific patterns that contain a grouping separator (e.g. "#,##0.###E0") at compile time. TR35 forbids grouping in scientific patterns; the comma was previously silently ignored at output time. Fix: drop the comma, or use a non-scientific pattern.

Added

• TR35 engineering notation. Patterns like "##0.#####E0" now correctly shift the mantissa so the exponent is a multiple of the pattern's max integer-digit count: 12345 → "12.345E3", 123456 → "123.456E3". Fixed-width mantissa patterns ("00.###E0") similarly shift to expose min_integer_digits integer digits. The shift is exact for Decimal (via the %Decimal{exp: …} field) and lossless for Decimal-promoted floats/integers.

• New :engineering format atom resolving to "##0.######E0". CLDR ships no engineering pattern, so this is a Localize-supplied default — pass an explicit pattern string for different mantissa precision.

• Scientific-pattern emission now reads options.symbols.exponential, options.symbols.minus_sign, and options.symbols.plus_sign from the locale's CLDR data instead of hardcoding ASCII "E", "+", "-". ar/arab renders "أس" with Arabic Letter Mark signs, fa/arabext renders the "×۱۰^" superscripting form, ar/latn wraps signs with U+200E LRM.

• Localize.Number.Format.Compiler now normalises @-significant scientific patterns per TR35: "@@###E0" ≡ "0.0###E0", "@@@##E0" ≡ "0.00##E0", etc. The compiler rewrites these to the canonical 0-prefixed form so the runtime formatter does not need a separate @-aware path.

• New :exponent_style option on Localize.Number.to_string/2. :e (the default) emits the standard 1.234E3 form; :superscript emits 1.234 × 10³ using CLDR's superscriptingExponent symbol and Unicode superscript digits (⁰¹²³⁴⁵⁶⁷⁸⁹⁻⁺). Ignored for non-scientific patterns.

Fixed

• Localize.Utils.Math.round_significant/2 no longer crashes when called with a Decimal and n <= 0 or with a Decimal zero of any sign. Previously these reached :math.log10/1 deep in the Decimal square-root path and raised :invalid_operation; both cases now return the input unchanged.

• Localize.Number.Format.Compiler.compile/1 propagates compile-time errors from format_to_metadata/1 instead of crashing with MatchError.

[0.40.0] — June 1st, 2026

Changed

• Breaking: A bare relative :locale_cache_dir (no :otp_app set) is now refused at app start with Localize.LocaleCacheDirError — it resolved against the BEAM's CWD, which differs between mix tasks, mix test, and a release. Fix: add :otp_app to anchor the relative path, or use an absolute path.

Fixed

• Localize.Locale.Provider.locale_cache_dir/0 validates its configuration at app start (via Localize.Supervisor) and raises Localize.LocaleCacheDirError instead of silently reading from the wrong directory at runtime.

• Localize.Locale.LocaleDisplay.display_name/2 no longer raises FunctionClauseError on a BCP 47 generic extension carrying an odd number of subtags (e.g. cr-s-7b); the trailing singleton chunk now renders as a bare subtag.

Added

• New :otp_app config key. Three supported forms for the locale cache directory: (1) :otp_app only → Application.app_dir(<otp_app>, "priv/localize/locales"); (2) :otp_app + relative :locale_cache_dir → Application.app_dir(<otp_app>, <relative>); (3) absolute :locale_cache_dir → used verbatim, :otp_app ignored.

[0.39.0] — May 31st, 2026

Fixed

• Scope download_locales skip check to the configured cache dir, not the bundled fallback. Thanks to @allenwyma for the issue. Closes #35.

[0.38.0] — May 23rd, 2026

Added

• Localize.Locale.expand_locale_list/2 (and therefore the :supported_locales configuration) now accepts a Gettext backend module like MyApp.Gettext as an entry; it expands to Gettext.known_locales/1 with each returned string re-resolved through the existing POSIX-normalisation and likely-subtag canonicalisation path. The check uses Code.ensure_compiled/1 so the entry is safe to place in either config.exs or runtime.exs.

[0.37.0] — May 17th, 2026

Fixed

• Localize.DateTime.Formatter audit: removed remaining :gregorian / Calendar.ISO hardcoding. The {0} / {1} date-time placeholders now derive the CLDR calendar from the date instead of always asking for the gregorian pattern, ISO week-of-year (w / Y) prefers the date's own iso_week_of_year/3 callback before falling back to converting to Calendar.ISO, and iso_day/1's dead silent-fallback clause for unknown calendars was removed.

• Localize.Date.to_string/2 now honours CLDR number_system overrides carried alongside date patterns — Hebrew dates render in Hebrew numerals (י״ב באייר ה׳תשפ״ד), Japanese imperial year-1 renders as 元年, and numeric overrides like :arab transliterate per-field via the system's digit set. Algorithmic systems resolve through CLDR's numberingSystems.json to the right RBNF rule (:hebr → :hebrew, :jpanyear → :spellout-numbering-year-latn under :ja).

• Localize.Date.to_string/2 with a skeleton format (e.g. :yMMMM) against a non-Gregorian calendar no longer infinite-loops. Match.best_match/3 now receives the calendar explicitly and resolve_skeleton carries a seen set, terminating any residual match cycle.

• Localize.Date.to_string/2 now honours non-Gregorian calendars carried in the date's :calendar field — previously every call hard-coded :gregorian. A Date built with Calendrical.Japanese now formats as 平成12年1月1日 under :"ja-JP" instead of 2000/01/01.

• Localize.Calendar.localize/3 for :era now derives the correct era by delegating to the date's year_of_era/3 callback. Previously it always returned era 1, producing 白雉 (Hakuchi, AD 650) for every Calendrical.Japanese date.

• Localize.DateTime.Formatter y token now uses the calendar's calendar_year/3 (or year_of_era/3 as fallback) for non-Calendar.ISO dates, so era-relative year numbering — Heisei 12, Reiwa 6, AH 1420, BE 2543 — renders correctly.

• Localize.DateTime.Format.resolve_variant/2 now handles the CLDR %{format: pattern, number_system: ns} variant shape. Without this, locales whose date patterns carry a number_system override (Japanese jpanyear, Hebrew hebr) silently fell back to Gregorian.

[0.36.0] — May 15th, 2026

Fixed

• Fix currency_symbol: :none when processing options for Localize.Number.to_string/2.

[0.35.0] — May 14th, 2026

Fixed

• Localize.Unit.localize/2 and a list-of-units overload of Localize.Unit.to_string/2 close the parity gap with Cldr.Unit.localize/3: passing :usage to to_string/2 now resolves the locale-preferred unit set (territory derived from :locale via Localize.Territory.territory_from_locale/1), decomposes the value across it, and joins the parts with the locale's standard list pattern in a single call (e.g. Localize.Unit.to_string(Localize.Unit.new!(1.83, "meter"), usage: :person_height, locale: "en-US") returns {:ok, "6 feet and 0.047 inches"}).

• Localize.Unit.Conversion.convert/3 and Localize.Unit.decompose/2 now preserve Decimal precision end-to-end: Decimal inputs flow through Decimal arithmetic instead of round-tripping through float.

• Localize.Unit gains a :format_options struct field that localize/2 populates from the skeleton attribute on CLDR's unitPreferenceData (e.g. [round_nearest: 50] for usage: :road distances of 300 m+ in region 001). to_string/2 merges these per-unit options with caller-supplied options and forwards them to the number formatter, so a 311 m road distance now renders as "300 meters" rather than "311 meters". Caller-supplied options win on conflict; usages whose CLDR preferences carry no skeleton (e.g. person-height) are unchanged.

• Localize.Unit.Math.round/3 now accepts a rounding mode (:half_up default, plus :half_even, :half_down, :up, :down, :ceiling, :floor); float values are routed through Decimal so every mode produces consistent results. New Localize.Unit.Math.trunc/1 truncates toward zero with the same Decimal/float/integer dispatch as floor/1 and ceil/1.

• Localize.Unit.measurement_system_for_territory/2 accepts a category second argument: :default (existing behaviour), :temperature (e.g. :US → :us for Fahrenheit), or :paper_size (:US → :us_letter, :FR → :a4). The category-specific maps in CLDR's measurementData.json only enumerate territories whose category system differs from their default measurement system, so the lookup falls through to the default for any territory not listed in the category map.

• Localize.Unit.decompose/3 accepts an optional third format_options argument and stamps it on the trailing (smallest) decomposed unit; intermediate units whose integer part rounds to zero are now skipped, matching cldr_units' behaviour. This is what Localize.Unit.localize/2 uses internally to thread CLDR preference skeletons through to to_string/2.

• Localize.Unit.to_string/2 documents :grammatical_gender and :grammatical_case as accepted options, matching the naming used by Cldr.Unit.to_string/3. :grammatical_case selects a case-keyed pattern variant (existing functionality, now documented). :grammatical_gender is accepted for cldr_units API parity but only meaningful for compound-unit patterns; for simple units the gender is fixed by CLDR data and the option has no effect on output.

• Localize.Unit.Preference.preferred_units/2 documents :scope and :alt as forward-compatible placeholder options accepted but unused, matching cldr_units API surface. CLDR 48 ships no <unitPreference> carrying these attributes.

[0.34.0] — May 14th, 2026

Fixed

• Localize.Utils.Http now resolves the HTTPS trust store via :public_key.cacerts_get/0 before falling back to the existing cacertfile chain (configured path → CAStore → :certifi → well-known Unix paths). mix localize.download_locales previously failed on Windows because the resolver only searched Unix file paths even though the OS-native trust store was reachable. Thanks to @LostKobrakai for the report. Closes #30.

• Localize.Number.System no longer bakes the build host's absolute ETF path into its compiled BEAM which caused exceptions when the build host and deployment host were different. The lookup now happens at runtime via Application.app_dir/2 from a function body. Thanks to @neilberkman for the PR. Closes #28.

Added

• Localize.Supervisor is now a publicly documented module that owns the library's runtime supervision tree and runs the one-time post-start work (supplemental-atom interning, :supported_locales resolution). Consumers can keep the default OTP auto-start, or mark the dependency runtime: false and mount Localize.Supervisor directly under their own application supervisor. See the new guides/supervision.md for the full pattern.

[0.33.0] — May 13th, 2026

Changed

• Breaking: Localize.Message.Sigil is renamed to Localize.Message.Sigils to make room for additional MF2 sigils. Update any import Localize.Message.Sigil to import Localize.Message.Sigils.

Added

• Localize.Message.Sigils adds a new ~t sigil for compile-time MF2 translation. Elixir #{expr} interpolations are rewritten as MF2 {$name} placeholders with bindings derived automatically (fruit.name → fruit_name, String.upcase(x) → string_upcase, etc.), the canonical msgid is registered with Gettext for translation lookup, and modules opt in via use Localize.Message.Sigils, backend: MyApp.Gettext. Requires the backend to use Localize.Gettext.Interpolation.

• Localize.Gettext.Interpolation.skip_interpolation_sentinel/0 — public sentinel used by Localize.HTML.t/1 (and other markup-aware renderers) to retrieve a translated MF2 source without running the markup-stripping interpolation. Both runtime_interpolate/2 and compile_interpolate/3 short-circuit when this sentinel is passed as bindings.

Fixed

• Localize.Application.start/2 now eagerly reads every bundled supplemental dataset (languages, scripts, territories, variants, subdivisions, units, currency codes, calendars, timezones, territory subdivisions, locale ids, number systems) so the atoms they reference are interned at app start. The 0.30.0 atom-DOS hardening switched many lookups to binary_to_existing_atom, which assumes the legitimate atoms already exist. Without the eager-load, valid input like numberingSystem=arab could surface as a bogus "unknown numbering system" error on a fresh BEAM where no prior code path had triggered the relevant binary_to_term/1 read. Manifested as a transient CI failure in Localize.Message.NumberOptionsTest; cause was identical in shape to issue #26.

• Localize.default_locale/0 no longer hangs when LANG/LC_* hold values that fail validation (e.g. POSIX on minimal CI runners): the resolver pre-seeds the :persistent_term cache with :en before walking the env-var/app-config chain so a recursive locale lookup during warning formatting short-circuits, and the two warning sites now use a non-localised message to avoid the Exception.message/1 → Gettext-backend → get_locale/0 recursion that produced the original 60-second hang in localize_translate CI.

[0.32.0] — May 12th, 2026

Fixed

• mix localize.download_locales no longer evaluates config/runtime.exs of the consumer application. Previously the task ran Mix.Task.run("app.config"), which transitively evaluated runtime.exs, which was not necessary. The task now loads only compile-time config (config/config.exs and any imported env-specific file), matching the build-time contract its docstring already advertised. Thanks to @whatyouhide for the PR.

• Hardened two further sites that pattern-matched {:ok, _} = <fallible Localize call> and could have surfaced the same MatchError class as issue #26: the per-unit format loop in Localize.Duration.to_string/2 now short-circuits on the first formatter error, and Localize.Number.Formatter.Decimal's digit-transliteration step now uses with to fall through to untransliterated digits if either the requested or :latn number-system data is unavailable.

• New Localize.LintTest source-level lint that scans lib/ and fails the test suite if any file pattern-matches {:ok, _} = against a known-fallible Localize call. The list of fallible calls and an empty allowlist live in the test; future occurrences fail loudly on the offending PR rather than waiting for a runtime regression report.

• New Localize.Locale.FallbackResilienceTest exercises the load → store → get pipeline for seven representative regional locales under a provider that only serves :en, asserting that the data ends up under the canonicalised requested key and that provider.get/3 succeeds.

• New Mix.Tasks.Localize.DownloadLocalesTest calls DownloadLocales.banner/2 directly with default_locale: :"en-ZA" set, reproducing the exact scenario from issue #26 without invoking the network. banner/2 is now @doc false so the test can reach it.

• New Localize.AtomInterningTest exercises the public lookup paths that previously surfaced the supplemental-atom bug — Localize.Number.System.system_name_from/2 and friends, plus Localize.Currency.validate_currency/1, Localize.validate_calendar/1, Localize.validate_territory/1, Localize.validate_script/1 — each driven with binary input. A regression in intern_supplemental_atoms/0 would surface here as a structured error from one of these accessors.

[0.31.0] — May 12th, 2026

Fixed

• Localize.Locale.Loader now stores fallback locale data under the requested locale id rather than the resolved fallback id, restoring 0.29 behaviour. The regression introduced in 0.30.0 caused provider.get(requested_locale, _) to miss in-memory fallback data and surface as a spurious ItemNotFoundError — most visibly crashing mix localize.download_locales with a MatchError when default_locale named an unavailable locale. Locked down with test/localize/locale/loader_fallback_test.exs. Closes #26.

• mix localize.download_locales no longer pattern-matches on the result of Localize.Message.format/2 when building its progress banner; if formatting fails for any reason the task falls back to a plain ASCII banner and continues with the actual download.

Changed

• Localize.InvalidValueError gained an :allowed_values field and a new Localize.NoCertificateStoreError carries the searched paths; previously prose-stuffed :expected/:currency fields and bare-string :reason codes are now structural.

• Eight option-validation sites across Localize.Language, Localize.Script, Localize.Collation, Localize.Utils.Map, and Localize.Utils.Http now raise structured Localize exceptions rather than ArgumentError/RuntimeError.

[0.30.1] — May 12th, 2026

Fixed

• Revert the [:safe] option on :binary_to_term/2 since we cannot guarantee all the required atoms are materialized at application start. Thanks to @bigardone for the report. Closes #25.

[0.30.0] — May 12th, 2026

Security

• Localize.LanguageTag.parse/1 no longer calls String.to_atom/1 on raw parser output, closing an atom-table-exhaustion DOS vector on untrusted locale inputs. Atomisation is now gated behind the CLDR validity sets after alias resolution, and unrecognised language/script/territory subtags return Localize.InvalidSubtagError.

• Localize.Locale.to_locale_id/1 renamed to Localize.Locale.cldr_locale_id_from/1 and now returns {:ok, atom()} | {:error, Exception.t()}, gating atom creation behind Localize.validate_locale/1 and closing a second atom-table-exhaustion vector on locale inputs.

• Localize.Currency.validate_currency/1, territory_currencies/1, current_currency_for_territory/1, and the binary-code branch of currencies_for_locale/3's filter no longer atomise input before checking validity. Unknown currency or territory binaries are rejected via Helpers.existing_atom/1 and never grow the atom table.

• Localize.Script.display_name/2 and Localize.Unit.Formatter no longer atomise binary input before checking validity. Unknown script codes return Localize.UnknownScriptError without growing the atom table; the unit formatter's currency atomisation is gated as defence-in-depth behind the upstream Localize.Unit.validate_currency_codes/1 check.

• MF2 :list function and unit parser no longer atomise user-controlled binaries. The :list function's binary style= fallthrough now sets a sentinel atom that surfaces as an InvalidValueError in Localize.List, and SI prefix names are resolved through a compile-time lookup map (Localize.Unit.Data.si_prefix_atom/1) rather than String.to_atom/1 at parse time.

• Localize.Number.System (system_name_from/2, number_system_digits/1, to_system/2), Localize.Number.Symbol.number_symbols_for/2, and the datetime-formatter's time_preferences_for/1 no longer atomise user-supplied binary number-system or locale names before validation. Lookups go through Helpers.existing_atom/1 against pre-atomised CLDR data sets.

• Closed additional Atom DOS vectors in Localize.Locale.LocaleDisplay.display_name/2 (now routes through cldr_locale_id_from/1), Localize.Territory.Subdivision.display_name/2, the -u-co- and -u-kr- extension parsers in Localize.Collation.Options, and the redundant String.to_atom(to_string(...)) round-trip in plural-rule fallback.

• Closed three further atom-DOS sites called out by the security audit's findings 1.4 and 1.5: LocaleDisplay.U.find_exemplar_city/2 (-u-tz- IANA region/city splitter), LocaleDisplay.T.to_atom_safe/1 (-t- extension subtag normalisation), and Gettext.Interpolation.safe_to_atom/1 (missing-binding name reporting). All three previously fell through to String.to_atom/1 on a miss, which defeated the helper's name; they now return the original binary unchanged when no atom exists.

• Locale cache files and downloaded ETFs are decoded with :erlang.binary_to_term(_, [:safe]). Closes a node-crash vector for any deployment with :locale_cache_dir set to a writable directory: a malicious or corrupted cache file can no longer resurrect arbitrary atoms, funs, or refs. Failed safe decodes surface as LocaleNotFoundInCacheError (or LocaleDownloadError for the download path) and the file is treated as stale.

• Public parser entry points now reject oversized input before invoking the grammar, capping the parser's CPU exposure on hostile input. Defaults are 256 bytes for Localize.LanguageTag.parse/1 and Localize.Unit.Parser.parse/1, 64 KB for Localize.Message.Parser.parse/1, and 1 KB for Localize.Number.Parser.parse/2. Each cap is configurable via app env (:max_locale_id_bytes, :max_message_bytes, :max_unit_bytes, :max_number_bytes). Number.Parser.parse/2 additionally rejects Decimal results whose exponent magnitude exceeds :max_decimal_exponent (default ±100) so downstream multiplication or formatting cannot materialise huge mantissas.

• Localize.FormatCache ETS table switched from :public to :protected; writes are routed through the cache GenServer. The size cap (:format_cache_max_entries, default 2 000) is now enforced synchronously on each insert rather than by a 10-second sweeper, replacing the previous biased-random eviction that could leave the cache oversized. New Localize.FormatCache.clear/0 and size/0 helpers added for tests and maintenance.

• NIF (ICU bindings) hardened. All NIF entries except nif_plural_rule now run on the dirty CPU scheduler pool (ERL_NIF_DIRTY_JOB_CPU_BOUND); the collator pool is sized for schedulers + dirty_cpu_schedulers and reserve_coll refuses overflow rather than reading past the array end. The reorder-codes branch caps numCodes at 256 and checks enif_alloc before use; every std::stoll/std::stod/std::stoi is wrapped in try/catch so out-of-range C++ exceptions cannot unwind through the NIF boundary; the hand-rolled JSON arg parser guards each access after skip_ws; per-call input lengths are capped at the NIF boundary (MAX_MF2_BYTES = 64 KB, MAX_COLLATION_BYTES = 1 MB, MAX_NUMBER_STR_BYTES = 1 KB).

• Localize.Unit.CustomRegistry.load_file/1 now refuses to evaluate the file in :prod (or any environment without a loaded Mix module — typical for releases) unless config :localize, :allow_runtime_unit_files, true is explicitly set. Outside :prod the function works as before. The flag exists so an unintended feature switch in production cannot accidentally surface arbitrary code execution via Code.eval_file/1.

• :localize_locale_cache ETS table switched from :public to :protected, owned by Localize.Locale.Loader. Writes are routed through the owner via cast (so the hot validate path doesn't block and writes triggered from inside the owner's own handle_call cannot deadlock). Reads remain direct ETS lookups. Combined with the format cache fix above, both ETS caches are now :protected against multi-tenant or other-library interference.

• Localize.Utils.Http.get/2 and get_with_headers/2 now reject responses larger than 50 MB by default (configurable via :max_http_body_bytes app env or per-call :max_body_bytes option). Without the cap a malicious or compromised CDN could feed a multi-gigabyte response and OOM the BEAM. Oversized responses log an error and return {:error, :response_too_large}. Additionally, when peer certificate verification has been disabled (via LOCALIZE_UNSAFE_HTTPS), a one-time Logger.warning is emitted so a misconfigured production deployment cannot silently downgrade TLS without leaving an audit trail.

[0.29.0] — May 11th, 2026

Changed

• Localize.Currency.currency_for_code/2 now returns the new Localize.CurrencyNotLocalizedError (instead of UnknownCurrencyError) when the currency code is valid but the locale has no display data for it. UnknownCurrencyError is now reserved for codes that aren't recognised ISO 4217 or registered custom currencies.

Added

• Localize.Currency.currency_for_code/2 accepts a new :fallback option which walks the CLDR parent locale chain and the application default locale before failing. Thanks to @neilberkman for the PR.

• Localize.Locale.get/3 accepts a new :fallback_to_default option for a final-step fallback after any :fallback parent walk. Accepts true (use Localize.default_locale/0), or an atom/string/Localize.LanguageTag for a specific locale.

• Add :iso_3166 option to Localize.Territory.territory_codes/1 to return only ISO 3166 codes (not aggregate territories).

[0.28.0] — May 9th, 2026

Changed

• Localize.Interval.to_string/3 Date intervals (style :date, the default) now resolve their skeleton per-locale instead of using a hard-coded locale-independent mapping. The interval looks up Localize.DateTime.Format.date_formats(locale_id)[format] — the same mapping Localize.Date.to_string/2 uses — so date intervals follow the same conventions as single dates for the same :format. Visible effect on locales whose single-Date skeletons differ from the previous Interval table — most notably:
  • ja :medium is now numeric ("2012/01/05～2012/01/06"), aligning with single Date :medium ("2012/01/05"); was previously the abbreviated month form "2012年1月5日～6日". The richer Japanese-character form is now :long (matching single Date :long).
  • de :medium is now numeric ("15.01.2022 – 20.03.2022"); was previously the abbreviated month form. To get "15. Jan. – 20. März 2022" request the :yMMMd skeleton explicitly.
  • en :long uses full month name with no weekday ("January 5, 2012 – January 6, 2012"); was previously the :yMMMEd form "Thu, Jan 5 – Fri, Jan 6, 2012". The weekday now appears at :full. Per-locale skeletons that aren't shipped in CLDR's interval_formats data fall back to formatting each endpoint with Localize.Date.to_string/2 and joining via the locale's interval_format_fallback template. Non-:date styles (:month, :month_and_day, :year_and_month) remain locale-independent — they describe a deliberate field selection unrelated to standard date styles. The static Localize.Interval.date_styles/0 no longer includes a :date entry.

Fixed

• Strip zone token for NaiveDateTime too in Localize.Time.to_string/2 since they also do not have a time zone field. Relates to #22.

• Fix Localize.Interval.to_string/3 silently ignoring the :date_format option on Date-only intervals. The option now overrides :format on the date axis, mirroring the precedence used for :time_format on time intervals. Relates to #22.

• Fix Localize.Interval.to_string/3 raising Localize.DateTimeIntervalFormatError when called with format: :full on a Date interval. Relates to #22.

• Localize.Utils.Math.sqrt/2 now respects the current Decimal.Context.get/0 precision when called with a Decimal — the result is rounded to the configured precision and Newton's-method convergence scales accordingly.

• Added the test suite for Localize.Utils that are derived from the Cldr.Util equivalents.

[0.27.0] — May 8th, 2026

Fixed

• Fix Localize.Interval.to_string/3 :short time-interval format using the wrong hour cycle on 24-hour locales. :short now picks :hm or :Hm per the locale's preferred hour cycle (honouring any -u-hc- Unicode-extension override), matching the cycle used by Localize.Time.to_string/2 :short. Thanks to @woylie for the follow-up report. Fixes #22.

• Fix Localize.Time.to_string/2 silently ignoring the -u-hc- Unicode-extension override on the locale. The override now applies to both standard formats (:short/:medium/:long/:full) — remapped to the locale's cycle-appropriate :hm/:hms/:hmsv (12-hour, with the locale's AM/PM marker) or :Hm/:Hms/:Hmsv (24-hour) skeleton — and to user-supplied skeleton atoms like :Hms, where the hour symbols are substituted.

• Fix zone-field artefacts on %Time{} standard formats. A Time carries no zone information, so Localize.Time.to_string/2 now strips zone characters (z, Z, O, v, V, x, X) from the resolved skeleton ID before formatting. Localize.Time.to_string!(~T[21:00:00], format: :long, locale: :ja) returns "21:00:00" (was "21:00:00 " — trailing space), and :es :full returns "21:00:00" instead of "21:00:00 ()" (parens around the empty zone field).

• Adds support for Decimal version 3.0 to address a CVE. Thanks to @mitchellhenke for the PR.

Added

• Add Localize.Time.hour_format_from_locale/1 (and !/1) returning the locale's preferred hour cycle (:h11/:h12/:h23/:h24), honouring any -u-hc- Unicode-extension override.

[0.26.0] — May 6th, 2026

This release fixes user-reported bug #22 in time interval formatting and a number of RBNF conformance bugs arising from a more complete conformance testing process. The RBNF bugs have been around unreported and undiagnosed for many years.

Changed

• Breaking: The default Localize.Interval.to_string/3 format output (which is :medium) for time-only inputs now includes seconds. Localize.Interval.to_string!(~T[12:00:00], ~T[14:00:00], locale: :ja) shifts from 午後0時00分～2時00分 to 12:00:00～14:00:00. :en's :medium shifts from 12:00 – 2:00 PM to 12:00:00 PM – 2:00:00 PM. Users who relied on no-seconds output should explicitly pass time_format: :short.

Fixed

• Fix Localize.Interval.to_string/3 collapsing the :short, :medium, :long, and :full time styles to the same :hm skeleton on Time inputs. :short keeps CLDR's interval-format dispatch (collapsed AM/PM); :medium and above route through the locale's per-style time-format pattern, restoring per-style differentiation and including seconds in the default :medium output. Thanks to @woylie for the report. Fixes #22.

• Fix :time_format being silently ignored on Localize.Interval.to_string/3 for Time inputs. The option now takes precedence over :format, matching the precedence used on datetime intervals. Thanks to @woylie for the report. Fixes #22.

• Fix Localize.Interval.to_string/3 crashing with FunctionClauseError when called with a binary :format (or :time_format) on Time inputs. Binary patterns are now applied to both endpoints and joined via the locale's interval-format fallback template, matching the behaviour of datetime intervals. Thanks to @woylie for the report. Fixes #22.

• RBNF parser now distinguishes >> from >>> so CJK locales emit fractional digits without an inter-digit separator — Localize.Number.Rbnf.to_string(3.14, "spellout-numbering", locale: :zh) is 三点一四 instead of 三点一 四.

• RBNF leading and embedded zeros in fractional digits, and very small magnitudes, are now preserved — 0.05 en is "zero point zero five", 3.04 zh is 三点〇四, and 0.000001 en is "zero point zero zero zero zero zero one".

• RBNF 0.x special-base rule now matches when the integer part is zero and the value is non-zero, routing ko 0.5 spellout-numbering through its locale-correct sino-Korean 영점오 instead of the previous x.x-fallback 공점공오.

• RBNF negative floats no longer double their output or silently drop the sign — ko -0.5 spellout-numbering is -영점오 instead of 공점공점오, and locales that lack a -x rule now get an ASCII - prefix.

• RBNF integer <#,##0< quotient and float >%name> / >#,##0> / <%name< modulo and quotient no longer crash, completing case-clause coverage for every TR35 substitution-argument shape.

• RBNF $(cardinal,…) and $(ordinal,…) plural-keyed substitutions now use the requested locale's plural rules instead of hard-coding English — fr Localize.Number.Rbnf.to_string(21, "digits-ordinal-masculine", locale: :fr) is "21e" instead of "21er".

• RBNF fraction-with-rule numerator/denominator algorithm is now spec-correct — ky 1.5 spellout-cardinal is бир бүтүн ондон беш instead of бир бүтүн беш.

Added

• Add :minimum_significant_digits and :maximum_significant_digits options to Localize.Number.to_string/2.

• Localize.Number.Rbnf.to_string/3 now accepts Decimal inputs in addition to native integers and floats, with whole-valued Decimals routed through the integer path with no precision loss.

• RBNF >>> integer modulo now applies the source-preceding rule per TR35 §RBNF_Syntax, closing a latent gap; no current CLDR locale exercises this path.

[0.25.0] — May 1st, 2026

Fixed

• Fix en-CA :short date crash; teach :prefer about CLDR variant/standard alts. Thanks to @dabaer for the report. Closes #21.

Changed

• Module refactoring to remove many compile-time cycles.

[0.24.0] — April 29th, 2026

Fixed

• Localize.DateTime.Formatter stand-alone pattern helpers now pass context: :stand_alone to Localize.Calendar.localize/3 instead of an invalid type: option. Thanks to @timpritlove for the PR. Closes #20.

• Rename calendar :format/:stand_alone typespec and docs from :type to :context.

• Clarify Unit.display_name/2 vs to_string/2 in docs.

[0.23.0] — April 25th, 2026

Fixed

• Fix Cldr.Number.to_string/2 for Decimal numbers to produce the correct decimal digits.

• Fix LOCALIZE_UNSAFE_HTTPS env-var contract — values like "FALSE", "nil", an empty string, or unset all keep TLS verification on; only a truthy value disables it. Thanks to @rubas for the PR. Closes #15.

• Fix Localize.Locale.load/2 and Localize.Locale.get/3 to honor the :provider option — load/2 no longer calls provider.store/2 with the locale id, and get/3 now loads through the same provider it reads from. Thanks to @rubas for the PR. Closes #16.

• Localize.Locale.get/3 now honors the :fallback option by walking the CLDR parent locale chain when a key is missing in the requested locale. Fallback is handled in Localize.Locale so provider modules stay focused on store-and-fetch semantics. Thanks to @rubas for the PR. Closes #17.

• Public formatters (Localize.Date, Localize.Time, Localize.DateTime, Localize.DateTime.Relative, Localize.Interval, Localize.List, Localize.Calendar) now accept raw parsed Localize.LanguageTag structs whose :cldr_locale_id is not yet populated. The seven per-module locale resolvers collapse to one shared Localize.Locale.cldr_locale_id_from/1. Thanks to @rubas for the PR. Closes #18.

• Fix Localize.available_locale_id?/1, Localize.validate_calendar/1, and Localize.validate_number_system/1 to never intern caller-supplied strings as new atoms. Lookups now use compile-time string→atom maps for O(1) safe membership. Thanks to @rubas for the PR. Closes #19.

• Localize.supported_locales/0 now lazily resolves config :localize, supported_locales: [...] from the application environment when the :persistent_term cache has not yet been populated, instead of falling back to the full CLDR locale list. The cache is populated on application startup, but callers that run before the application has started — notably compile-time macro expansion in dependent applications like localize_web's ~q sigil — previously saw the full CLDR list during partial recompiles. This caused Localize.validate_locale/1 to best-match against all CLDR locales rather than the configured subset, producing incorrect cldr_locale_id resolutions.

[0.22.0] — April 22nd, 2026

Fixed

• Fix Cldr.Number.to_string/2 for Decimal numbers to produce the correct decimal digits.

[0.21.0] — April 22nd, 2026

Fixed

• Fix normalizing CLDR locale names to our standard atom format in Localize.validate_calendar/1.

• Localize.Calendar.iso_day_of_week/1 no longer crashes with MatchError on non-ISO calendars. The generic branch destructured calendar.day_of_week/4 as a 2-tuple but the Calendar behaviour returns {day, first, last}.

• Localize.Time.to_string/2 with a partial time and a standard format atom (:short/:medium/:long/:full) now derives a CLDR skeleton from the fields actually present (:h, :hm, :ms) instead of returning DateTimeUnresolvedFormatError.

• Localize.DateTime.to_string/2 no longer silently drops the hour when given a partial datetime such as %{year: _, month: _, day: _, hour: _} without :minute. Partial datetimes render via a split date + time path composed with the locale's datetime wrapper.

• Localize.DateTime.to_string/2 with hour + minute (no second) under :medium no longer emits a stray trailing : before the AM/PM marker — the partial path derives the :hm skeleton instead of using the full h:mm:ss a pattern with an empty seconds slot.

• The datetime formatter's AM/PM handler now accepts any map with :hour, not just maps that also have :minute.

• Localize.Number.to_string/2 now produces identical output for equivalent Decimal and float values. Previously Decimal.new("1234.56") rendered as "1,234.560" under the standard pattern because Decimal.round/3 returns a result padded to the requested scale; the formatter now normalizes after rounding so only the digits actually needed are emitted. Currency and other formats with a mandatory minimum scale still pad correctly via adjust_trailing_zeros/2.

[0.20.0] — April 22nd, 2026

Fixed

• Fixes mapping CLDR calendar types to the implementation module name.

[0.19.0] — April 19th, 2026

Fixed

• Restored the support of RBNF locales in Localize.Number.to_string/2. They are implemented in Localize.Number.Rbnf.to_string/1 but the delegation was lost on the ex_cldr transition. Thanks to @tangulip for the report. Closes #11.

[0.18.0] — April 18th, 2026

Changed

• Breaking: MF2 highlighter token class atoms renamed to match the tree-sitter capture taxonomy used by mf2_wasm_editor, so one stylesheet now styles both server-rendered HTML and the browser editor.

• Breaking: Localize.Message.to_html/2 now emits the new canonical class names with _ converted to - on output (.mf2-variable, .mf2-punctuation-bracket, .mf2-string-escape, .mf2-constant-builtin, etc.).

• Breaking: Localize.Message.to_ansi/2 default palette keys renamed to the new atoms.

Removed

• The mf2_theme_css/ directory and scripts/generate_mf2_themes.exs generator. Themes now live canonically in mf2_wasm_editor.

Fixed

• Localize.Gettext.Interpolation.runtime_interpolate/2 no longer raises Localize.ParseError when a translated string is not valid MF2. It now returns the message unchanged and logs a warning, matching gettext's own "fall back to the msgid" behaviour for missing translations. Dev-facing UI copy that happens to contain MF2-like syntax (e.g. {{…}} or .match) no longer crashes callers.

[0.17.0] — April 17th, 2026

Added

• mix format plugin Localize.Message.Formatter.Plugin. Canonicalises MF2 messages in ~M sigils and standalone .mf2 files. Enable by adding the plugin to .formatter.exs. See the "mix format plugin" section in the MessageFormat 2 guide.

[0.16.0] — April 17th, 2026

Fixed

• Fix locale download infinite recursion loop. Thanks to @woylie for the report. Closes #10.

[0.15.0] — April 17th, 2026

Added

• MF2 syntax highlighter. See Localize.Message.to_tokens/2, Localize.Message.to_html/2 and Localize.Message.to_ansi/2.

Fixed

• Fix the exception and message when formatting a number and specifying a number system that is not valid for the given locale.

[0.14.0] — April 16th, 2026

Changed

• Breaking: Remove @derive for Jason since Jason is no longer configured or used anywhere in the application.

Fixed

• Fix locale downloader to ensure it only uses the :cldr_locale_id field to construct the download URL.

[0.13.0] — April 15th, 2026

Fixed

• Localize.Interval.to_string/3 now correctly formats datetime intervals — matching ex_cldr_dates_times behaviour. Previously any interval between two datetime values was rendered as a date-only range, discarding the time portion. Now same-day intervals render as "Apr 8, 2026, 12:00 PM – 2:00 PM" (date once, time range) and different-day intervals render as "Apr 15, 2026, 12:49 AM – Apr 16, 2026, 1:49 AM" (full datetime on both sides). Time-only intervals (Time values on both sides) use the locale's time-interval patterns.

[0.12.0] — April 15th, 2026

Fixed

• Chinese collation tailorings (zh-u-co-pinyin, zh-u-co-stroke, zh-u-co-zhuyin) now produce correct locale-specific ordering for Han characters. .

• Han radical-stroke ordering (UAX #38) under -u-co-unihan now applies correctly. The Localize.Collation.Han module was previously orphaned — its data was never loaded in consumer apps and the sort path never consulted it. Radical data is now pre-generated in the build pipeline and shipped in priv/localize/collation_table.etf; the sort path invokes Han.collation_elements/1 for CJK codepoints when the :han_ordering option is :radical_stroke (set automatically for the -u-co-unihan collation type).

Added

• Localize.Collation.Options.han_ordering option — :implicit (default, UCA codepoint-based) or :radical_stroke (UAX #38). Automatically set to :radical_stroke for -u-co-unihan locales.

• Persistent-term cache for parsed tailorings. First call to Tailoring.get_tailoring/2 parses the rule string (~70 ms for zh-pinyin); subsequent calls read from persistent_term in microseconds.

• Differential tests for zh-u-co-pinyin, zh-u-co-stroke, zh-u-co-zhuyin, and ja-u-co-unihan that assert output differs from root codepoint order for specific character pairs — guards against silent regressions.

Changed

• Localize.Collation.Han is no longer a GenServer. Radical data is loaded alongside the main collation table by Localize.Collation.Table (one ETF, one load step).

[0.11.0] — April 14th, 2026

Added

• Localize.Interval.to_string/3 now accepts nil for either the from or to endpoint to format an open interval (e.g. "Jan 1, 2020 –" or "– Jan 1, 2020").

• New guide: Interval and Duration Formatting — covers Localize.Interval (including open intervals) and Localize.Duration (calendar-unit strings and numeric time strings) in one place.

[0.10.0] — April 14th, 2026

Changed

• Mix tasks now only do Mix.Task.run("app.config") followed by Application.ensure_all_started(:localize), avoiding starting any consumer application. Thanks to @lostkobrakai for the report. Closes #7,

[0.9.0] — April 14th, 2026

Changed

• Localize.Unit.Math.mult/2 and Localize.Unit.Math.div/2 now factor operands that share the same base dimension.

[0.8.0] — April 14th, 2026

Added

• Localize.Message.format_to_safe_list/3 and format_to_safe_list!/3 — new MF2 formatting entry points that preserve markup structure instead of stripping it.

[0.7.0] — April 14th, 2026

Changed

• Territory subdivision functions are now in the Localize.Territory.Subdivision module. Some functions have been renamed, see Localize.Territory.Subdivision. The translate functions have been removed.

[0.6.0] — April 13th, 2026

Added

• Public function wrappers in Localize.Unit.Math for all dimensionless functions: sin/1, cos/1, tan/1, asin/1, acos/1, atan/1, sinh/1, cosh/1, tanh/1, asinh/1, acosh/1, atanh/1, exp/1, ln/1, log/1, log2/1. Previously these were only accessible via apply_dimensionless/2.

Fixed

• apply_dimensionless/2 now validates that the unit is actually dimensionless before computing. Previously sin(1 meter) would silently return a result; it now returns {:error, "sin requires a dimensionless value, got unit with base: meter"}. Units must reduce to revolution (angles) or part (ratios) to be accepted.

[0.5.0] — April 13th, 2026

Added

• :special conversion support in CustomRegistry. Custom units can now be registered with factor: :special plus :forward and :inverse {module, function} tuples for nonlinear conversions. This enables logarithmic scales (decibels), temperature functions, density hydrometers, wire gauges, and other conversions that cannot be expressed as value * factor + offset.

• Conversion.do_convert/3 now uses a generalised special_unit/1 lookup that checks both CustomRegistry and a compiled @built_in_special map, replacing the previous hardcoded :beaufort pattern match.

[0.4.0] — April 13th, 2026

Fixed

• Localize.all_locale_ids/1 (:modern, :moderate, :basic) now returns the correct expanded list of locales. Thanks to @cw789 for the report.

[0.3.0] — April 13th, 2026

Fixed

• Load custom units in a single batch to avoid churning :persistent_store

[0.2.0] — April 13th, 2026

Fixed

• SI prefix parsing for custom units. Custom units can now be prefixed with SI prefixes and power prefixes.

Changed

• Custom unit category validation relaxed from a fixed allowlist to any non-empty string. The faciliates importing a broader range of unit definitions such as those from Gnu units.

[0.1.0] — April 13th, 2026

Initial release.

Highlights

• Full CLDR v48.2 locale data with lazy runtime loading from ETF files cached in :persistent_term. No compile-time backend configuration required.

• Number formatting — integers, decimals, percentages, currencies, ranges, and rule-based number formats (RBNF) including Roman numerals and CJK ideographs.

• Date, time, and datetime formatting using CLDR calendar patterns with :short, :medium, :long, and :full styles, custom skeleton patterns, and interval formatting.

• Unit formatting with plural-aware patterns, SI/binary prefixes, compound units, measurement system conversion, custom unit registration, and Localize.Unit.Operators for natural arithmetic (km + m).

• List formatting with locale-appropriate conjunctions, disjunctions, and unit list styles. Per-element formatting via Localize.Chars.

• ICU MessageFormat 2 (MF2) parser and interpreter with custom function registry, offset selection, JSON interchange, and bidirectional text support.

• Gettext integration — Localize.Gettext.Interpolation provides MF2-based interpolation for Gettext backends.

• Localize.Chars protocol — polymorphic locale-aware formatting with built-in implementations for 14 types and Any fallback to Kernel.to_string/1.

• Currency metadata, ISO 4217 validation, custom currency registration (private-use and extended codes), and territory-to-currency mapping.

• Display names for territories, languages, scripts, calendars, and full locale display names per the CLDR algorithm.

• Unicode Collation Algorithm (UCA) with CLDR locale-specific tailoring for 97 languages, including digraph expansion and script reordering.

• BCP 47 / RFC 5646 language tag parser with full Unicode extension support (-u-, -t-), locale distance matching, and parent chain resolution.

• On-disk locale cache with HTTPS download provider, version-based staleness detection, and mix localize.download_locales for build-time cache population.

• Optional NIF backend for faster Unicode normalisation and collation sort-key generation.

• Calendar data for all CLDR calendar systems including Buddhist, Hebrew, Islamic (5 variants), ROC, Indian, Persian, Coptic, Ethiopic, Chinese, Japanese, and Dangi.

• All public API functions return a standardized {:error, exception} (except bang variants). The exception is a standard Elixir exception struct populated with semantic information about the error. The error message can be returned by Exception.message(exception). The exception messages are all Gettext messages using the MF2 format and can be localized.

See the README for full documentation, configuration options, and usage examples.