Localize.Date.strptime/3, Localize.Time.strptime/3 and Localize.DateTime.strptime/3 read text written with a Calendar.strftime/3 format, the %Y-%m-%d family of directives that C's strftime(3) and strptime(3), Python, Ruby and Elixir share. Each translates the format into the CLDR pattern Localize's parsers read with, through Localize.DateTime.Strptime.pattern/2, and reads the text with parse/2 in the locale given. Nothing is read here that parse/2 could not read with a pattern; what the functions add is the format you already have, and the round trip with Calendar.strftime/3.
This guide lists the directives, then says where the reading matches what strptime(3) and Calendar.strftime/3 lead you to expect, and where it does not. Every result shown was produced by the code.
Quick start
iex> Localize.DateTime.strptime("2026-03-04T07:05:09", "%Y-%m-%dT%H:%M:%S", locale: :en)
{:ok, ~N[2026-03-04 07:05:09]}
iex> Localize.Date.strptime("4 mars 2026", "%e %B %Y", locale: :fr)
{:ok, ~D[2026-03-04]}
iex> Localize.Time.strptime("7:05 PM", "%I:%M %p", locale: :en)
{:ok, ~T[19:05:00]}
iex> Localize.DateTime.strptime("2026-03-04 07:05 +0530", "%Y-%m-%d %H:%M %z", locale: :en)
{:ok, DateTime.new!(~D[2026-03-04], ~T[07:05:00], "+05:30", Localize.TimeZoneDatabase)}The round trip with Calendar.strftime/3, whose month, weekday and day-period names Localize.Calendar.strftime_options!/1 supplies for a locale:
iex> strftime_options = Localize.Calendar.strftime_options!(locale: :de)
iex> written = Calendar.strftime(~N[2026-03-04 19:05:09], "%A, %d. %B %Y, %H:%M", strftime_options)
"Mittwoch, 04. März 2026, 19:05"
iex> Localize.DateTime.strptime(written, "%A, %d. %B %Y, %H:%M", locale: :de)
{:ok, ~N[2026-03-04 19:05:00]}The translation alone, for a pattern to use with parse/2 or to_string/2:
iex> Localize.DateTime.Strptime.pattern("%d %B %Y at %I:%M %p")
{:ok, "dd MMMM y 'at' hh:mm a"}Directives
Every directive Calendar.strftime/3 writes is read but %s and %u, which no pattern field carries, and so are the C directives that read the same text. Padding and width modifiers (%-d, %_m, %05Y) are accepted and ignored, since every field is read at any width.
| Directive | Reads | Pattern | Notes |
|---|---|---|---|
%a, %A | A weekday name in the locale | EEE, EEEE | Either width reads with either directive. |
%b, %h, %B | A month name in the locale | MMM, MMMM | Either width reads with either directive. |
%c, %x, %X | The preferred date and time, date, or time | the :preferred_* option | Defaults as Calendar.strftime/3 has them. |
%d, %e | The day of the month | dd, d | Padded or not. |
%f | A fraction of a second | SSSSSS | Any number of digits, kept as precision. |
%H, %k | The hour, 0 to 23 | HH, H | |
%I, %l | The hour, 1 to 12, with %p | hh, h | |
%j | The day of the year | DDD | |
%m | The month | MM | |
%M | The minute | mm | |
%p, %P | The day period, AM or PM, in the locale | a | Either case, and forms such as "p.m.". |
%q | The quarter, 1 to 4 | Q | |
%S | The second | ss | |
%y | A two-digit year | yy | See below. |
%Y | The year, with a sign | y | Up to four digits. |
%z | A UTC offset | xx | "+0530" and "+05:30" both read. |
%Z | A time zone name CLDR gives the locale | zzzz | Needs a time zone database; see below. |
%D, %F, %T, %R | %m/%d/%y, %Y-%m-%d, %H:%M:%S, %H:%M | as composed | |
%n, %t | A run of spaces | a space | Not a tab or a newline; see below. |
%% | A percent sign | % |
Any other letter in the format is literal text, quoted in the pattern, so "%Y-%m-%dT%H:%M" becomes y-MM-dd'T'HH:mm.
Where the reading is what you expect
Unpadded fields and runs of spaces.
"2026-3-4 7:05"reads with"%Y-%m-%d %H:%M", asstrptime(3)reads it: a numeric directive takes one or two digits, and a space in the format matches a run of spaces in the text.Names in either width, in any case.
%breads "March" and%Breads "Mar", asstrptime(3)does;%preads "PM", "pm" and "p.m.".Offsets in either form.
%zreads "+0530" and "+05:30", as glibc'sstrptime(3)does, and resolves to aDateTime.t/0in that fixed offset.%c,%xand%Xstand for the:preferred_datetime,:preferred_dateand:preferred_timeoptions, with the same defaults asCalendar.strftime/3,"%Y-%m-%d %H:%M:%S","%Y-%m-%d"and"%H:%M:%S", and the same rule that a preferred format may not itself contain them.The round trip with
Calendar.strftime/3. Every directive it writes but%sand%uis read, so text it writes with any other format and the namesLocalize.Calendar.strftime_options!/1supplies for a locale reads back with the same format in that locale. The suite checks this for English, German, French, Spanish and Japanese.Padding and width modifiers are accepted and ignored, as
strptime(3)largely ignores them on input.Partial text reads with
as: :map, asparse/2reads it, which is the rolestrptime(3)'s partly filledtmplays:Localize.Date.strptime("2026-03", "%Y-%m", locale: :en, as: :map)is{:ok, %{calendar: Calendar.ISO, year: 2026, month: 3}}.Errors are returned, never raised. An unreadable directive is
{:error, %Localize.DateTimeFormatError{reason: :unsupported_directive}}naming the directive in:detail, before any text is read; text the format does not match is the errorparse/2returns.Calendar.strftime/3raisesArgumentErrorfor a directive it does not know.
Where it is not
A space,
%nand%tmatch spaces, not any whitespace.strptime(3)matches any run of white space for a space,%nor%tin the format; here each matches a run of spaces, and a tab or a newline in the text reads only where the format has that character itself:"2026-03-04\t07:05"reads with"%F\t%R"and not with"%F %R"or"%F%t%R".The whole string must match.
strptime(3)stops at the end of the format and hands back the rest of the text; here text after the format is an error."2026-03-04 07:05 and more"does not read with"%Y-%m-%d %H:%M".A two-digit year falls in a window, not at POSIX's pivot.
%yresolves into the eighty years before and twenty years after the reference date, today or:reference_date, asparse/2resolves a two-digit year. POSIX pivots at 69: 69 to 99 are 1969 to 1999 and 00 to 68 are 2000 to 2068. With a reference date in 2026 the window is 1946 to 2045, so the two agree from 00 to 45 and from 69 to 99 and differ from 46 to 68: "50" is 1950 here and 2050 for POSIX.The locale is the
:localeoption, not the process'sLC_TIME. The names of the C locale are the:enlocale's;"4 mars 2026"reads withlocale: :fr.%Zneeds a time zone database. A zone name, "PST", "Pacific Standard Time" or "Europe/Paris", resolves to aDateTime.t/0in that zone through the database configured forCalendar, withtzortzdata, asparse/2resolves it. Without one the zone is dropped and the result is aNaiveDateTime.t/0. The names read are the ones CLDR gives the locale, its long and short zone names such as "Pacific Standard Time" and "PST", and the IANA identifiers; the abbreviationsCalendar.strftime/3takes from the time zone database, "IST", "AEDT" or "JST", are not all among them, so a round trip through%Zis not assured where one through%zis.%zneeds no database.%pmust agree with%H.strptime(3)ignores%pwhen%Hgives the hour; here a day period that contradicts the 24-hour clock is an error:"19:05 PM"reads with"%H:%M %p"and"07:05 PM"does not. Use%Iwith%p.A weekday is checked against the date. glibc ignores
%aand%Aon input; here"Wed 2026-03-05"does not read with"%a %Y-%m-%d", because 5 March 2026 is a Thursday.A year has at most four digits.
%Yreads a sign, so"-0001-01-01"is~D[-0001-01-01], but a fifth digit does not read.Each function reads the fields its shape has.
Localize.DateTime.strptime/3wants a date and a time in the format,Localize.Date.strptime/3a date,Localize.Time.strptime/3a time, as the threeparse/2functions do. A date-only format given toLocalize.DateTime.strptime/3is aLocalize.DateTimeFormatError.t/0, and a time in a format given toLocalize.Date.strptime/3is at:Localize.DateTimeInvalidInputError.t/0naming the fields the shape lacks.Directives Localize does not read are an error naming the directive:
%s, seconds since the epoch, which no pattern field carries;%uand%w, the weekday as a number, since CLDR numbers weekdays by the locale's first day of the week where C counts from Monday or Sunday;%U,%W,%V,%Gand%g, the week of the year and the week-based year, for the same reason;%C, the century; and the%Eand%Omodifiers of POSIX locales.
Options
:preferred_datetime,:preferred_dateand:preferred_timeare the strftime formats%c,%xand%Xstand for.Every option of
parse/2but:format::locale,:calendar,:reference_dateand:as;Localize.Time.strptime/3has no use for:reference_dateand ignores it, asLocalize.Time.parse/2does.
Errors
{:error, %Localize.DateTimeFormatError{reason: :unsupported_directive, detail: directive}}for a directive Localize does not read, or%c,%xor%Xinside a preferred format, with the whole format in:format.{:error, %Localize.InvalidValueError{}}for a format or a preferred format that is not a UTF-8 string, or options that are not a keyword list.The error
parse/2returns where the text does not match the format: aLocalize.DateParseError.t/0,Localize.TimeParseError.t/0orLocalize.DateTimeParseError.t/0.