Formater les valeurs selon la langue
Formatez les nombres, les dates, les listes et le texte avec les API Intl natives, en fournissant les unités et les informations temporelles nécessaires à l’affichage.
Les messages traduits contiennent eux aussi des valeurs : prix, dates, quantités et listes. Un objet Lingo formate ces valeurs selon sa langue active, sans les rechercher dans un catalogue. Utilisez le même objet pour afficher le message qui les entoure : les valeurs et le message suivront ainsi la même langue.
Nombres et quantités #
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" });Le formatage du prix porte sur le montant fourni en dollars américains ; il ne convertit pas les devises. La valeur fournie pour le pourcentage est un ratio : 0.125 s’affiche donc sous la forme 12.5%, tandis que 12.5 correspondrait à 1250%. De même, la fonction utilitaire pour les unités indique que la valeur fournie est en Celsius, sans la convertir.
| Méthode | Paramètres après la valeur |
|---|---|
num(value: number) | Intl.NumberFormatOptions facultatif. |
currency(value: number, currency: string) | Code de devise, puis options facultatives de formatage des nombres. |
percent(value: number) | Options facultatives de formatage des nombres. |
unit(value: number, unit: string) | Identifiant d’unité, puis options facultatives de formatage des nombres. |
compact(value: number) | Options facultatives de formatage des nombres. |
fileSize(bytes: number) | Aucune option. |
Toutes ces méthodes renvoient des chaînes de caractères. Les méthodes de devise, de pourcentage et d’unité imposent le style correspondant à leur nom ; compact impose la notation compacte après avoir appliqué les autres options.
fileSize divise par des puissances de 1024 et utilise les libellés fixes B, KB, MB, GB, TB et PB. La méthode formate le nombre selon la langue, sans décimales pour les octets et avec au plus une décimale pour les unités supérieures. 1024 devient 1 KB ; zéro s’affiche sous la forme 0 B. Fournissez un nombre entier d’octets supérieur ou égal à zéro. Aucune règle d’affichage pertinente n’est définie pour les valeurs négatives ou les fractions d’octet, et les libellés tels que GB ne sont pas traduits en français sous la forme Go.
Dates, heures et décalages relatifs #
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" });Ces appels utilisent le l de l’exemple précédent. date, time et datetime acceptent Date | number, puis, en option, Intl.DateTimeFormatOptions. Les horodatages numériques sont exprimés en millisecondes, et non en secondes Unix. Par défaut, ces méthodes utilisent respectivement une date au format moyen, une heure au format court et les deux.
Si vous fournissez des champs individuels tels que year ou hour, les styles par défaut ne s’appliquent plus. Des options de style explicites peuvent remplacer les valeurs par défaut, mais une combinaison incompatible de styles et de champs individuels peut conduire l’API native Intl à lever une exception. Définissez un fuseau horaire lorsqu’un serveur et un navigateur doivent afficher la même date.
relative(value, unit, options?) accepte un nombre signé, un Intl.RelativeTimeFormatUnit et, en option, Intl.RelativeTimeFormatOptions. La méthode formate le décalage que vous fournissez. Calculez la différence par rapport à un instant de référence dans le code de l’application et mettez-la à jour au besoin ; la méthode ne lit pas l’horloge et ne planifie pas de mises à jour.
Listes et opérations sur le texte #
| Méthode | Résultat et comportement |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | Une chaîne réunissant les libellés déjà sélectionnés ; la conjonction est utilisée par défaut. |
displayName(code, type) | Un nom localisé ou undefined ; le type est language, region, script ou currency. Le mécanisme de repli natif peut renvoyer le code lui-même. |
sort(items: string[], options?: Intl.CollatorOptions) | Un nouveau tableau trié selon les règles de classement de la langue ; le tableau d’entrée reste inchangé. |
segment(text, granularity?) | Des segments de chaîne, avec grapheme par défaut ou word/sentence. Le mode mot inclut les segments d’espaces blancs. |
displayName intercepte les erreurs natives et renvoie undefined. Les autres méthodes n’interceptent pas ces erreurs. Validez les codes de langue et les options dès leur entrée dans votre application.
Tenez compte de l’environnement d’exécution pris en charge #
Ces fonctions utilitaires s’appuient sur les API natives NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator et Segmenter. Le paquet ne remplace pas les API natives manquantes et ne fournit pas les données linguistiques de tous les environnements d’exécution.
Testez des valeurs représentatives sur le serveur et dans les navigateurs que vous prenez en charge. La ponctuation et les conventions peuvent varier selon les données ICU. Pour l’hydratation, veillez à utiliser un horodatage, un fuseau horaire, un instant de référence pour le temps relatif et une langue cohérents.