Gerir plurais, datas e números

Deixe que o idioma determine a gramática e a formatação, mantendo na aplicação o controlo dos valores, das unidades e dos fusos horários.

Uma contagem de itens envolve duas decisões: o número que a aplicação pretende representar e a forma como o idioma de quem lê exprime essa quantidade. A mesma distinção aplica-se às datas e aos valores monetários. Mantenha os valores estruturados até ao momento da apresentação, para poder escolher de forma consciente a gramática, os separadores, a moeda e o fuso horário.

Estes exemplos utilizam @lingo.dev/react. Os sistemas de recursos nativos têm sintaxe de mensagens e geradores próprios; uma notação semelhante à ICU não torna os ambientes de execução todos intercambiáveis.

Fornecer uma mensagem completa ao formatador #

Num componente dentro de LingoProvider, utilize a contagem numérica numa mensagem de plural:

tsx
const l = useLingo();

const label = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the shopping cart" },
);

Importe useLingo de @lingo.dev/react; count é o valor numérico da aplicação. O ambiente de execução constrói uma mensagem ICU e formata a tradução do catálogo de acordo com o idioma atual. one e other são categorias gramaticais. Concatenar um substantivo traduzido a seguir a um número formatado eliminaria essa seleção e a possibilidade de alterar a ordem das palavras.

A função auxiliar plural cria categorias CLDR com nome; não inclui ramos para números exatos, como =0. Para apresentar uma mensagem específica do produto quando o valor é zero, utilize a via de texto com uma expressão ICU explícita:

ts
l.text("{count, plural, =0 {No items} one {# item} other {# items}}", {
  context: "Cart count with a distinct empty state",
  values: { count },
});

Os idiomas de destino podem exigir mais categorias do que o inglês. Examine a mensagem traduzida e teste as formas selecionadas pelo respetivo idioma, em vez de obrigar todos os idiomas a seguir os ramos do texto de origem. A documentação Plurais e seleções descreve as formas suportadas e o comportamento da extração.

Para uma alternativa semântica, utilize valores estáveis no seletor:

ts
l.select(role, {
  admin: "Manage team settings",
  member: "View team settings",
  other: "View settings",
}, { context: "Settings action for the user's team role" });

A aplicação fornece role. Traduza as mensagens dos ramos, mantendo admin, member e a alternativa obrigatória other. Se o valor for desconhecido, é utilizado other.

Distinguir a posição ordinal da quantidade cardinal #

Um ordinal indica uma posição. Utilize o formatador ICU complexo da via de texto para uma mensagem como esta:

ts
l.text("You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", {
  context: "Participant's finishing position in a competition",
  values: { position },
});

Os sufixos são próprios do texto de origem em inglês e não obedecem a uma regra universal. A tradução deve exprimir a posição de acordo com o idioma de destino. Ao fornecer values, ativa a formatação na via de texto; as declarações geradas verificam o contrato da chamada, mas não validam todos os ramos ICU aninhados.

Manter explícitas as unidades monetárias e de percentagem #

Utilize montantes numéricos com o código de moeda correspondente:

ts
const price = l.currency(1234.5, "EUR");
const discount = l.percent(0.15);

A primeira chamada formata um montante em euros; não converte outra moeda em euros. A segunda representa quinze por cento, porque o valor de entrada é uma fração. Fornecer 15 corresponderia a uma quantidade diferente. Ao inserir estas cadeias de texto formatadas numa frase, passe-as através de values com nome, em vez de construir uma nova cadeia de origem.

As funções auxiliares de formatação também abrangem números, unidades, listas e outros valores tratados com Intl. Verifique as predefinições e as opções suportadas por cada função auxiliar. A formatação adaptada ao idioma não traduz todos os rótulos de unidades personalizadas, e as opções inválidas podem, ainda assim, causar falhas.

Escolher o significado da data e o fuso horário de apresentação #

Uma marca temporal representa um instante; uma data de calendário pode representar um dia sem fuso horário. Não transforme um prazo definido apenas por uma data num instante à meia-noite, a menos que essa conversão corresponda ao significado pretendido no produto.

Para um instante, especifique o fuso horário em que o pretende apresentar:

ts
const instant = new Date("2026-01-02T00:30:00Z");

const date = l.date(instant, { timeZone: "UTC" });
const time = l.time(instant, { timeZone: "UTC" });

Estas funções auxiliares utilizam o idioma ativo para a apresentação e UTC como fuso horário. Também pode utilizar diretamente as API padrão subjacentes:

ts
new Intl.NumberFormat("de-DE", {
  style: "currency", currency: "EUR",
}).format(1234.5);

new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium", timeZone: "UTC",
}).format(new Date("2026-01-02T00:30:00Z"));

Respeitar a gramática suportada nas mensagens com conteúdo enriquecido #

l.rich associa etiquetas com nome a componentes React e interpola marcadores de posição simples. Não utiliza o formatador ICU complexo de l.text. Uma frase como «Leia a nossa <link>política de entregas</link> para {region}» funciona por esta via quando o código fornece a função de apresentação da ligação e o valor da região. Acrescentar-lhe um plural ou um ordinal não ativa o suporte para ICU.

Mantenha as definições de interação no código e escolha uma estrutura de mensagem suportada quando houver sobreposição entre conteúdo enriquecido e gramática. As etiquetas desconhecidas mantêm-se como texto literal, e o emparelhamento de etiquetas aninhadas com o mesmo nome é limitado. Consulte Mensagens interativas com conteúdo enriquecido.

Verificar os casos em que o significado muda #

Teste contagens de 0, 1, 2, um número maior e um número decimal, se o produto o permitir. Para os ordinais em inglês, inclua 1, 2, 3, 11, 12, 13 e 21; para os idiomas de destino, utilize a formulação esperada em cada idioma. Teste um valor desconhecido do seletor, montantes negativos quando fizerem sentido e o mesmo instante em dois fusos horários perto da meia-noite.

Carregue os catálogos reais dos idiomas de destino para estas verificações. Se uma tradução estiver em falta ou vazia, pode ser utilizado o texto de origem, pelo que um resultado plausível, por si só, não comprova a cobertura do idioma de destino. Compare os valores apresentados com a quantidade, a data e a mensagem pretendidas e, depois, reveja o próprio texto.