Dar formato a los valores según el idioma

Da formato a números, fechas, listas y texto con Intl nativo y proporciona las unidades y la información temporal necesarias para mostrarlos.

Los mensajes traducidos también contienen valores: precios, fechas, cantidades y listas. Un objeto Lingo da formato a esos valores según su idioma activo, sin buscarlos en un catálogo. Usa el mismo objeto que muestra el mensaje que los acompaña para que ambos utilicen el mismo idioma.

Números y cantidades #

ts
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" });

El precio da formato al importe proporcionado en dólares estadounidenses; no convierte divisas. El valor de entrada del porcentaje es una proporción, por lo que 0.125 se muestra como 12.5%, mientras que 12.5 equivaldría a 1250%. Del mismo modo, la función auxiliar de unidades añade la etiqueta correspondiente al valor proporcionado en grados Celsius, sin convertirlo.

MétodoParámetros después del valor
num(value: number)Intl.NumberFormatOptions opcional.
currency(value: number, currency: string)Código de divisa y, opcionalmente, opciones de formato numérico.
percent(value: number)Opciones de formato numérico opcionales.
unit(value: number, unit: string)Identificador de unidad y, opcionalmente, opciones de formato numérico.
compact(value: number)Opciones de formato numérico opcionales.
fileSize(bytes: number)Sin opciones.

Todos devuelven cadenas de texto. Los métodos de divisa, porcentaje y unidad fuerzan el estilo indicado por su nombre; compact fuerza la notación compacta después de aplicar las demás opciones.

fileSize divide entre potencias de 1024 y usa las etiquetas fijas B, KB, MB, GB, TB y PB. Da formato al número según el idioma, sin decimales para los bytes y con un máximo de uno para las unidades mayores. 1024 se muestra como 1 KB; el cero, como 0 B. Proporciona una cantidad de bytes que sea un número entero no negativo. No hay un criterio útil para mostrar valores negativos o fracciones de byte, y las etiquetas como GB no se traducen al francés como Go.

Fechas, horas y diferencias de tiempo relativas #

ts
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" });

Estas llamadas usan el l del ejemplo anterior. date, time y datetime aceptan Date | number y, opcionalmente, Intl.DateTimeFormatOptions. Las marcas de tiempo numéricas se expresan en milisegundos, no en segundos Unix. Sus formatos predeterminados son, respectivamente, fecha de longitud media, hora corta y ambos.

Al proporcionar campos individuales como year o hour, se desactivan los estilos predeterminados. Las opciones de estilo explícitas pueden sustituir los valores predeterminados, pero las combinaciones incompatibles de estilos y campos individuales pueden hacer que el Intl nativo lance una excepción. Establece una zona horaria cuando un servidor y un navegador deban mostrar la misma fecha.

relative(value, unit, options?) acepta un número con signo, un Intl.RelativeTimeFormatUnit y, opcionalmente, Intl.RelativeTimeFormatOptions. Da formato a la diferencia de tiempo que proporcionas. Calcula la diferencia respecto a un instante de referencia en el código de la aplicación y actualízala cuando sea necesario; el método no consulta el reloj ni programa actualizaciones.

Listas y operaciones de texto #

MétodoResultado y comportamiento
list(items: string[], options?: Intl.ListFormatOptions)Una cadena de texto que une etiquetas ya seleccionadas; usa una conjunción de forma predeterminada.
displayName(code, type)Un nombre localizado o undefined; el tipo es language, region, script o currency. El mecanismo alternativo nativo puede devolver el propio código.
sort(items: string[], options?: Intl.CollatorOptions)Una nueva matriz ordenada según las reglas del idioma; la matriz de entrada no se modifica.
segment(text, granularity?)Segmentos de texto, con grapheme de forma predeterminada o word/sentence. El modo de palabras incluye segmentos de espacios en blanco.

displayName captura los errores nativos y devuelve undefined. Los demás métodos no capturan los errores de esta forma. Valida los códigos de idioma y las opciones al recibirlos en tu aplicación.

Adáptate al entorno de ejecución compatible #

Estas funciones auxiliares delegan en las API nativas NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator y Segmenter. El paquete no sustituye las API nativas que falten ni proporciona los datos de idioma de todos los entornos de ejecución.

Prueba valores representativos en el servidor y en los navegadores compatibles con tu aplicación. La puntuación y las convenciones pueden variar según los datos de ICU. Para la hidratación, mantén coherentes la marca de tiempo, la zona horaria y la referencia de tiempo relativo, además del idioma.