Formatar valores para um idioma

Formate números, datas, listas e texto com o Intl nativo, fornecendo as unidades e a informação temporal necessárias à apresentação.

As mensagens traduzidas continuam a conter valores: preços, datas, quantidades e listas. Um objeto Lingo formata esses valores de acordo com o idioma ativo, sem os procurar num catálogo. Utilize o mesmo objeto que apresenta o texto da mensagem para garantir que ambos usam o mesmo idioma.

Números e quantidades #

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

A formatação do preço aplica-se ao montante fornecido em dólares dos EUA; não faz conversão de moedas. O valor de entrada da percentagem é uma proporção, pelo que 0.125 é apresentado como 12.5%, enquanto 12.5 corresponderia a 1250%. Da mesma forma, a função auxiliar de unidades acrescenta a indicação da unidade ao valor fornecido em Celsius, sem o converter.

MétodoParâmetros após o valor
num(value: number)Intl.NumberFormatOptions opcional.
currency(value: number, currency: string)Código da moeda, seguido de opções facultativas de formatação numérica.
percent(value: number)Opções facultativas de formatação numérica.
unit(value: number, unit: string)Identificador da unidade, seguido de opções facultativas de formatação numérica.
compact(value: number)Opções facultativas de formatação numérica.
fileSize(bytes: number)Sem opções.

Todos devolvem cadeias de caracteres. Os métodos de moeda, percentagem e unidade impõem o estilo indicado no respetivo nome; compact impõe a notação compacta depois de aplicar as restantes opções.

fileSize divide por potências de 1024 e utiliza os rótulos fixos B, KB, MB, GB, TB e PB. Formata o número de acordo com o idioma, sem casas decimais para bytes e com, no máximo, uma para unidades maiores. 1024 passa a 1 KB; zero é apresentado como 0 B. Forneça um número inteiro e não negativo de bytes. Não existe uma regra de apresentação útil para valores negativos ou frações de byte, e rótulos como GB não são traduzidos para a forma francesa Go.

Datas, horas e diferenças de tempo 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 chamadas utilizam o l do exemplo anterior. date, time e datetime aceitam Date | number, seguido de Intl.DateTimeFormatOptions opcional. Os carimbos de data/hora numéricos são expressos em milissegundos, não em segundos Unix. Os estilos predefinidos são, respetivamente, data em formato médio, hora em formato curto e ambos.

A indicação de campos individuais, como year ou hour, desativa os estilos predefinidos. As opções de estilo explícitas podem substituir as predefinições, mas combinações incompatíveis de estilos e campos individuais podem fazer com que o Intl nativo lance uma exceção. Defina um fuso horário quando o servidor e o navegador tiverem de apresentar a mesma data.

relative(value, unit, options?) aceita um número com sinal, um Intl.RelativeTimeFormatUnit e Intl.RelativeTimeFormatOptions opcional. Formata a diferença de tempo fornecida. Calcule a diferença em relação a um instante de referência no código da aplicação e atualize-a quando necessário; o método não consulta o relógio nem agenda atualizações.

Listas e operações de texto #

MétodoResultado e comportamento
list(items: string[], options?: Intl.ListFormatOptions)Uma cadeia de caracteres que junta rótulos já selecionados; por predefinição, utiliza uma conjunção.
displayName(code, type)Um nome localizado ou undefined; o tipo é language, region, script ou currency. O mecanismo alternativo nativo pode devolver o próprio código.
sort(items: string[], options?: Intl.CollatorOptions)Um novo vetor ordenado segundo as regras do idioma; o vetor de entrada permanece inalterado.
segment(text, granularity?)Segmentos de uma cadeia de caracteres, usando grapheme por predefinição ou word/sentence. O modo de palavras inclui segmentos de espaços em branco.

displayName captura erros nativos e devolve undefined. Os restantes métodos não capturam erros desta forma. Valide os códigos de idioma e as opções no ponto de entrada na aplicação.

Adapte ao ambiente de execução suportado #

Estas funções auxiliares delegam nas implementações nativas de NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator e Segmenter. O pacote não substitui APIs nativas em falta nem fornece os dados de idioma de todos os ambientes de execução.

Teste valores representativos no servidor e nos navegadores suportados. A pontuação e as convenções podem variar consoante os dados ICU. Para a hidratação, garanta a consistência do carimbo de data/hora, do fuso horário e do instante de referência para o tempo relativo, além do idioma.