@ultimat3/i18n 1.0.0

package/src/interpolate.js

@@ -0,0 +1,96 @@
+/**
+ * `{var}` substitution and CLDR plural-form selection.
+ * Pure string work: it never reads a catalog and never resolves a locale.
+ */
+/** CLDR plural categories, in the order we probe catalog suffixes. */
+export const PLURAL_CATEGORIES = [
+    'zero',
+    'one',
+    'two',
+    'few',
+    'many',
+    'other',
+];
+const PLACEHOLDER = /\{\{|\}\}|\{([^{}\s]+)\}/g;
+/**
+ * Replace `{name}` with `vars.name`. `{{` and `}}` escape a literal brace.
+ * An unknown variable renders loudly as `⟦name⟧` for the same reason a missing key
+ * does: a silently blank slot ships to production, a bracketed one does not.
+ */
+export function interpolate(template, vars) {
+    if (!template.includes('{'))
+        return template;
+    return template.replace(PLACEHOLDER, (match, name) => {
+        if (match === '{{')
+            return '{';
+        if (match === '}}')
+            return '}';
+        if (name === undefined)
+            return match;
+        const value = vars?.[name];
+        if (value === undefined)
+            return `⟦${name}⟧`;
+        return String(value);
+    });
+}
+/** Variable names a template expects — used by the extractor to flag arity drift. */
+export function placeholdersOf(template) {
+    const names = new Set();
+    for (const match of template.matchAll(PLACEHOLDER)) {
+        const name = match[1];
+        if (name !== undefined)
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * Pick the plural category for `count` in `locale` via `Intl.PluralRules` — CLDR
+ * categories, never an English `n === 1` check. `pl` has one/few/many/other, `ar`
+ * adds zero/two: a two-branch translator is wrong in both.
+ */
+export function pluralCategory(count, locale) {
+    return pluralRulesFor(locale).select(count);
+}
+/**
+ * Candidate keys for a plural lookup, most specific first.
+ *
+ * `items` + count 3 in `pl` → `items_many`, `items_plural`, `items_other`, `items`.
+ * `items` + count 1 in `pl` → `items_one`, `items`.
+ * `_plural` is the two-form authoring shortcut from the house style; the `_<category>`
+ * suffixes are what a 3+ form locale needs.
+ */
+export function pluralKeyCandidates(key, count, locale) {
+    const category = pluralCategory(count, locale);
+    if (category === 'one')
+        return [`${key}_one`, key];
+    return [`${key}_${category}`, `${key}_plural`, `${key}_other`, key];
+}
+/** First candidate that exists, per the caller's `has` predicate; falls back to `key`. */
+export function selectPluralKey(key, count, locale, has) {
+    for (const candidate of pluralKeyCandidates(key, count, locale)) {
+        if (has(candidate))
+            return candidate;
+    }
+    return key;
+}
+/** All suffixed variants of `key` a locale could legitimately define. */
+export function pluralVariantsOf(key) {
+    return [`${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
+}
+const rulesCache = new Map();
+function pluralRulesFor(locale) {
+    const cached = rulesCache.get(locale);
+    if (cached !== undefined)
+        return cached;
+    // An unknown tag would throw inside Intl; degrade to `en` rather than break a render.
+    let rules;
+    try {
+        rules = new Intl.PluralRules(locale);
+    }
+    catch {
+        rules = new Intl.PluralRules('en');
+    }
+    rulesCache.set(locale, rules);
+    return rules;
+}
+//# sourceMappingURL=interpolate.js.map

package/src/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["interpolate.ts"],"names":[],"mappings":"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"}

package/src/interpolate.ts

@@ -0,0 +1,103 @@
+/**
+ * `{var}` substitution and CLDR plural-form selection.
+ * Pure string work: it never reads a catalog and never resolves a locale.
+ */
+
+export type InterpolationValue = string | number | boolean;
+export type InterpolationVars = Record<string, InterpolationValue>;
+
+/** CLDR plural categories, in the order we probe catalog suffixes. */
+export const PLURAL_CATEGORIES: readonly Intl.LDMLPluralRule[] = [
+  'zero',
+  'one',
+  'two',
+  'few',
+  'many',
+  'other',
+];
+
+const PLACEHOLDER = /\{\{|\}\}|\{([^{}\s]+)\}/g;
+
+/**
+ * Replace `{name}` with `vars.name`. `{{` and `}}` escape a literal brace.
+ * An unknown variable renders loudly as `⟦name⟧` for the same reason a missing key
+ * does: a silently blank slot ships to production, a bracketed one does not.
+ */
+export function interpolate(template: string, vars?: InterpolationVars): string {
+  if (!template.includes('{')) return template;
+  return template.replace(PLACEHOLDER, (match, name: string | undefined) => {
+    if (match === '{{') return '{';
+    if (match === '}}') return '}';
+    if (name === undefined) return match;
+    const value = vars?.[name];
+    if (value === undefined) return `⟦${name}⟧`;
+    return String(value);
+  });
+}
+
+/** Variable names a template expects — used by the extractor to flag arity drift. */
+export function placeholdersOf(template: string): string[] {
+  const names = new Set<string>();
+  for (const match of template.matchAll(PLACEHOLDER)) {
+    const name = match[1];
+    if (name !== undefined) names.add(name);
+  }
+  return [...names];
+}
+
+/**
+ * Pick the plural category for `count` in `locale` via `Intl.PluralRules` — CLDR
+ * categories, never an English `n === 1` check. `pl` has one/few/many/other, `ar`
+ * adds zero/two: a two-branch translator is wrong in both.
+ */
+export function pluralCategory(count: number, locale: string): Intl.LDMLPluralRule {
+  return pluralRulesFor(locale).select(count);
+}
+
+/**
+ * Candidate keys for a plural lookup, most specific first.
+ *
+ * `items` + count 3 in `pl` → `items_many`, `items_plural`, `items_other`, `items`.
+ * `items` + count 1 in `pl` → `items_one`, `items`.
+ * `_plural` is the two-form authoring shortcut from the house style; the `_<category>`
+ * suffixes are what a 3+ form locale needs.
+ */
+export function pluralKeyCandidates(key: string, count: number, locale: string): string[] {
+  const category = pluralCategory(count, locale);
+  if (category === 'one') return [`${key}_one`, key];
+  return [`${key}_${category}`, `${key}_plural`, `${key}_other`, key];
+}
+
+/** First candidate that exists, per the caller's `has` predicate; falls back to `key`. */
+export function selectPluralKey(
+  key: string,
+  count: number,
+  locale: string,
+  has: (candidate: string) => boolean,
+): string {
+  for (const candidate of pluralKeyCandidates(key, count, locale)) {
+    if (has(candidate)) return candidate;
+  }
+  return key;
+}
+
+/** All suffixed variants of `key` a locale could legitimately define. */
+export function pluralVariantsOf(key: string): string[] {
+  return [`${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
+}
+
+const rulesCache = new Map<string, Intl.PluralRules>();
+
+function pluralRulesFor(locale: string): Intl.PluralRules {
+  const cached = rulesCache.get(locale);
+  if (cached !== undefined) return cached;
+  // An unknown tag would throw inside Intl; degrade to `en` rather than break a render.
+  let rules: Intl.PluralRules;
+  try {
+    rules = new Intl.PluralRules(locale);
+  } catch {
+    rules = new Intl.PluralRules('en');
+  }
+  rulesCache.set(locale, rules);
+  return rules;
+}

package/src/locales.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Locale resolution only: the supported set, the default, tag normalization and
+ * HTTP `Accept-Language` negotiation. Knows nothing about catalogs or interpolation.
+ */
+/** A normalized BCP-47 tag — primary subtag, lowercase (`pt`), or `lang-script` (`zh-hant`). */
+export type Locale = string;
+export declare const DEFAULT_LOCALE: Locale;
+/** Locales the framework's own catalogs may ship for. Apps narrow or extend this set. */
+export declare const SUPPORTED_LOCALES: readonly Locale[];
+export type Direction = 'ltr' | 'rtl';
+/**
+ * Strip region, lowercase, fall back to the default.
+ * `pt-BR` → `pt`; `ZH-Hant-TW` → `zh-hant` when that tag is supported, else `zh`.
+ */
+export declare function normalizeLocale(tag?: string | null, supported?: readonly Locale[], fallback?: Locale): Locale;
+/** Same as `normalizeLocale` but loud: use where an unknown locale is a caller bug. */
+export declare function assertSupportedLocale(tag: string, supported?: readonly Locale[]): Locale;
+export declare function isSupportedLocale(tag: string, supported?: readonly Locale[]): boolean;
+export interface LanguageRange {
+    tag: string;
+    quality: number;
+}
+/**
+ * Parse `Accept-Language: en-GB,en;q=0.9,fr-CH;q=0.8,*;q=0.5` into ranges sorted by
+ * quality descending, ties resolved by header order (stable sort).
+ */
+export declare function parseAcceptLanguage(header?: string | null): LanguageRange[];
+/**
+ * Pick the best supported locale for an `Accept-Language` header.
+ * `*` matches the fallback rather than the first supported locale — a wildcard is
+ * "no preference", not "any language you have".
+ */
+export declare function negotiateLocale(acceptLanguage?: string | null, supported?: readonly Locale[], fallback?: Locale): Locale;
+export declare function isRtl(locale: Locale): boolean;
+export declare function directionOf(locale: Locale): Direction;
+//# sourceMappingURL=locales.d.ts.map

package/src/locales.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["locales.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,gGAAgG;AAChG,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,eAAO,MAAM,cAAc,EAAE,MAAa,CAAC;AAE3C,yFAAyF;AACzF,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EA+B9C,CAAC;AAuBF,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtC;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EACnB,SAAS,GAAE,SAAS,MAAM,EAAsB,EAChD,QAAQ,GAAE,MAAuB,GAChC,MAAM,CAeR;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,SAAS,MAAM,EAAsB,GAC/C,MAAM,CAIR;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,SAAS,MAAM,EAAsB,GAC/C,OAAO,CAET;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,EAAE,CAkB3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,EAC9B,SAAS,GAAE,SAAS,MAAM,EAAsB,EAChD,QAAQ,GAAE,MAAuB,GAChC,MAAM,CAOR;AAED,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG7C;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAErD"}

package/src/locales.js

@@ -0,0 +1,141 @@
+/**
+ * Locale resolution only: the supported set, the default, tag normalization and
+ * HTTP `Accept-Language` negotiation. Knows nothing about catalogs or interpolation.
+ */
+import { localeUnsupported } from './errors';
+export const DEFAULT_LOCALE = 'en';
+/** Locales the framework's own catalogs may ship for. Apps narrow or extend this set. */
+export const SUPPORTED_LOCALES = [
+    'en',
+    'es',
+    'pt',
+    'fr',
+    'de',
+    'it',
+    'nl',
+    'pl',
+    'ru',
+    'uk',
+    'tr',
+    'cs',
+    'sv',
+    'da',
+    'nb',
+    'fi',
+    'el',
+    'ro',
+    'hu',
+    'ar',
+    'he',
+    'fa',
+    'ur',
+    'hi',
+    'id',
+    'vi',
+    'th',
+    'ja',
+    'ko',
+    'zh',
+];
+/**
+ * Right-to-left scripts, by primary subtag. A static CLDR-derived set rather than
+ * `Intl.Locale.prototype.getTextInfo` so direction is deterministic across runtimes.
+ */
+const RTL_LOCALES = new Set([
+    'ar',
+    'arc',
+    'ckb',
+    'dv',
+    'fa',
+    'he',
+    'ks',
+    'ku',
+    'nqo',
+    'ps',
+    'sd',
+    'ug',
+    'ur',
+    'yi',
+]);
+/**
+ * Strip region, lowercase, fall back to the default.
+ * `pt-BR` → `pt`; `ZH-Hant-TW` → `zh-hant` when that tag is supported, else `zh`.
+ */
+export function normalizeLocale(tag, supported = SUPPORTED_LOCALES, fallback = DEFAULT_LOCALE) {
+    if (!tag)
+        return fallback;
+    const lower = tag.trim().toLowerCase().replace(/_/g, '-');
+    if (lower.length === 0 || lower === '*')
+        return fallback;
+    if (supported.includes(lower))
+        return lower;
+    const segments = lower.split('-');
+    const primary = segments[0] ?? '';
+    // `lang-script` is a distinct written form (zh-hant vs zh-hans) — try it before dropping to `lang`.
+    const script = segments[1];
+    if (script !== undefined && script.length === 4) {
+        const withScript = `${primary}-${script}`;
+        if (supported.includes(withScript))
+            return withScript;
+    }
+    return supported.includes(primary) ? primary : fallback;
+}
+/** Same as `normalizeLocale` but loud: use where an unknown locale is a caller bug. */
+export function assertSupportedLocale(tag, supported = SUPPORTED_LOCALES) {
+    const normalized = normalizeLocale(tag, supported, '');
+    if (normalized === '')
+        throw localeUnsupported(tag, supported);
+    return normalized;
+}
+export function isSupportedLocale(tag, supported = SUPPORTED_LOCALES) {
+    return normalizeLocale(tag, supported, '') !== '';
+}
+/**
+ * Parse `Accept-Language: en-GB,en;q=0.9,fr-CH;q=0.8,*;q=0.5` into ranges sorted by
+ * quality descending, ties resolved by header order (stable sort).
+ */
+export function parseAcceptLanguage(header) {
+    if (!header)
+        return [];
+    const ranges = [];
+    for (const part of header.split(',')) {
+        const [rawTag, ...params] = part.trim().split(';');
+        const tag = rawTag?.trim();
+        if (!tag)
+            continue;
+        let quality = 1;
+        for (const param of params) {
+            const match = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(param);
+            if (match?.[1] !== undefined) {
+                const parsed = Number.parseFloat(match[1]);
+                quality = Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 1) : 0;
+            }
+        }
+        if (quality > 0)
+            ranges.push({ tag: tag.toLowerCase(), quality });
+    }
+    return ranges.sort((a, b) => b.quality - a.quality);
+}
+/**
+ * Pick the best supported locale for an `Accept-Language` header.
+ * `*` matches the fallback rather than the first supported locale — a wildcard is
+ * "no preference", not "any language you have".
+ */
+export function negotiateLocale(acceptLanguage, supported = SUPPORTED_LOCALES, fallback = DEFAULT_LOCALE) {
+    for (const { tag } of parseAcceptLanguage(acceptLanguage)) {
+        if (tag === '*')
+            return fallback;
+        const match = normalizeLocale(tag, supported, '');
+        if (match !== '')
+            return match;
+    }
+    return fallback;
+}
+export function isRtl(locale) {
+    const primary = locale.split('-')[0]?.toLowerCase() ?? '';
+    return RTL_LOCALES.has(primary);
+}
+export function directionOf(locale) {
+    return isRtl(locale) ? 'rtl' : 'ltr';
+}
+//# sourceMappingURL=locales.js.map

package/src/locales.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.js","sourceRoot":"","sources":["locales.ts"],"names":[],"mappings":"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"}

package/src/locales.ts

@@ -0,0 +1,166 @@
+/**
+ * Locale resolution only: the supported set, the default, tag normalization and
+ * HTTP `Accept-Language` negotiation. Knows nothing about catalogs or interpolation.
+ */
+
+import { localeUnsupported } from './errors';
+
+/** A normalized BCP-47 tag — primary subtag, lowercase (`pt`), or `lang-script` (`zh-hant`). */
+export type Locale = string;
+
+export const DEFAULT_LOCALE: Locale = 'en';
+
+/** Locales the framework's own catalogs may ship for. Apps narrow or extend this set. */
+export const SUPPORTED_LOCALES: readonly Locale[] = [
+  'en',
+  'es',
+  'pt',
+  'fr',
+  'de',
+  'it',
+  'nl',
+  'pl',
+  'ru',
+  'uk',
+  'tr',
+  'cs',
+  'sv',
+  'da',
+  'nb',
+  'fi',
+  'el',
+  'ro',
+  'hu',
+  'ar',
+  'he',
+  'fa',
+  'ur',
+  'hi',
+  'id',
+  'vi',
+  'th',
+  'ja',
+  'ko',
+  'zh',
+];
+
+/**
+ * Right-to-left scripts, by primary subtag. A static CLDR-derived set rather than
+ * `Intl.Locale.prototype.getTextInfo` so direction is deterministic across runtimes.
+ */
+const RTL_LOCALES: ReadonlySet<string> = new Set([
+  'ar',
+  'arc',
+  'ckb',
+  'dv',
+  'fa',
+  'he',
+  'ks',
+  'ku',
+  'nqo',
+  'ps',
+  'sd',
+  'ug',
+  'ur',
+  'yi',
+]);
+
+export type Direction = 'ltr' | 'rtl';
+
+/**
+ * Strip region, lowercase, fall back to the default.
+ * `pt-BR` → `pt`; `ZH-Hant-TW` → `zh-hant` when that tag is supported, else `zh`.
+ */
+export function normalizeLocale(
+  tag?: string | null,
+  supported: readonly Locale[] = SUPPORTED_LOCALES,
+  fallback: Locale = DEFAULT_LOCALE,
+): Locale {
+  if (!tag) return fallback;
+  const lower = tag.trim().toLowerCase().replace(/_/g, '-');
+  if (lower.length === 0 || lower === '*') return fallback;
+  if (supported.includes(lower)) return lower;
+
+  const segments = lower.split('-');
+  const primary = segments[0] ?? '';
+  // `lang-script` is a distinct written form (zh-hant vs zh-hans) — try it before dropping to `lang`.
+  const script = segments[1];
+  if (script !== undefined && script.length === 4) {
+    const withScript = `${primary}-${script}`;
+    if (supported.includes(withScript)) return withScript;
+  }
+  return supported.includes(primary) ? primary : fallback;
+}
+
+/** Same as `normalizeLocale` but loud: use where an unknown locale is a caller bug. */
+export function assertSupportedLocale(
+  tag: string,
+  supported: readonly Locale[] = SUPPORTED_LOCALES,
+): Locale {
+  const normalized = normalizeLocale(tag, supported, '');
+  if (normalized === '') throw localeUnsupported(tag, supported);
+  return normalized;
+}
+
+export function isSupportedLocale(
+  tag: string,
+  supported: readonly Locale[] = SUPPORTED_LOCALES,
+): boolean {
+  return normalizeLocale(tag, supported, '') !== '';
+}
+
+export interface LanguageRange {
+  tag: string;
+  quality: number;
+}
+
+/**
+ * Parse `Accept-Language: en-GB,en;q=0.9,fr-CH;q=0.8,*;q=0.5` into ranges sorted by
+ * quality descending, ties resolved by header order (stable sort).
+ */
+export function parseAcceptLanguage(header?: string | null): LanguageRange[] {
+  if (!header) return [];
+  const ranges: LanguageRange[] = [];
+  for (const part of header.split(',')) {
+    const [rawTag, ...params] = part.trim().split(';');
+    const tag = rawTag?.trim();
+    if (!tag) continue;
+    let quality = 1;
+    for (const param of params) {
+      const match = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(param);
+      if (match?.[1] !== undefined) {
+        const parsed = Number.parseFloat(match[1]);
+        quality = Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 1) : 0;
+      }
+    }
+    if (quality > 0) ranges.push({ tag: tag.toLowerCase(), quality });
+  }
+  return ranges.sort((a, b) => b.quality - a.quality);
+}
+
+/**
+ * Pick the best supported locale for an `Accept-Language` header.
+ * `*` matches the fallback rather than the first supported locale — a wildcard is
+ * "no preference", not "any language you have".
+ */
+export function negotiateLocale(
+  acceptLanguage?: string | null,
+  supported: readonly Locale[] = SUPPORTED_LOCALES,
+  fallback: Locale = DEFAULT_LOCALE,
+): Locale {
+  for (const { tag } of parseAcceptLanguage(acceptLanguage)) {
+    if (tag === '*') return fallback;
+    const match = normalizeLocale(tag, supported, '');
+    if (match !== '') return match;
+  }
+  return fallback;
+}
+
+export function isRtl(locale: Locale): boolean {
+  const primary = locale.split('-')[0]?.toLowerCase() ?? '';
+  return RTL_LOCALES.has(primary);
+}
+
+export function directionOf(locale: Locale): Direction {
+  return isRtl(locale) ? 'rtl' : 'ltr';
+}

package/src/translator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Lookup + interpolation delegation, nothing else. Never throws, never falls back to
+ * another locale, never returns the key bare: a miss renders `⟦key⟧` so gaps are
+ * visible in dev and in review screenshots instead of invisible in production.
+ */
+import type { Catalog } from './catalog';
+import { type InterpolationVars } from './interpolate';
+import { type Locale } from './locales';
+export interface TranslateVars extends InterpolationVars {
+    /** Present ⇒ plural selection runs against the locale's CLDR categories. */
+    count?: number;
+}
+export interface Translator {
+    (key: string, vars?: TranslateVars): string;
+    /** Whether the key (or any of its plural variants) can be rendered. */
+    has(key: string): boolean;
+    /** The raw template, for tooling that needs the placeholders. */
+    raw(key: string): string | undefined;
+    keys(): string[];
+    readonly locale: Locale;
+}
+export declare function createTranslator(catalog: Catalog, locale?: Locale): Translator;
+/** True when a rendered string is a loud miss — assert on this in tests, never on `''`. */
+export declare function isMiss(rendered: string): boolean;
+//# sourceMappingURL=translator.d.ts.map

package/src/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["translator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,iBAAiB,EAAgC,MAAM,eAAe,CAAC;AACrF,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAC5C,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,IAAI,IAAI,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAuB,GAAG,UAAU,CA2B9F;AAED,2FAA2F;AAC3F,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/src/translator.js

@@ -0,0 +1,37 @@
+/**
+ * Lookup + interpolation delegation, nothing else. Never throws, never falls back to
+ * another locale, never returns the key bare: a miss renders `⟦key⟧` so gaps are
+ * visible in dev and in review screenshots instead of invisible in production.
+ */
+import { interpolate, selectPluralKey } from './interpolate';
+import { DEFAULT_LOCALE } from './locales';
+export function createTranslator(catalog, locale = DEFAULT_LOCALE) {
+    const hasExact = (key) => Object.hasOwn(catalog, key);
+    const resolveKey = (key, vars) => {
+        const count = vars?.count;
+        if (typeof count === 'number' && Number.isFinite(count)) {
+            return selectPluralKey(key, count, locale, hasExact);
+        }
+        return key;
+    };
+    const translate = (key, vars) => {
+        const template = catalog[resolveKey(key, vars)];
+        if (template === undefined)
+            return `⟦${key}⟧`;
+        return vars === undefined ? template : interpolate(template, vars);
+    };
+    return Object.assign(translate, {
+        has: (key) => hasExact(key) ||
+            hasExact(`${key}_other`) ||
+            hasExact(`${key}_plural`) ||
+            hasExact(`${key}_one`),
+        raw: (key) => catalog[key],
+        keys: () => Object.keys(catalog).sort(),
+        locale,
+    });
+}
+/** True when a rendered string is a loud miss — assert on this in tests, never on `''`. */
+export function isMiss(rendered) {
+    return rendered.startsWith('⟦') && rendered.endsWith('⟧');
+}
+//# sourceMappingURL=translator.js.map

package/src/translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.js","sourceRoot":"","sources":["translator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAA0B,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,cAAc,EAAe,MAAM,WAAW,CAAC;AAiBxD,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,MAAM,GAAW,cAAc;IAChF,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAEvE,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,IAAoB,EAAU,EAAE;QAC/D,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,eAAe,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,IAAoB,EAAU,EAAE;QAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,IAAI,GAAG,GAAG,CAAC;QAC9C,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE;QAC9B,GAAG,EAAE,CAAC,GAAW,EAAW,EAAE,CAC5B,QAAQ,CAAC,GAAG,CAAC;YACb,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC;YACxB,QAAQ,CAAC,GAAG,GAAG,SAAS,CAAC;YACzB,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAC;QACxB,GAAG,EAAE,CAAC,GAAW,EAAsB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;QACtD,IAAI,EAAE,GAAa,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QACjD,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,MAAM,CAAC,QAAgB;IACrC,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC"}