מחבר:
    נוצר:2024-08-13עדכון אחרון:2026-10-02

    Intlayer Formatters

    Table of Contents

    Overview

    Intlayer provides locale-aware formatting utilities built on top of the native Intl APIs. These formatters automatically use the current locale from your application context, eliminating the need to manually pass locale parameters.

    For React, Vue, and other frameworks, use the framework-specific hooks/composables that automatically bind to your app's locale context:

    FrameworkImport
    React (client)react-intlayer/format
    React (server)react-intlayer/server/format
    Next.js (client)next-intlayer/client/format
    Next.js (server)next-intlayer/server/format
    Vuevue-intlayer/format
    Preactpreact-intlayer/format
    Vanilla JS / Node.jsintlayer (no provider needed)

    Which locale is used?

    When you pass a locale option, it always wins. Otherwise, the formatters, their hooks (useNumber, useDate, useList…) and useIntl resolve it in this order:

    1. The locale of the provider (IntlayerProvider), for hooks and composables.
    2. The locale of the current request, on the server, when an Intlayer integration handles it (express-intlayer, fastify-intlayer, hono-intlayer, remix-intlayer, astro-intlayer…).
    3. The locale stored in the browser (cookie, localStorage, sessionStorage), the one your locale switcher persists.
    4. The defaultLocale of your configuration.
    ts
    import { number, list } from "intlayer";

// Stored locale: fr
number(1234.5); // "1 234,5"
list(["apple", "banana"]); // "apple et banana"

    Outside of a provider or a server integration, the server formats with the defaultLocale while the browser uses the stored locale, which can cause a hydration mismatch. For server-rendered pages, use a provider or pass the locale explicitly.

    React Formatters

    Quick Start

    tsx
    import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
  useIntl,
} from "react-intlayer/format";
// Next.js client: "next-intlayer/client/format"
// Next.js server: "next-intlayer/server/format"
// Preact: "preact-intlayer/format"

const PriceDisplay = () => {
  const currency = useCurrency();
  const percentage = usePercentage();

  return (
    <div>
      <p>Price: {currency(1234.5, { currency: "EUR" })}</p>
      <p>Discount: {percentage(0.25)}</p>
    </div>
  );
};

    Available Hooks

    All hooks automatically use the locale from IntlayerProvider (or IntlayerClientProvider / IntlayerServerProvider).

    HookDescriptionExample Output
    useNumber()Format numbers with grouping"123,456.789"
    useCurrency()Format currency values"€1,234.50"
    usePercentage()Format percentages"25%"
    useDate()Format dates and times"Aug 2, 2025"
    useRelativeTime()Format relative time"in 3 days"
    useUnit()Format values with units"5 kilometers"
    useCompact()Format numbers in compact notation"1.2K"
    useList()Format arrays as lists"apple, banana, and orange"
    useIntl()Get locale-bound Intl objectFull Intl API access

    Complete Example

    tsx
    import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
} from "react-intlayer/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(Date.now() + 86400000))}</p>
      <p>{unit(5, { unit: "kilometer" })}</p>
    </div>
  );
};

    useIntl Hook

    The useIntl hook provides direct access to a locale-bound Intl object. This is useful when you need the full Intl API (e.g., DisplayNames, Collator, PluralRules) with automatic locale injection.

    tsx
    import { useIntl } from "react-intlayer/format";

const MyComponent = () => {
  const intl = useIntl(); // uses context locale

  // Standard Intl API, but locale is auto-injected when undefined
  const formatted = new intl.NumberFormat(undefined, {
    style: "currency",
    currency: "USD",
  }).format(123.45);

  // You can still override the locale if needed
  const date = new intl.DateTimeFormat("fr-FR").format(new Date());

  // Access other Intl features
  const displayNames = new intl.DisplayNames(undefined, { type: "language" });
  const languageName = displayNames.of("fr"); // "French" (or localized)

  return (
    <div>
      <p>{formatted}</p>
      <p>{date}</p>
      <p>{languageName}</p>
    </div>
  );
};

    Vue Formatters

    Quick Start

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

const currency = useCurrency();
const percentage = usePercentage();
</script>

<template>
  <div>
    <p>Price: {{ currency.value(1234.5, { currency: "EUR" }) }}</p>
    <p>Discount: {{ percentage.value(0.25) }}</p>
  </div>
</template>

    Available Composables

    All composables return computed refs that automatically use the locale from the injected IntlayerProvider.

    ComposableDescriptionExample Output
    useNumber()Format numbers with grouping"123,456.789"
    useCurrency()Format currency values"€1,234.50"
    usePercentage()Format percentages"25%"
    useDate()Format dates and times"Aug 2, 2025"
    useRelativeTime()Format relative time"in 3 days"
    useUnit()Format values with units"5 kilometers"
    useCompact()Format numbers in compact notation"1.2K"
    useList()Format arrays as lists"apple, banana, and orange"
    useIntl()Get locale-bound Intl objectFull Intl API access

    Complete Example

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

const number = useNumber();
const currency = useCurrency();
const date = useDate();
const percentage = usePercentage();
const compact = useCompact();
const list = useList();
const relativeTime = useRelativeTime();
const unit = useUnit();
</script>

<template>
  <div>
    <p>{{ number.value(123456.789) }}</p>
    <p>{{ currency.value(1234.5, { currency: "EUR" }) }}</p>
    <p>{{ date.value(new Date(), "short") }}</p>
    <p>{{ percentage.value(0.25) }}</p>
    <p>{{ compact.value(1200) }}</p>
    <p>{{ list.value(["apple", "banana", "orange"]) }}</p>
    <p>{{ relativeTime.value(new Date(), new Date(Date.now() + 86400000)) }}</p>
    <p>{{ unit.value(5, { unit: "kilometer" }) }}</p>
  </div>
</template>

    useIntl Composable

    The useIntl composable provides direct access to a locale-bound Intl object. This is useful when you need the full Intl API with automatic locale injection.

    vue
    <script setup>
import { useIntl } from "vue-intlayer/format";

const intl = useIntl(); // uses context locale

// Standard Intl API, but locale is auto-injected when undefined
const formatted = new intl.value.NumberFormat(undefined, {
  style: "currency",
  currency: "USD",
}).format(123.45);

// You can still override the locale if needed
const date = new intl.value.DateTimeFormat("fr-FR").format(new Date());

// Access other Intl features
const displayNames = new intl.value.DisplayNames(undefined, {
  type: "language",
});
const languageName = displayNames.of("fr");
</script>

<template>
  <div>
    <p>{{ formatted }}</p>
    <p>{{ date }}</p>
    <p>{{ languageName }}</p>
  </div>
</template>

    Vanilla JS / Node.js Formatters

    For non-framework contexts, import formatters directly from intlayer. The locale option is optional: without it, the request locale, then the stored locale, then the defaultLocale is used.

    Import

    ts
    import {
  number,
  percentage,
  currency,
  date,
  relativeTime,
  units,
  compact,
  list,
  Intl,
} from "intlayer";

    Formatter Functions

    number(value, options?)

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

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    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 normalized (e.g., 25 → 25%, 0.25 → 25%).

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    percentage(0.25); // "25%"
percentage(25); // "25%"
percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"

    currency(value, options?)

    Formats a value as localized currency. Defaults to USD.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Common: currency, currencyDisplay ("symbol" | "code" | "name")
    ts
    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"
    ts
    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? }
    ts
    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")
    ts
    units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
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 }
    ts
    compact(1200); // "1.2K"
compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

    list(values, options?)

    Formats an array into a localized list string.

    • values: (string | number)[]
    • options: Intl.ListFormatOptions & { locale?: LocalesValues }
      • Common: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")
    ts
    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.

    ts
    import { Intl } from "intlayer";

// Number formatting
const 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 sorting
const collator = new Intl.Collator("fr", { sensitivity: "base" });
collator.compare("é", "e"); // 0 (equal)

// Plural rules
const pluralRules = new Intl.PluralRules("fr");
pluralRules.select(1); // "one"
pluralRules.select(2); // "other"

    Additional Intl Features

    Intl.DisplayNames

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

    ts
    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:

    ts
    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:

    ts
    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

    getLocaleName(displayLocale, targetLocale?)

    Gets the localized name of a locale:

    ts
    import { getLocaleName } from "intlayer";

getLocaleName("fr", "en"); // "French"
getLocaleName("en", "fr"); // "anglais"
getLocaleName("de", "es"); // "alemán"

    getLocaleLang(locale?)

    Extracts the language code from a locale string:

    ts
    import { getLocaleLang } from "intlayer";

getLocaleLang("en-US"); // "en"
getLocaleLang("fr-CA"); // "fr"

    getLocaleFromPath(inputUrl)

    Extracts the locale segment from a URL or pathname:

    ts
    import { getLocaleFromPath } from "intlayer";

getLocaleFromPath("/en/dashboard"); // "en"
getLocaleFromPath("/fr/dashboard"); // "fr"
getLocaleFromPath("/dashboard"); // "en" (default locale)

    getPathWithoutLocale(inputUrl, locales?)

    Removes the locale segment from a URL:

    ts
    import { getPathWithoutLocale } from "intlayer";

getPathWithoutLocale("/en/dashboard"); // "/dashboard"
getPathWithoutLocale("/fr/dashboard"); // "/dashboard"

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

    Generates a localized URL:

    ts
    import { getLocalizedUrl } from "intlayer";

getLocalizedUrl("/about", "fr", ["en", "fr"], "en", false); // "/fr/about"
getLocalizedUrl("/about", "en", ["en", "fr"], "en", false); // "/about"

    getHTMLTextDir(locale?)

    Returns the text direction for a locale:

    ts
    import { getHTMLTextDir } from "intlayer";

getHTMLTextDir("en-US"); // "ltr"
getHTMLTextDir("ar"); // "rtl"
getHTMLTextDir("he"); // "rtl"

    Content Handling Utilities

    getContent(node, nodeProps, locale?)

    Transforms a content node with all available plugins:

    ts
    import { getContent } from "intlayer";

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

    getTranslation(languageContent, locale?, fallback?)

    Extracts content for a specific locale:

    ts
    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:

    ts
    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.
    שליפה באמצעות פונקציהCLI