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:
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:
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:
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:
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:
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:
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:
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.