Pluralización

Por qué la pluralización no es una condición simple

La primera intuición al manejar texto plural es escribir algo como:

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

Esto funciona en inglés. Falla en polaco, donde "2 items" es 2 elementy, "5 items" es 5 elementów, y "21 items" vuelve a ser 21 elementów. Falla en árabe, que tiene seis formas de plural. Falla en ruso, que distingue entre un ítem, dos-a-cuatro ítems y cinco-o-más ítems. Falla para cero. En francés, cero usa la forma singular (0 élément), mientras que en inglés cero usa la forma plural (0 items).

La idea central es que la selección plural es una función tanto del idioma como del número. Cada idioma importante tiene reglas documentadas en el proyecto Unicode CLDR (Common Locale Data Repository), y esas reglas mapean cualquier entero a una de cinco categorías con nombre: zero, one, two, few, many y other. Cada idioma usa un subconjunto de estas categorías, y other siempre es la categoría de cierre obligatoria.

El motor de pluralización de Spraxium delega la selección de categorías a Intl.PluralRules, el motor V8 integrado en Node.js que implementa las reglas CLDR, y luego busca la variante con key correspondiente en el map plano de traducciones.

Convención de nombres para variantes plurales

Las keys plurales siguen el patrón baseKey_category. La base key es la misma key que usarías para t(). La categoría es uno de los seis nombres CLDR anexado con un separador de guion bajo.

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

Después de aplanar con el nombre de referencia commands y nombre de archivo items, las keys completas quedan:

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

El motor construye la key de búsqueda anexando _ más la categoría resuelta a la base key que pases a tp().

Las seis categorías y cuándo aplica cada una

Los idiomas que no tienen una forma de cero dedicada (la mayoría de idiomas de Europa occidental) mapean cero a other. Esto significa que en inglés 0 items se resuelve a _other, por eso la variante de cero en el ejemplo de arriba dice "No items.". Necesitas proporcionar una entrada _zero específicamente para esa redacción.

Algoritmo de resolución

Proveer traducciones para un idioma con reglas plurales complejas

El ruso requiere cuatro entradas para ser correcto. Si omites _few o _many, el motor cae hacia _other para esos valores, lo que puede ser gramaticalmente incorrecto para tu string concreta.

{
  'items': {
    '_one': '{{count}} предмет',
    '_few': '{{count}} предмета',
    '_many': '{{count}} предметов',
    '_other': '{{count}} предмета'
  }
}

i18n.tp('commands.items', 'ru', 1); // '1 предмет'    (one)
i18n.tp('commands.items', 'ru', 2); // '2 предмета'   (few)
i18n.tp('commands.items', 'ru', 5); // '5 предметов'  (many)
i18n.tp('commands.items', 'ru', 11); // '11 предметов' (many, teen numbers are always many in Russian)
i18n.tp('commands.items', 'ru', 21); // '21 предмет'   (one, 21 ends in 1)

Usar pluralización en 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);

  }
}

Reglas plurales personalizadas para casos límite

Cuando Intl.PluralRules da resultados incorrectos para un identificador de locale específico (esto es poco común, pero puede ocurrir con strings de locale personalizadas o variantes de locale no cubiertas por los datos CLDR de la versión actual de Node.js), puedes sobrescribir la regla en tiempo de configuración:

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';
    },
  },
});

Las reglas personalizadas reciben el count numérico y deben devolver una de las seis strings de categoría. Se ejecutan antes de Intl.PluralRules y la sobrescriben por completo para el locale especificado. Los locales sin una regla personalizada siguen usando Intl.PluralRules con normalidad.

La variable {{count}}

El count pasado a tp() o tpUser() queda disponible automáticamente como {{count}} en la string traducida. No necesitas pasarlo explícitamente en el objeto vars. El motor lo fusiona automáticamente para que cada variante plural pueda referenciar el count sin boilerplate extra.

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

Si pasas vars adicionales, se fusionan con count y todas quedan disponibles como {{varName}} placeholders:

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'