Intlayer Formatters

Overview

Intlayer provides a set of lightweight helpers built on top of the native Intl APIs, plus a cached Intl wrapper to avoid repeatedly constructing heavy formatters. These utilities are fully locale-aware and can be used from the main intlayer package.

Cached Intl

The exported Intl is a thin, cached wrapper around the global Intl. It memoises instances of NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator, and PluralRules, which avoids rebuilding the same formatter repeatedly.

Because formatter construction is relatively expensive, this caching improves performance without changing behaviour. The wrapper exposes the same API as the native Intl, so usage is identical.

• Caching is per process and transparent to callers.

If Intl.DisplayNames is not available in the environment, a single dev-only warning is printed (consider a polyfill).

Examples:

import { Intl } from "intlayer";// Number formattingconst numberFormat = new Intl.NumberFormat("en-GB", {  style: "currency",  currency: "GBP",});numberFormat.format(1234.5); // "£1,234.50"// Display names for languages, regions, etc.const displayNames = new Intl.DisplayNames("fr", { type: "language" });displayNames.of("en"); // "anglais"// Collation for sortingconst collator = new Intl.Collator("fr", { sensitivity: "base" });collator.compare("é", "e"); // 0 (equal)// Plural rulesconst pluralRules = new Intl.PluralRules("fr");pluralRules.select(1); // "one"pluralRules.select(2); // "other"

Locale Utilities

getLocaleFromPath(inputUrl)

Extracts the locale segment from a URL or pathname:

import { getLocaleFromPath } from "intlayer";getLocaleFromPath("/en/dashboard"); // "en"getLocaleFromPath("/fr/dashboard"); // "fr"getLocaleFromPath("/dashboard"); // "en" (default locale)getLocaleFromPath("https://example.com/es/about"); // "es"

• inputUrl: The complete URL string or pathname to process
• returns: The detected locale or default locale if no locale is found

getPathWithoutLocale(inputUrl, locales?)

Removes the locale segment from a URL or pathname:

import { getPathWithoutLocale } from "intlayer";getPathWithoutLocale("/en/dashboard"); // "/dashboard"getPathWithoutLocale("/fr/dashboard"); // "/dashboard"getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"

• inputUrl: The complete URL string or pathname to process
• locales: Optional array of supported locales (defaults to configured locales)
• returns: The URL without the locale segment

getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)

Generates a localised URL for the current locale:

import { getLocalizedUrl } from "intlayer";getLocalizedUrl("/about", "fr", ["en", "fr"], "en", false); // "/fr/about"getLocalizedUrl("/about", "en", ["en", "fr"], "en", false); // "/about"getLocalizedUrl("https://example.com/about", "fr", ["en", "fr"], "en", true); // "https://example.com/fr/about"

• url: The original URL to localise
• currentLocale: The current locale
• locales: Optional array of supported locales (defaults to configured locales)
• defaultLocale: Optional default locale (defaults to configured default locale)
• prefixDefault: Whether to prefix the default locale (defaults to configured value)

getHTMLTextDir(locale?)

Returns the text direction for a locale:

import { getHTMLTextDir } from "intlayer";getHTMLTextDir("en-US"); // "ltr"getHTMLTextDir("ar"); // "rtl"getHTMLTextDir("he"); // "rtl"

• locale: The locale to get the text direction for (defaults to current locale)
• returns: "ltr", "rtl", or "auto"

Content Handling Utilities

getContent(node, nodeProps, locale?)

Transforms a content node with all available plugins (translation, enumeration, insertion, etc.):

import { getContent } from "intlayer";const content = getContent(  contentNode,  { dictionaryKey: "common", dictionaryPath: "/path/to/dict" },  "fr");

• node: The content node to transform
• nodeProps: Properties for the transformation context
• locale: Optional locale (defaults to configured default locale)

getTranslation(languageContent, locale?, fallback?)

Extracts content for a specific locale from a language content object:

import { getTranslation } from "intlayer";const content = getTranslation(  {    en: "Hello",    fr: "Bonjour",    de: "Hallo",  },  "fr",  true); // "Bonjour"

• languageContent: Object mapping locales to content
• locale: Target locale (defaults to configured default locale)
• fallback: Whether to fallback to the default locale (defaults to true)

getIntlayer(dictionaryKey, locale?, plugins?)

Retrieves and transforms content from a dictionary by key:

import { getIntlayer } from "intlayer";const content = getIntlayer("common", "fr");const nestedContent = getIntlayer("common", "fr", customPlugins);

• dictionaryKey: The key of the dictionary to retrieve
• locale: Optional locale (defaults to configured default locale)
• plugins: Optional array of custom transformation plugins

getIntlayerAsync(dictionaryKey, locale?, plugins?)

Asynchronously retrieves content from a remote dictionary:

import { getIntlayerAsync } from "intlayer";const content = await getIntlayerAsync("common", "fr");

• dictionaryKey: The key of the dictionary to retrieve
• locale: Optional locale (defaults to configured default locale)
• plugins: Optional array of custom transformation plugins

Formatters

All helpers below are exported from intlayer.

percentage(value, options?)

Formats a number as a percentage string.

Behaviour: values greater than 1 are interpreted as whole percentages and normalised (e.g., 25 → 25%, 0.25 → 25%).

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }

Examples:

import { percentage } from "intlayer";percentage(0.25); // "25%"percentage(25); // "25%"percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"

Additional Intl Features

number(value, options?)

Formats a numeric value using locale-aware grouping and decimals.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }

number(123456.789); // "123,456.789" (in en-US)number("1000000", { locale: "fr" }); // "1 000 000"number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"

percentage(value, options?)

Formats a number as a percentage string. Values greater than 1 are normalised (e.g., 25 → 25%, 0.25 → 25%).

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }

percentage(0.25); // "25%"percentage(25); // "25%"percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"

currency(value, options?)

Formats a value as localised currency. Defaults to USD.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }
  • Common: currency, currencyDisplay ("symbol" | "code" | "name")

currency(1234.5, { currency: "EUR" }); // "€1,234.50"currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"

date(date, optionsOrPreset?)

Formats a date/time value.

• date: Date | string | number
• optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } or preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"

date(new Date(), "short"); // e.g., "08/02/25, 14:30"date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

relativeTime(from, to?, options?)

Formats relative time between two instants.

• from: Date | string | number
• to: Date | string | number (defaults to new Date())
• options: { locale?, unit?, numeric?, style? }

const now = new Date();const in3Days = new Date(now.getTime() + 3 * 864e5);relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"

units(value, options?)

Formats a numeric value with a unit.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }
  • Common: unit (e.g., "kilometer", "byte"), unitDisplay ("short" | "narrow" | "long")

units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometres"units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"

compact(value, options?)

Formats a number using compact notation.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }

compact(1200); // "1.2K"compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

list(values, options?)

Formats an array into a localised list string.

• values: (string | number)[]
• options: Intl.ListFormatOptions & { locale?: LocalesValues }
  • Common: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")

list(["apple", "banana", "orange"]); // "apple, banana, and orange"list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"

Cached Intl

The exported Intl from intlayer is a cached wrapper around the global Intl. It memoizes formatter instances (NumberFormat, DateTimeFormat, etc.) to avoid repeatedly constructing them, improving performance.

import { Intl } from "intlayer";// Number formattingconst numberFormat = new Intl.NumberFormat("en-GB", {  style: "currency",  currency: "GBP",});numberFormat.format(1234.5); // "£1,234.50"// Display names for languages, regions, etc.const displayNames = new Intl.DisplayNames("fr", { type: "language" });displayNames.of("en"); // "anglais"// Collation for sortingconst collator = new Intl.Collator("fr", { sensitivity: "base" });collator.compare("é", "e"); // 0 (equal)// Plural rulesconst pluralRules = new Intl.PluralRules("fr");pluralRules.select(1); // "one"pluralRules.select(2); // "other"

Additional Intl Features

Intl.DisplayNames

For localised names of languages, regions, currencies, and scripts:

import { Intl } from "intlayer";const languageNames = new Intl.DisplayNames("en", { type: "language" });languageNames.of("fr"); // "French"const regionNames = new Intl.DisplayNames("fr", { type: "region" });regionNames.of("US"); // "États-Unis"

Intl.Collator

For locale-aware string comparison and sorting:

import { Intl } from "intlayer";const collator = new Intl.Collator("de", {  sensitivity: "base",  numeric: true,});const words = ["äpfel", "zebra", "100", "20"];words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]

Intl.PluralRules

For determining plural forms in different locales:

import { Intl } from "intlayer";const pluralRules = new Intl.PluralRules("ar");pluralRules.select(0); // "zero"pluralRules.select(1); // "one"pluralRules.select(2); // "two"pluralRules.select(3); // "few"pluralRules.select(11); // "many"

Locale Utilities

units(value, options?)

Formats a numeric value as a localised unit string using Intl.NumberFormat with style: 'unit'.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }
  • Common fields: unit (e.g., "kilometre", "byte"), unitDisplay ("short" | "narrow" | "long")
  • Defaults: unit: 'day', unitDisplay: 'short', useGrouping: false

Examples:

import { units } from "intlayer";units(5, { unit: "kilometre", unitDisplay: "long", locale: "en-GB" }); // "5 kilometres"units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (locale-dependent)

compact(value, options?)

Formats a number using compact notation (e.g., 1.2K, 1M).

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues } (uses notation: 'compact' under the hood)

Examples:

import { compact } from "intlayer";compact(1200); // "1.2K"compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

list(values, options?)

Formats an array of values into a localised list string using Intl.ListFormat.

• values: (string | number)[]
• options: Intl.ListFormatOptions & { locale?: LocalesValues }
  • Common fields: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")
  • Defaults: type: 'conjunction', style: 'long'

Examples:

import { list } from "intlayer";list(["apple", "banana", "orange"]); // "apple, banana, and orange"list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"list([1, 2, 3], { type: "unit" }); // "1, 2, 3"

getLocaleLang(locale?)

Extracts the language code from a locale string:

import { getLocaleLang } from "intlayer";getLocaleLang("en-US"); // "en"getLocaleLang("fr-CA"); // "fr"

React

Client components:

import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "react-intlayer/format";// or in Next.js appsimport {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "next-intlayer/client/format";const MyComponent = () => {  const number = useNumber();  const currency = useCurrency();  const date = useDate();  const percentage = usePercentage();  const compact = useCompact();  const list = useList();  const relativeTime = useRelativeTime();  const unit = useUnit();  return (    <div>      <p>{number(123456.789)}</p>      <p>{currency(1234.5, { currency: "EUR" })}</p>      <p>{date(new Date(), "short")}</p>      <p>{percentage(0.25)}</p>      <p>{compact(1200)}</p>      <p>{list(["apple", "banana", "orange"])}</p>      <p>{relativeTime(new Date(), new Date() + 1000)}</p>      <p>{unit(123456.789, { unit: "kilometre" })}</p>    </div>  );};

Server components (or React Server runtime):

import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "react-intlayer/server/format";// or in Next.js appsimport {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "next-intlayer/server/format";

These hooks will consider the locale from the IntlayerProvider or IntlayerServerProvider

getHTMLTextDir(locale?)

Returns the text direction for a locale:

import { getHTMLTextDir } from "intlayer";getHTMLTextDir("en-US"); // "ltr"getHTMLTextDir("ar"); // "rtl"getHTMLTextDir("he"); // "rtl"

Content Handling Utilities

Vue

Client components:

import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "vue-intlayer/format";

These composables will consider the locale from the injected IntlayerProvider

getTranslation(languageContent, locale?, fallback?)

Extracts content for a specific locale:

import { getTranslation } from "intlayer";const content = getTranslation(  { en: "Hello", fr: "Bonjour", de: "Hallo" },  "fr",  true); // "Bonjour"

getIntlayer(dictionaryKey, locale?, plugins?)

Retrieves and transforms content from a dictionary:

import { getIntlayer } from "intlayer";const content = getIntlayer("common", "fr");

Notes

• All helpers accept string inputs; they are internally coerced to numbers or dates.
• Locale defaults to your configured internationalization.defaultLocale if not provided.
• These utilities are thin wrappers; for advanced formatting, pass through the standard Intl options.