Format values for a locale
Format numbers, dates, lists, and text with native Intl while supplying the units and time information the display needs.
Translated messages still contain values: prices, dates, quantities, and lists. A Lingo object formats those values using its active locale, without looking them up in a catalog. Use the same object that renders the surrounding message so both follow the same locale.
Numbers and quantities #
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const price = l.currency(29.99, "USD");
const completion = l.percent(0.125, { maximumFractionDigits: 1 });
const temperature = l.unit(32, "celsius", { unitDisplay: "long" });The price formats the supplied US-dollar amount; it does not convert currencies. The percentage input is a ratio, so 0.125 displays as 12.5%, while 12.5 would mean 1250%. Likewise, the unit helper labels the supplied Celsius value without converting it.
| Method | Parameters after the value |
|---|---|
num(value: number) | Optional Intl.NumberFormatOptions. |
currency(value: number, currency: string) | Currency code, then optional number-format options. |
percent(value: number) | Optional number-format options. |
unit(value: number, unit: string) | Unit identifier, then optional number-format options. |
compact(value: number) | Optional number-format options. |
fileSize(bytes: number) | No options. |
All return strings. Currency, percent, and unit methods enforce their named style; compact enforces compact notation after applying the other options.
fileSize divides by powers of 1024 and uses fixed labels B, KB, MB, GB, TB, and PB. It uses the locale for the number, with no fractional digits for bytes and at most one for larger units. 1024 becomes 1 KB; zero is 0 B. Supply a nonnegative integer byte count. Negative and fractional-byte inputs do not have a useful display policy, and labels such as GB are not translated into French Go.
Dates, times, and relative offsets #
const instant = new Date("2026-10-10T12:00:00Z");
const timestamp = l.datetime(instant, { timeZone: "UTC" });
const date = l.date(instant, {
year: "numeric",
month: "2-digit",
day: "2-digit",
timeZone: "UTC",
});
const age = l.relative(-3, "day", { numeric: "auto" });These calls use the l from the previous example. date, time, and datetime accept Date | number, followed by optional Intl.DateTimeFormatOptions. Numeric timestamps are milliseconds, not Unix seconds. Their defaults are medium date, short time, and both, respectively.
Supplying individual fields such as year or hour suppresses the default styles. Explicit style options can override defaults, but incompatible combinations of styles and individual fields can make native Intl throw. Set a timezone when a server and browser must show the same date.
relative(value, unit, options?) accepts a signed number, an Intl.RelativeTimeFormatUnit, and optional Intl.RelativeTimeFormatOptions. It formats the offset you provide. Calculate the difference from a reference instant in application code and update it when needed; the method does not read the clock or schedule updates.
Lists and text operations #
| Method | Result and behavior |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | A string joining already selected labels; conjunction is the default. |
displayName(code, type) | A localized name or undefined; type is language, region, script, or currency. Native fallback may return the code itself. |
sort(items: string[], options?: Intl.CollatorOptions) | A new array ordered by locale collation; the input stays unchanged. |
segment(text, granularity?) | String segments, using grapheme by default or word/sentence. Word mode includes whitespace segments. |
displayName catches native errors and returns undefined. The other methods do not share that catch behavior. Validate locale codes and options where they enter your application.
Match the runtime you support #
These helpers delegate to native NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator, and Segmenter. The package does not replace missing native APIs or supply every runtime's locale data.
Test representative values in the server and browsers you support. Punctuation and conventions can vary with ICU data. For hydration, keep the timestamp, timezone, and relative-time reference consistent as well as the locale.