@cat-factory/app 0.217.1 → 0.218.0

package/i18n/plural-rules.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+import { allowedFormCounts, pluralRules, type OverriddenLocale } from './plural-rules'
+
+// The slot order each overridden locale's CLDR categories fill, matching `plural-rules.ts`.
+// Naming them as CLDR category strings is what lets the tests below compare against
+// `Intl.PluralRules`, the platform's own copy of the same CLDR data: a hand-written rule that
+// drifts from ICU (because CLDR revised the locale, or because the rule was wrong to begin
+// with) fails here instead of quietly rendering the wrong form.
+const CATEGORY_ORDER: Record<OverriddenLocale, readonly Intl.LDMLPluralRule[]> = {
+  pl: ['one', 'few', 'many'],
+  uk: ['one', 'few', 'many'],
+  he: ['one', 'two', 'other'],
+}
+
+const LOCALES = Object.keys(CATEGORY_ORDER) as OverriddenLocale[]
+
+/** The CLDR category a selector resolves `n` to, for an entry carrying only the CLDR forms. */
+function categoryFor(locale: OverriddenLocale, n: number): Intl.LDMLPluralRule {
+  const order = CATEGORY_ORDER[locale]
+  return order[pluralRules[locale](n, order.length)]!
+}
+
+describe('plural selectors agree with Intl.PluralRules', () => {
+  // Every whole count a UI badge can plausibly show. The Slavic rules key off n % 100, and
+  // Hebrew's off n itself, so 0..1000 exercises both far past their period.
+  it.each(LOCALES)('%s over whole counts 0..1000', (locale) => {
+    const icu = new Intl.PluralRules(locale)
+    const disagreements = Array.from({ length: 1001 }, (_, n) => n)
+      .map((n) => ({ n, ours: categoryFor(locale, n), icu: icu.select(n) }))
+      .filter(({ ours, icu: theirs }) => ours !== theirs)
+    expect(disagreements).toEqual([])
+  })
+
+  // Hebrew is exact over fractions too. The Slavic locales are deliberately not: CLDR routes
+  // their fractions to an `other` category the 3-form catalogs carry no slot for, so the rule
+  // folds those onto `many` (documented in `plural-rules.ts`) and cannot be compared here.
+  it('he over fractional counts', () => {
+    const icu = new Intl.PluralRules('he')
+    const fractions = [0.1, 0.5, 0.9, 1.1, 1.5, 2.5, 3.5, 10.5, 20.5, 100.5]
+    for (const n of fractions) expect(categoryFor('he', n)).toBe(icu.select(n))
+  })
+
+  it('treats a negative count as its magnitude', () => {
+    for (const locale of LOCALES) {
+      for (const n of [1, 2, 3, 5, 22]) {
+        expect(pluralRules[locale](-n, 3)).toBe(pluralRules[locale](n, 3))
+      }
+    }
+  })
+})
+
+describe('the leading zero form', () => {
+  // One optional slot may precede the CLDR forms: a copy nicety ("no participants"), NOT a
+  // CLDR category. An entry that carries it shifts every other slot by one, which is why the
+  // form count is part of the contract rather than an authoring detail.
+  it('is selected only for 0, and only when the entry carries it', () => {
+    for (const locale of LOCALES) {
+      const [cldrOnly, withZero] = allowedFormCounts(locale) as [number, number]
+      expect(pluralRules[locale](0, withZero)).toBe(0)
+      // Without a zero slot, 0 falls to whatever category the locale puts it in, never to
+      // the `one` form.
+      expect(pluralRules[locale](0, cldrOnly)).not.toBe(0)
+      for (const n of [1, 2, 3, 5, 11, 22]) {
+        expect(pluralRules[locale](n, withZero)).toBe(pluralRules[locale](n, cldrOnly) + 1)
+      }
+    }
+  })
+})
+
+describe('an entry with too few forms', () => {
+  // A short entry is a CI failure (`scripts/i18n-plural-forms.mjs`). At RUNTIME the selector
+  // still has to answer with an in-range index: vue-i18n indexes the form array raw and throws
+  // out of `t()` on an out-of-range answer, which blanks the whole surface rendering it rather
+  // than degrading to an approximate form.
+  it('clamps to the last form instead of running off the end', () => {
+    for (const locale of LOCALES) {
+      for (const forms of [1, 2]) {
+        for (let n = 0; n <= 200; n++) {
+          const index = pluralRules[locale](n, forms)
+          expect(index).toBeGreaterThanOrEqual(0)
+          expect(index).toBeLessThan(forms)
+        }
+      }
+    }
+  })
+})
+
+describe('hebrew', () => {
+  // The behaviour this module exists to add: 2 is its own form, where the default 2-form
+  // selector lumped it in with the plural.
+  it('gives 2 a form of its own', () => {
+    const forms = ['one', 'two', 'other']
+    expect(forms[pluralRules.he(1, 3)]).toBe('one')
+    expect(forms[pluralRules.he(2, 3)]).toBe('two')
+    expect(forms[pluralRules.he(3, 3)]).toBe('other')
+    expect(forms[pluralRules.he(20, 3)]).toBe('other')
+  })
+})

package/i18n/plural-rules.ts

@@ -0,0 +1,123 @@
+// Per-locale plural SELECTORS for vue-i18n: given a count and how many forms a catalog entry
+// carries, return the index of the form to render. Wired onto `pluralRules` in `i18n.config.ts`;
+// this module is deliberately free of Nuxt/vue-i18n imports so it unit-tests as pure logic
+// (`plural-rules.spec.ts`).
+//
+// vue-i18n's BUILT-IN selector implements neither Slavic nor Semitic agreement: for a 2-form
+// entry it picks index 0 when n === 1 and index 1 otherwise, and for a 3-form entry it picks
+// 0/1/2 for n === 0 / n === 1 / n > 1. That is right for `en`/`es`/`fr`/`de`/`it`/`ja`/`tr`
+// (which are therefore NOT listed here) and wrong everywhere below.
+//
+// ## The slot contract a catalog entry declares by its FORM COUNT
+//
+// A locale's CLDR categories fill the trailing slots, in the order named by `CLDR_CATEGORIES`
+// below. One optional slot may precede them: a ZERO form, which is a COPY nicety rather than a
+// CLDR category ("no participants" reads better than "0 participants") and which `en` already
+// uses. So for a locale with 3 CLDR categories:
+//
+//   3 forms  ->  <cat0> | <cat1> | <cat2>
+//   4 forms  ->  zero | <cat0> | <cat1> | <cat2>
+//
+// The count is therefore load-bearing: dropping a form does not degrade the message, it
+// RE-POINTS every remaining slot onto a different count. `scripts/i18n-plural-forms.mjs` fails
+// CI on an entry whose form count is not one of the two shapes, because nothing else can catch
+// it (a short entry renders confidently and wrongly, and vue-i18n throws outright when a
+// selector returns an index past the end).
+
+/** A vue-i18n plural selector: `(count, formsInThisEntry) => index of the form to render`. */
+export type PluralSelector = (choice: number, choicesLength: number) => number
+
+// Polish and Ukrainian share the `few` bucket but NOT the `one` bucket, and one rule serving
+// both is what this pair of functions replaced: Polish reserves `one` for exactly 1, while
+// Ukrainian gives it to every count ending in 1 except the teens, so 21/31/…/101 were rendering
+// the `many` form ("21 репозиторіїв" for "21 репозиторій") on 89 of the first 1000 counts.
+const slavicFew = (mod10: number, mod100: number): boolean =>
+  mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)
+
+/**
+ * Polish one/few/many, e.g. "decyzja | decyzje | decyzji".
+ *
+ * CLDR also gives Polish an `other` category, reached only by fractional counts. The catalogs
+ * carry no slot for it and a count here is always a whole number of things, so a fraction
+ * collapses onto `many`, which is the form Polish uses for a decimal anyway ("2,5 decyzji").
+ * The same holds for Ukrainian below.
+ */
+const polishCategory = (n: number): number => {
+  if (n === 1) return 0 // one
+  if (slavicFew(n % 10, n % 100)) return 1 // few
+  return 2 // many (incl. 0, 5-21, ...)
+}
+
+/** Ukrainian one/few/many, e.g. "рішення | рішення | рішень". */
+const ukrainianCategory = (n: number): number => {
+  const mod10 = n % 10
+  const mod100 = n % 100
+  if (mod10 === 1 && mod100 !== 11) return 0 // one (1, 21, 31, ..., 101, ...)
+  if (slavicFew(mod10, mod100)) return 1 // few
+  return 2 // many (incl. 0, 5-20, ...)
+}
+
+/**
+ * Hebrew one/two/other (CLDR `he`): a distinct DUAL, which is why running `he` on the default
+ * 2-form selector made every count message an approximation. n === 2 takes its own form, both
+ * for the lexical duals ("יומיים" for two days, "פעמיים" for twice) and for the spelled-out
+ * numeral ordinary prose wants ("שתי משימות" rather than "2 משימות").
+ *
+ * Fractions follow CLDR too: a count below 1 is `one` (0.5 -> "one"), a fractional count at or
+ * above 1 is `other`. `plural-rules.spec.ts` asserts the whole domain against `Intl.PluralRules`,
+ * so an ICU/CLDR revision to Hebrew fails a test rather than silently disagreeing with the
+ * platform's own formatter.
+ *
+ * Note the CLDR rule has THREE categories, not the four (one/two/many/other) it carried before
+ * the `many` bucket for round tens was retired: modern Hebrew does not inflect for it, so asking
+ * a translator to author that form would only produce a duplicate of `other`.
+ */
+const hebrewCategory = (n: number): number => {
+  const integerPart = Math.floor(n)
+  if (n !== integerPart) return integerPart === 0 ? 0 : 2 // one below 1, otherwise other
+  if (integerPart === 1) return 0 // one
+  if (integerPart === 2) return 1 // two
+  return 2 // other (incl. 0)
+}
+
+/** How many CLDR categories each overridden locale's rule resolves, in slot order. */
+const CLDR_CATEGORIES = {
+  pl: { count: 3, category: polishCategory },
+  uk: { count: 3, category: ukrainianCategory },
+  he: { count: 3, category: hebrewCategory },
+} as const
+
+/** The locales whose plural selector is overridden, i.e. the ones the form-count guard covers. */
+export type OverriddenLocale = keyof typeof CLDR_CATEGORIES
+
+/**
+ * The form counts a catalog entry may carry in `locale`: the CLDR categories alone, or those
+ * preceded by the optional zero form. Exported so the CI guard and this module agree on the
+ * contract by construction instead of by two copies of the same numbers.
+ */
+export function allowedFormCounts(locale: OverriddenLocale): readonly number[] {
+  const { count } = CLDR_CATEGORIES[locale]
+  return [count, count + 1]
+}
+
+function selectorFor(locale: OverriddenLocale): PluralSelector {
+  const { count: cldrForms, category } = CLDR_CATEGORIES[locale]
+  return (choice, choicesLength) => {
+    const n = Math.abs(choice)
+    // More forms than the locale has categories means the entry leads with a zero form.
+    const hasZeroForm = choicesLength > cldrForms
+    if (hasZeroForm && n === 0) return 0
+    const index = (hasZeroForm ? 1 : 0) + category(n)
+    // An entry with too FEW forms is a CI failure, not a runtime one: clamping renders the
+    // nearest form instead of handing vue-i18n an out-of-range index, which it rejects by
+    // throwing out of `t()` and blanking whatever was rendering the message.
+    return Math.min(index, choicesLength - 1)
+  }
+}
+
+/** vue-i18n's `pluralRules` map: only the locales the built-in selector gets wrong. */
+export const pluralRules: Record<OverriddenLocale, PluralSelector> = {
+  pl: selectorFor('pl'),
+  uk: selectorFor('uk'),
+  he: selectorFor('he'),
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.217.1",
+  "version": "0.218.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.230.1"
+    "@cat-factory/contracts": "0.231.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",