Форматери Intlayer

Зміст

Cached Intl

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

Якщо Intl.DisplayNames недоступний у середовищі, виводиться одне попередження лише для розробників (розгляньте можливість поліфілу).

Приклади:

Яка локаль використовується?

Якщо ви передаєте опцію locale, вона завжди має пріоритет. Інакше форматери, їхні хуки (useNumber, useDate, useList…) і useIntl визначають її в такому порядку:

1. Локаль провайдера (IntlayerProvider), для хуків і composables.
2. Локаль поточного запиту, на сервері, коли його обробляє інтеграція Intlayer (express-intlayer, fastify-intlayer, hono-intlayer, remix-intlayer, astro-intlayer…).
3. Локаль, збережена в браузері (cookie, localStorage, sessionStorage), яку зберігає ваш перемикач мови.
4. defaultLocale вашої конфігурації.

import { number, list } from "intlayer";

// Збережена локаль: fr
number(1234.5); // "1 234,5"
list(["яблуко", "банан"]); // "яблуко et банан"

Поза провайдером або серверною інтеграцією сервер форматує з defaultLocale, а браузер використовує збережену локаль, що може спричинити помилку гідратації. Для сторінок із серверним рендерингом використовуйте провайдер або передавайте locale явно.

Утиліти локалей

getLocaleName(displayLocale, targetLocale?)

import { getLocaleName } from "intlayer";

getLocaleName("fr", "en"); // англійською: "French"
getLocaleName("en", "fr"); // французькою: "anglais"
getLocaleName("de", "es"); // іспанською: "alemán"

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

Генерує локалізований URL для поточної локалі:

• url: Початковий URL для локалізації
• currentLocale: Поточна локаль
• locales: Необов'язковий масив підтримуваних локалей (за замовчуванням, сконфігуровані локалі)
• defaultLocale: Необов'язкова локаль за замовчуванням (за замовчуванням, сконфігурована локаль за замовчуванням)
• prefixDefault: Чи додавати префікс для локалі за замовчуванням (за замовчуванням, сконфігуроване значення)

getContent(node, nodeProps, locale?)

import { getContent } from "intlayer";

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

getIntlayer(dictionaryKey, locale?, plugins?)

Отримує та трансформує вміст із словника за ключем:

import { getIntlayer } from "intlayer";

const content = getIntlayer("common", "fr");
const nestedContent = getIntlayer("common", "fr", customPlugins);

Форматувачі

number(value, options?)

import { number } from "intlayer";

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

currency(value, options?)

Форматує значення як локалізовану валюту. За замовчуванням USD з двома знаками після коми.

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }
  • Типові поля: currency (наприклад, "EUR"), currencyDisplay ("symbol" | "code" | "name")

relativeTime(from, to = new Date(), options?)

import { relativeTime } from "intlayer";

const now = new Date();
const in3Days = new Date(now.getTime() + 3 * 864e5);
relativeTime(now, in3Days, { unit: "day" }); // "через 3 дні"

const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 години тому"

units(value, options?)

• value: number | string
• options: Intl.NumberFormatOptions & { locale?: LocalesValues }
  • Загальні поля: unit (наприклад, "kilometer", "byte"), unitDisplay ("short" | "narrow" | "long")
  • За замовчуванням: unit: 'day', unitDisplay: 'short', useGrouping: false

import { units } from "intlayer";

units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 кілометрів"
units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (залежить від локалі)

Vanilla JS / Node.js Formatters

Для контекстів без фреймворку імпортуйте форматери безпосередньо з intlayer. Опція locale необов'язкова: без неї використовується локаль запиту, потім збережена локаль, потім defaultLocale.

list(values, options?)

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"

Функції форматування

number(value, options?)

Форматує числове значення з врахуванням локалі для групування та десяткових знаків.

• 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?)

Форматує число як рядок відсотка. Значення більше 1 нормалізуються (наприклад, 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?)

Форматує значення як локалізовану валюту. За замовчуванням використовує 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?)

Форматує значення дати/часу.

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

date(new Date(), "short"); // наприклад, "08/02/25, 14:30"
date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

relativeTime(from, to?, options?)

Форматує відносний час між двома моментами.

• from: Date | string | number
• to: Date | string | number (за замовчуванням new Date())
• options: { locale?, unit?, numeric?, style? }

const now = new Date();
const in3Days = new Date(now.getTime() + 3 * 864e5);
relativeTime(now, in3Days, { unit: "day" }); // "через 3 дні"

const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 години тому"

units(value, options?)

Форматує числове значення з одиницею виміру.

• 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 kilometers"
units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"

compact(value, options?)

Форматує число за допомогою компактного запису.

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

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

list(values, options?)

Форматує масив у локалізований рядок списку.

• values: (string | number)[]
• options: Intl.ListFormatOptions & { locale?: LocalesValues }
  • Поширені: 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

Експортований Intl з intlayer це кешований wrapper навколо глобального Intl. Він мемоізує екземпляри форматерів (NumberFormat, DateTimeFormat тощо), щоб уникнути їхнього повторного створення та поліпшити продуктивність.

import { Intl } from "intlayer";

// Форматування чисел
const numberFormat = new Intl.NumberFormat("en-GB", {
  style: "currency",
  currency: "GBP",
});
numberFormat.format(1234.5); // "£1,234.50"

// Назви відображення для мов, регіонів тощо
const displayNames = new Intl.DisplayNames("fr", { type: "language" });
displayNames.of("en"); // "anglais"

// Collation для сортування
const collator = new Intl.Collator("fr", { sensitivity: "base" });
collator.compare("é", "e"); // 0 (equal)

// Правила множини
const pluralRules = new Intl.PluralRules("fr");
pluralRules.select(1); // "one"
pluralRules.select(2); // "other"

Додаткові функції Intl

Intl.DisplayNames

Для локалізованих назв мов, регіонів, валют та письмових систем:

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

Для локалізованого порівняння та сортування рядків:

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

Для визначення форм множини в різних локалях:

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?)

Отримує локалізовану назву локалі:

import { getLocaleName } from "intlayer";

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

getLocaleLang(locale?)

Витягує код мови з рядка локалі:

import { getLocaleLang } from "intlayer";

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

getLocaleFromPath(inputUrl)

Витягує сегмент локалі з URL-адреси або шляху:

import { getLocaleFromPath } from "intlayer";

getLocaleFromPath("/en/dashboard"); // "en"
getLocaleFromPath("/fr/dashboard"); // "fr"
getLocaleFromPath("/dashboard"); // "en" (локаль за замовчуванням)

getPathWithoutLocale(inputUrl, locales?)

Видаляє сегмент локалі з URL:

import { getPathWithoutLocale } from "intlayer";

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

React

Клієнтські компоненти:

import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
} from "react-intlayer/server/format";
// або в додатках Next.js
import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
} from "next-intlayer/server/format";

getHTMLTextDir(locale?)

Повертає напрямок тексту для локалі:

import { getHTMLTextDir } from "intlayer";

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

Утиліти обробки вмісту

Vue

Клієнтські компоненти:

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

getTranslation(languageContent, locale?, fallback?)

Витягує вміст для конкретної локалі:

import { getTranslation } from "intlayer";

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

getIntlayer(dictionaryKey, locale?, plugins?)

Отримує та трансформує вміст зі словника:

import { getIntlayer } from "intlayer";

const content = getIntlayer("common", "fr");

Примітки

• Усі помічники приймають входи типу string; внутрішньо вони перетворюються на числа або дати.
• Locale за замовчуванням використовує ваш налаштований internationalization.defaultLocale, якщо він не надано.
• Ці утиліти є тонкими обгортками; для розширеного форматування передайте стандартні параметри Intl.