Pluralização

Por que pluralização não é uma condição simples

A primeira reação ao lidar com texto no plural costuma ser escrever algo assim:

const message = count === 1 ? 'One item' : `${count} items`;

Isso funciona para inglês. Falha para polonês, onde “2 items” vira 2 elementy, “5 items” vira 5 elementów e “21 items” volta para 21 elementów. Falha para árabe, que tem seis formas de plural. Falha para russo, que distingue entre um item, dois a quatro itens e cinco ou mais itens. Falha até para zero. Em francês, zero usa a forma singular, 0 élément, enquanto em inglês zero usa a forma plural, 0 items.

O ponto central é que a escolha do plural depende de duas coisas: o idioma e o número. Os principais idiomas têm regras documentadas pelo projeto Unicode CLDR, Common Locale Data Repository, e essas regras mapeiam qualquer inteiro para uma entre seis categorias nomeadas: zero, one, two, few, many e other. Cada idioma usa apenas um subconjunto dessas categorias, e other é sempre o fallback obrigatório.

O motor de pluralização do Spraxium delega a escolha da categoria para Intl.PluralRules, a implementação do V8 embutida no Node.js que segue as regras do CLDR, e depois procura a variante correspondente dentro do mapa achatado de traduções.

Convenção de nomes para variantes plurais

As chaves de plural seguem o padrão baseKey_category. A base é a mesma chave que você usaria com t(). A categoria é um dos seis nomes do CLDR, anexada com underscore.

{
  "items": {
    "_zero": "No items in your inventory",
    "_one": "One item in your inventory",
    "_other": "{{count}} items in your inventory"
  }
}

Depois do flattening usando o nome da referência commands e o nome do arquivo items, as chaves completas ficam assim:

• commands.items._zero
• commands.items._one
• commands.items._other

O motor constrói a chave de busca adicionando _ mais a categoria resolvida à base que você passou para tp().

As seis categorias e quando cada uma se aplica

Idiomas que não têm forma específica para zero, como a maior parte das línguas da Europa Ocidental, mapeiam zero para other. Isso significa que 0 items em inglês cai em _other, e por isso a variante _zero do exemplo acima usa a frase “No items”. Se você quiser uma formulação especial para zero, precisa fornecer _zero explicitamente.

Algoritmo de resolução

Fornecendo traduções para idiomas com regra plural complexa

O russo precisa de quatro entradas para ficar correto. Se você pular _few ou _many, o motor cai em _other nesses casos, o que pode gerar uma frase gramaticalmente errada.

{
  "items": {
    "_one": "{{count}} ?@54<5B",
    "_few": "{{count}} ?@54<5B0",
    "_many": "{{count}} ?@54<5B>2",
    "_other": "{{count}} ?@54<5B0"
  }
}

i18n.tp('commands.items', 'ru', 1); // '1 ?@54<5B'    (one)
i18n.tp('commands.items', 'ru', 2); // '2 ?@54<5B0'   (few)
i18n.tp('commands.items', 'ru', 5); // '5 ?@54<5B>2'  (many)
i18n.tp('commands.items', 'ru', 11); // '11 ?@54<5B>2' (many, teen numbers are always many in Russian)
i18n.tp('commands.items', 'ru', 21); // '21 ?@54<5B'   (one, 21 ends in 1)

Usando pluralização em handlers

import { Ctx, SlashCommandHandler } from '@spraxium/common';
import { I18nService } from '@spraxium/i18n';
import type { ChatInputCommandInteraction } from 'discord.js';
import { InventoryCommand } from '../commands/inventory.command';

@SlashCommandHandler(InventoryCommand)
export class InventoryHandler {
  constructor(private readonly i18n: I18nService) {}

  async handle(@Ctx() interaction: ChatInputCommandInteraction): Promise<void> {
    const count = await getInventoryCount(interaction.user.id);
    const locale = interaction.locale;

    const message = this.i18n.tp('commands.items', locale, count, { count });
    await interaction.reply(message);

  }
}

Regras plurais customizadas para casos de borda

Quando Intl.PluralRules devolve um resultado incorreto para um identificador específico de locale, algo raro, mas possível em variantes customizadas ou em combinações ainda não cobertas pela versão atual do CLDR embarcada no Node.js, você pode sobrescrever a regra no momento da configuração:

import { defineI18n } from '@spraxium/i18n';

export const i18nConfig = defineI18n({
  defaultLocale: 'en-US',
  references: [{ name: 'commands', path: './locales/commands' }],
  pluralRules: {
    'pt-BR': (count) => (count === 1 ? 'one' : 'other'),
    ar: (count) => {
      if (count === 0) return 'zero';
      if (count === 1) return 'one';
      if (count === 2) return 'two';
      if (count % 100 >= 3 && count % 100 <= 10) return 'few';
      if (count % 100 >= 11 && count % 100 <= 99) return 'many';
      return 'other';
    },
  },
});

As regras customizadas recebem o número e devem devolver uma entre as seis categorias possíveis. Elas rodam antes de Intl.PluralRules e o substituem completamente para o locale especificado. Locales sem regra customizada continuam usando Intl.PluralRules normalmente.

A variável

O valor passado para tp() ou tpUser() já fica disponível automaticamente como {{count}} na string traduzida. Você não precisa enviá-lo manualmente no objeto de vars. O motor faz essa mescla sozinho para que qualquer variante plural possa referenciar a contagem sem boilerplate extra.

{
  "items": {
    "_one": "You have one item remaining",
    "_other": "You have {{count}} items remaining"
  }
}

Se você passar variáveis adicionais, elas são mescladas com count, e todas ficam disponíveis como placeholders {{varName}}:

i18n.tp('commands.items', 'en-US', 5, { maxCapacity: 10 });
// Translation: 'You have {{count}} of {{maxCapacity}} item slots used'
// Result:      'You have 5 of 10 item slots used'