Auteur:
    Aymeric PINEAU
    Création:2024-08-13Dernière mise à jour:2025-08-20

    Formatteurs Intlayer

    Vue d'ensemble

    Intlayer fournit un ensemble d'aides légères construites sur les API natives Intl, ainsi qu'un wrapper Intl mis en cache pour éviter de reconstruire à plusieurs reprises des formatteurs lourds. Ces utilitaires sont entièrement sensibles à la locale et peuvent être utilisés depuis le package principal intlayer.

    Intl mis en cache

    L'Intl exporté est un wrapper léger et mis en cache autour de l'Intl global. Il mémorise les instances de NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator et PluralRules, ce qui évite de reconstruire plusieurs fois le même formateur.

    Si Intl.DisplayNames n'est pas disponible dans l'environnement, un seul avertissement destiné aux développeurs est affiché (envisagez un polyfill).

    Exemples :

    Utilitaires de locale

    getLocaleName(displayLocale, targetLocale?)

    ts
    import { getLocaleName } from "intlayer";

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

    getLocaleFromPath(inputUrl)

    Extrait le segment de locale d'une URL ou d'un chemin :

    • inputUrl : La chaîne complète de l'URL ou le chemin à traiter
    • returns : La locale détectée ou la locale par défaut si aucune locale n'est trouvée

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

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

    getHTMLTextDir(locale?)

    Retourne la direction du texte pour une locale :

    ts
    import { getHTMLTextDir } from "intlayer";

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

    Formatteurs

    number(value, options?)

    ts
    import { number } from "intlayer";

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

    currency(value, options?)

    Formate une valeur en devise localisée. Par défaut en USD avec deux chiffres fractionnaires.

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

    date(date, optionsOrPreset?)

    ts
    import { date } from "intlayer";

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

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

    • Passez "now" comme premier argument et la cible comme second pour obtenir une formulation naturelle.
    • from : Date | string | number
    • to : Date | string | number (par défaut new Date())
    • options : { locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }
      • L’unit par défaut est "second".
    ts
    import { relativeTime } from "intlayer";

const now = new Date();
const in3Days = new Date(now.getTime() + 3 * 864e5);
relativeTime(now, in3Days, { unit: "day" }); // "dans 3 jours"

const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "il y a 2 heures"

    Vanilla JS / Node.js Formatters

    Pour les contextes sans framework, importez les formatters directement depuis intlayer. Notez que vous devez passer la locale manuellement.

    units(value, options?)

    ts
    import { units } from "intlayer";

units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (dépendant de la locale)

    Fonctions de formatage

    number(value, options?)

    Formate une valeur numérique en utilisant le groupement et les décimales tenant compte de la locale.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    number(123456.789); // "123,456.789" (en en-US)
number("1000000", { locale: "fr" }); // "1 000 000"
number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"

    percentage(value, options?)

    Formate un nombre en tant que chaîne de caractères de pourcentage. Les valeurs supérieures à 1 sont normalisées (par exemple, 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?)

    Formate une valeur en devise localisée. Par défaut USD.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Courant: 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?)

    Formate une valeur de date/heure.

    • date: Date | string | number
    • optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } ou preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"
    ts
    date(new Date(), "short"); // par exemple, "08/02/25, 14:30"
date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

    relativeTime(from, to?, options?)

    Formate le temps relatif entre deux instants.

    • from: Date | string | number
    • to: Date | string | number (par défaut 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?)

    Formate une valeur numérique avec une unité.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Common: unit (par exemple, "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?)

    Formate un nombre en utilisant la notation compacte.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    compact(1200); // "1.2K"
compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

    list(values, options?)

    Formate un tableau en une chaîne de liste localisée.

    • values: (string | number)[]
    • options: Intl.ListFormatOptions & { locale?: LocalesValues }
      • Courant : 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"

    Intl en cache

    L'Intl exporté depuis intlayer est un wrapper en cache autour de l'Intl global. Il mémoïse les instances de formateurs (NumberFormat, DateTimeFormat, etc.) pour éviter de les construire à plusieurs reprises, améliorant ainsi les performances.

    ts
    import { Intl } from "intlayer";

// Formatage des nombres
const numberFormat = new Intl.NumberFormat("en-GB", {
  style: "currency",
  currency: "GBP",
});
numberFormat.format(1234.5); // "£1,234.50"

// Noms d'affichage pour les langues, régions, etc.
const displayNames = new Intl.DisplayNames("fr", { type: "language" });
displayNames.of("en"); // "anglais"

// Collation pour le tri
const collator = new Intl.Collator("fr", { sensitivity: "base" });
collator.compare("é", "e"); // 0 (égal)

// Règles de pluriel
const pluralRules = new Intl.PluralRules("fr");
pluralRules.select(1); // "one"
pluralRules.select(2); // "other"

    Fonctionnalités Intl Supplémentaires

    Intl.DisplayNames

    Pour les noms localisés des langues, régions, devises et écritures :

    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

    Pour la comparaison et le tri de chaînes sensibles à la locale :

    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

    Pour déterminer les formes plurielles dans différentes 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"

    Utilitaires de Locale

    getLocaleName(displayLocale, targetLocale?)

    Obtient le nom localisé d'une locale :

    ts
    import { getLocaleName } from "intlayer";

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

    getLocaleLang(locale?)

    Extrait le code de langue d'une chaîne de locale :

    ts
    import { getLocaleLang } from "intlayer";

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

    getLocaleFromPath(inputUrl)

    Extrait le segment de locale d'une URL ou d'un chemin :

    ts
    import { getLocaleFromPath } from "intlayer";

getLocaleFromPath("/en/dashboard"); // "en"
getLocaleFromPath("/fr/dashboard"); // "fr"
getLocaleFromPath("/dashboard"); // "en" (locale par défaut)

    getPathWithoutLocale(inputUrl, locales?)

    Supprime le segment de locale d'une URL :

    ts
    import { getPathWithoutLocale } from "intlayer";

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

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

    Génère une URL localisée :

    ts
    import { getLocalizedUrl } from "intlayer";

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

    getHTMLTextDir(locale?)

    Retourne la direction du texte pour une locale :

    ts
    import { getHTMLTextDir } from "intlayer";

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

    Utilitaires de gestion du contenu

    compact(value, options?)

    Exemples :

    ts
    import { compact } from "intlayer";

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

    list(values, options?)

    Exemples :

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

    Vue

    Composants client :

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

    Notes

    • Tous les helpers acceptent des entrées string ; elles sont converties en nombres ou dates en interne.
    • La locale par défaut est votre internationalization.defaultLocale configurée si elle n'est pas fournie.
    • Ces utilitaires sont des wrappers minimalistes ; pour un formatage avancé, transmettez les options Intl standard.
    Récupération de fonctionFichier par locale