Formate valores para um idioma
Formate números, datas, listas e texto com o Intl nativo, fornecendo as unidades e as informações de tempo necessárias para a exibição.
Mensagens traduzidas também contêm valores: preços, datas, quantidades e listas. Um objeto Lingo formata esses valores de acordo com o idioma ativo, sem consultá-los em um catálogo. Use o mesmo objeto que renderiza a mensagem ao redor desses valores para que ambos sigam o mesmo idioma.
Números e quantidades #
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 de preço usa o valor fornecido em dólares americanos, sem converter moedas. O valor de entrada da porcentagem é uma razão: 0.125 é exibido como 12.5%, enquanto 12.5 significaria 1250%. Da mesma forma, a função auxiliar de unidades acrescenta a unidade ao valor fornecido em Celsius, sem convertê-lo.
| Método | Parâmetros após o valor |
|---|---|
num(value: number) | Intl.NumberFormatOptions opcional. |
currency(value: number, currency: string) | Código da moeda, seguido de opções de formatação numérica opcionais. |
percent(value: number) | Opções de formatação numérica opcionais. |
unit(value: number, unit: string) | Identificador da unidade, seguido de opções de formatação numérica opcionais. |
compact(value: number) | Opções de formatação numérica opcionais. |
fileSize(bytes: number) | Sem opções. |
Todos retornam strings. Os métodos de moeda, porcentagem e unidade sempre usam o estilo indicado em seus nomes; compact força o uso da notação compacta após aplicar as demais opções.
fileSize divide por potências de 1024 e usa os rótulos fixos B, KB, MB, GB, TB e PB. O número é formatado de acordo com o idioma, sem casas decimais para bytes e com no máximo uma para unidades maiores. 1024 se torna 1 KB; zero é 0 B. Forneça uma quantidade de bytes inteira e não negativa. Não há uma regra de exibição útil para valores negativos ou com frações de byte, e rótulos como GB não são traduzidos para Go em francês.
Datas, horas e deslocamentos relativos #
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 usam 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 formatos padrão são, respectivamente, data média, hora curta e a combinação dos dois.
Informar campos individuais, como year ou hour, desativa os estilos padrão. Opções de estilo explícitas podem substituir os padrões, mas combinações incompatíveis de estilos e campos individuais podem fazer o Intl nativo lançar uma exceção. Defina um fuso horário quando o servidor e o navegador precisarem exibir a mesma data.
relative(value, unit, options?) aceita um número com sinal, um Intl.RelativeTimeFormatUnit e Intl.RelativeTimeFormatOptions opcional. Ele formata o deslocamento informado. 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étodo | Resultado e comportamento |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | Uma string que une os rótulos já selecionados; por padrão, usa conjunção. |
displayName(code, type) | Um nome localizado ou undefined; o tipo é language, region, script ou currency. O mecanismo alternativo nativo pode retornar o próprio código. |
sort(items: string[], options?: Intl.CollatorOptions) | Um novo array ordenado conforme as regras do idioma; a entrada permanece inalterada. |
segment(text, granularity?) | Segmentos de string, usando grapheme por padrão ou word/sentence. O modo de palavras inclui segmentos de espaços em branco. |
displayName captura erros nativos e retorna undefined. Os demais métodos não fazem essa captura. Valide os códigos de idioma e as opções nos pontos de entrada da aplicação.
Adapte aos ambientes de execução compatíveis #
Estas funções auxiliares delegam o trabalho às APIs nativas NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator e Segmenter. O pacote não substitui APIs nativas ausentes nem fornece os dados de idioma de todos os ambientes de execução.
Teste valores representativos no servidor e nos navegadores compatíveis com sua aplicação. A pontuação e as convenções podem variar conforme os dados do ICU. Para a hidratação, mantenha consistentes o carimbo de data/hora, o fuso horário e a referência de tempo relativo, além do idioma.