Localized values

Sites often need to show a count or measured value in prose. Writing commas, spaces, or decimal separators in a template makes that presentation belong to one language. format_number() keeps the value numeric until Heine formats it for the locale currently being rendered.

{{ format_number(value=1234567.89) }}

For example, this renders as 1,234,567.89 in en-US and 1.234.567,89 in de-DE. Heine uses bundled locale data rather than the operating system locale, so the same checked build produces the same text on every machine.

Template numbers

format_number() accepts a finite template number and these optional keyword arguments:

{{ format_number(
  value=data.measurement,
  grouping=false,
  minimum_fraction_digits=2,
  maximum_fraction_digits=2,
) }}

Grouping defaults to true. The minimum defaults to 0; the maximum defaults to 3. Heine rounds to the requested maximum with round-half-to-even and then pads to the requested minimum. For example, at two fraction digits, 2.345 renders as 2.34 and 2.355 as 2.36. This deliberately differs from the half-expand behavior many authors know from JavaScript formatting.

Both fraction-digit values must be integers from 0 through 32768, which is the precision limit of Heine's checked decimal representation. The minimum must not exceed the maximum. If a requested minimum exceeds the default maximum of 3, set maximum_fraction_digits explicitly to at least that minimum. A single request can deliberately produce 32,768 fractional digit positions, so avoid gratuitous padding in repeated template output. Heine never allocates output from an unchecked template value.

Heine converts floating-point inputs through their shortest round-trippable decimal text before it rounds them. It does not multiply a binary float to implement decimal precision. Integers remain exact at the template boundary. Numbers must be finite: a NaN or infinity input fails with number must be finite. Negative values retain their sign, including -0 from a template float.

Locale ownership

The two rendering boundaries deliberately choose their locale from different sources:

Where a value is formattedLocale Heine uses
format_number(), format_date(), format_time(), or format_datetime() in a templateThe locale of the page being rendered
A Fluent placeable, NUMBER(), or DATETIME() inside t()The locale of the bundle that supplied the resolved message

The second rule keeps a fallback message coherent. An English fallback message on a German page retains English prose, grammar, digits, and date conventions.

Fluent messages

Pass a number directly to t(). A bare Fluent placeable formats it in the locale of the Fluent bundle that supplied the resolved message:

post-count = { $count ->
   [one] One post
  *[other] { $count } posts
}
{{ t(id="post-count", count=posts.count) }}

Use Fluent's built-in NUMBER() when the translation needs a different presentation:

download-size = Download size: { NUMBER($size, maximumFractionDigits: 1) }

NUMBER() accepts the three checked decimal presentation options useGrouping, minimumFractionDigits, and maximumFractionDigits. It rejects other options instead of silently ignoring them. Heine formats both a bare placeable and NUMBER() with the same bundled locale data as format_number().

Fluent uses f64 for its selector engine. Before t() passes a numeric value to Fluent, Heine verifies that the number survives that conversion exactly. A large integer that Fluent cannot distinguish from a neighboring integer is a template error. Format such a value directly with format_number() instead.

Plural messages

Fluent selects plural variants from Heine's checked default decimal before it writes locale digits or separators. That policy rounds half to even with at most three fractional digits and no forced trailing zeros, so 1.0004 selects as 1. Keep a selector's numeric presentation at that default policy when the same value appears through NUMBER(). Heine rejects a different fraction-digit policy in that message or in any message or term it references, because it could display a plural operand that disagrees with the selector. If a message needs a differently rounded display value, the template author must pass a separate argument with that intended meaning.

For numeric values, Heine currently formats decimal values only. Percentages, currencies, units, compact notation, and relative dates have distinct semantics and remain out of scope. The deferred percentage and currency record explains why those APIs wait for stable formatter support.

Dates and times

format_date() presents a calendar date. It also accepts an RFC 3339 instant, then selects that instant's calendar date in the configured site.time_zone. This keeps a published page on its authored editorial day:

<time datetime="{{ page.published }}">
  {{ format_date(value=page.published, style="long") }}
</time>

format_time() and format_datetime() accept an RFC 3339 instant only. A calendar date has no time, so Heine rejects it rather than assuming midnight. Both functions use the site's editorial time zone and the locale of the page:

{{ format_time(value=data.event.starts_at, style="short") }}
{{ format_datetime(
  value=data.event.starts_at,
  date_style="long",
  time_style="short",
) }}

Every style is short, medium, or long; medium is the default. A combined value chooses its date and time styles separately. These styles do not add a time-zone label, so a rendered time implies the site's configured editorial time zone. Per-event time zones are not supported: write an event's zone in surrounding localized prose when it differs from that editorial policy.

Fluent messages use DATETIME() with the equivalent camel-case option names:

event-time = Starts at { DATETIME($when, timeStyle: "short") }.
event-date-time = Starts at { DATETIME($when, dateStyle: "long", timeStyle: "short") }.
{{ t(id="event-time", when=data.event.starts_at) }}

DATETIME() requires a value variable and one or both of dateStyle and timeStyle. Heine checks the function's options while it loads Fluent resources, then checks the supplied value when the selected message renders. Like numeric values, dates and times follow the locale of the Fluent message that supplies them after fallback. An English fallback message on a German page therefore keeps English date and time conventions. Heine never uses the host time zone, a browser setting, or the current clock.

Heine accepts ISO calendar dates and formats them through its ISO/Gregorian calendar model. Alternative calendars and locale extensions that select them remain outside this formatter contract.