Trabalhe com plurais, datas e números

Deixe o idioma definir a gramática e a formatação, enquanto a aplicação mantém o controle dos valores, das unidades e dos fusos horários.

Uma contagem de itens envolve duas decisões: qual número a aplicação quer representar e como o idioma do leitor expressa essa quantidade. A mesma distinção vale para datas e valores monetários. Mantenha os valores estruturados até a renderização para escolher de forma consciente a gramática, os separadores, a moeda e o fuso horário.

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

Forneça uma mensagem completa ao formatador #

Em um componente dentro de LingoProvider, use a contagem numérica com uma 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 cria 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 após um número formatado elimina essa seleção e a possibilidade de alterar a ordem das palavras.

A função auxiliar plural cria categorias nomeadas do CLDR; ela não inclui ramificações para números exatos, como =0. Para exibir uma mensagem específica do produto quando o valor for zero, use o caminho 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 que o idioma seleciona, em vez de forçar todos os idiomas a seguir as ramificações do texto de origem. Plurais e seleções documenta as formas aceitas e o comportamento da extração.

Para uma alternativa semântica, use valores estáveis para o 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 das ramificações, preservando admin, member e a alternativa obrigatória other. Valores desconhecidos usam other.

Diferencie posição ordinal de quantidade cardinal #

Um ordinal descreve uma posição. Use o formatador de expressões ICU complexas do caminho de texto para uma mensagem como:

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, não de uma regra universal. A tradução deve expressar a posição no idioma de destino. Fornecer values habilita a formatação no caminho de texto; as declarações geradas verificam o contrato da chamada, mas não validam todas as ramificações ICU aninhadas.

Mantenha explícitas as unidades de moeda e porcentagem #

Use valores numéricos com o código da moeda correspondente:

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

A primeira chamada formata valores em euros; não converte outra moeda em euros. A segunda representa quinze por cento porque recebe uma fração como entrada. Fornecer 15 representaria uma quantidade diferente. Ao inserir esses textos formatados em uma frase, passe-os por values nomeados, em vez de montar um novo texto de origem.

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

Defina o significado da data e o fuso horário de exibição #

Um registro de data e hora 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 em um instante à meia-noite, a menos que essa conversão corresponda ao significado pretendido no produto.

Para um instante, especifique o fuso horário desejado para a exibição:

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

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

Essas funções auxiliares usam o idioma ativo para a apresentação e UTC como fuso horário de exibição. As APIs padrão subjacentes também podem ser usadas diretamente:

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

Respeite a gramática aceita pelas mensagens ricas #

l.rich associa tags nomeadas a componentes React e interpola marcadores de posição simples. Ele não usa o formatador de expressões ICU complexas de l.text. Uma frase como “Leia nossa <link>política de entrega</link> para {region}” funciona nesse caminho quando o código fornece o renderizador do link e o valor da região. Adicionar um plural ou ordinal à frase não habilita o suporte a ICU.

Mantenha as definições de interação no código e escolha um modelo de mensagem compatível quando houver sobreposição entre estrutura rica e gramática. Tags desconhecidas permanecem como texto literal, e o pareamento de tags aninhadas com o mesmo nome é limitado. Consulte Mensagens interativas ricas.

Verifique os casos em que o significado muda #

Teste contagens de 0, 1, 2, um número maior e um decimal, se o produto permitir. Para ordinais em inglês, inclua 1, 2, 3, 11, 12, 13 e 21; nos idiomas de destino, use a redação esperada em cada idioma. Teste um valor desconhecido para o seletor, valores 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 essas verificações. Uma tradução ausente ou vazia pode levar ao uso do texto de origem como alternativa; por isso, um resultado plausível, por si só, não comprova a cobertura do idioma de destino. Compare os valores renderizados com a quantidade, a data e a mensagem pretendidas e, depois, revise o texto em si.