@ultimat3/i18n 1.0.0

package/src/extract.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Static extraction: which keys the source calls, which are missing per locale, which
+ * are defined and never used. `x verify` fails on a missing key in a shipped locale —
+ * a translation gap is a build error, not a ticket.
+ */
+import { type Catalog } from './catalog';
+import type { Locale } from './locales';
+export interface KeyUsage {
+    key: string;
+    file: string;
+    line: number;
+    column: number;
+}
+/** `t(key)` where `key` is a variable — the extractor cannot verify it, so it says so. */
+export interface DynamicUsage {
+    expression: string;
+    file: string;
+    line: number;
+    column: number;
+}
+export interface Extraction {
+    usages: KeyUsage[];
+    dynamic: DynamicUsage[];
+}
+export interface LocaleAudit {
+    locale: Locale;
+    missing: string[];
+    unused: string[];
+}
+export interface ExtractReport {
+    /** Distinct static keys, sorted. */
+    used: string[];
+    usages: KeyUsage[];
+    dynamic: DynamicUsage[];
+    locales: LocaleAudit[];
+    ok: boolean;
+}
+export interface ExtractOptions {
+    /** Call names treated as translator calls. */
+    callees?: readonly string[];
+}
+/**
+ * Scan one source file. Deliberately a lexer-free scan: a translator call is a
+ * recognisable shape, and a regex that runs in milliseconds over a whole repo beats a
+ * parser that needs a tsconfig to start.
+ */
+export declare function extractKeys(source: string, file?: string, options?: ExtractOptions): Extraction;
+export interface AuditInput {
+    extraction: Extraction;
+    /** Every locale that ships. A locale absent here is not audited. */
+    catalogs: Readonly<Record<Locale, Catalog>>;
+    /** Keys resolved at runtime (e.g. `time.cron.*`) — never reported unused. */
+    ignoreUnused?: readonly string[];
+}
+/**
+ * A used key counts as present when the locale defines it *or* any of its plural
+ * variants: `pl` legitimately defines `items_one`/`items_few`/`items_many` and no bare
+ * `items`, and that must not read as a missing key.
+ */
+export declare function auditCatalogs(input: AuditInput): ExtractReport;
+/** The `x verify` gate. Throws on the first locale with a gap, naming file and keys. */
+export declare function assertCatalogsComplete(report: ExtractReport): void;
+/** Merge per-file extractions before auditing. */
+export declare function mergeExtractions(...extractions: readonly Extraction[]): Extraction;
+/** Read + scan real files. Bun-only by design; the CLI passes the glob results. */
+export declare function extractFromFiles(paths: readonly string[], options?: ExtractOptions): Promise<Extraction>;
+//# sourceMappingURL=extract.d.ts.map

package/src/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["extract.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAe,MAAM,WAAW,CAAC;AAGtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAKD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,SAAa,EACjB,OAAO,GAAE,cAAmB,GAC3B,UAAU,CA0BZ;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,oEAAoE;IACpE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,6EAA6E;IAC7E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAuB9D;AAED,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAIlE;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,GAAG,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAKlF;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAKrB"}

package/src/extract.js

@@ -0,0 +1,106 @@
+/**
+ * Static extraction: which keys the source calls, which are missing per locale, which
+ * are defined and never used. `x verify` fails on a missing key in a shipped locale —
+ * a translation gap is a build error, not a ticket.
+ */
+import { catalogKeys } from './catalog';
+import { catalogMissingKeys } from './errors';
+import { PLURAL_CATEGORIES } from './interpolate';
+const DEFAULT_CALLEES = ['t', '$t', 'translate'];
+const STRING_LITERAL = /^(['"`])((?:[^\\]|\\.)*?)\1$/s;
+/**
+ * Scan one source file. Deliberately a lexer-free scan: a translator call is a
+ * recognisable shape, and a regex that runs in milliseconds over a whole repo beats a
+ * parser that needs a tsconfig to start.
+ */
+export function extractKeys(source, file = '<memory>', options = {}) {
+    const callees = options.callees ?? DEFAULT_CALLEES;
+    const pattern = new RegExp(
+    // not preceded by an identifier char or `.`, so `ctx.t(` and `format(` don't match
+    String.raw `(?<![\w$.])(?:${callees.map(escapeRegExp).join('|')})(?:\.has)?\s*\(\s*([^,)]*)`, 'g');
+    const usages = [];
+    const dynamic = [];
+    for (const match of source.matchAll(pattern)) {
+        const argument = (match[1] ?? '').trim();
+        const index = match.index ?? 0;
+        const position = positionOf(source, index);
+        if (argument === '')
+            continue;
+        const literal = STRING_LITERAL.exec(argument);
+        const key = literal?.[2];
+        if (key === undefined || key.includes('${')) {
+            dynamic.push({ expression: argument, file, ...position });
+            continue;
+        }
+        usages.push({ key, file, ...position });
+    }
+    return { usages, dynamic };
+}
+/**
+ * A used key counts as present when the locale defines it *or* any of its plural
+ * variants: `pl` legitimately defines `items_one`/`items_few`/`items_many` and no bare
+ * `items`, and that must not read as a missing key.
+ */
+export function auditCatalogs(input) {
+    const used = [...new Set(input.extraction.usages.map((usage) => usage.key))].sort();
+    const ignore = input.ignoreUnused ?? [];
+    const locales = Object.keys(input.catalogs)
+        .sort()
+        .map((locale) => {
+        const catalog = input.catalogs[locale] ?? {};
+        const missing = used.filter((key) => !definesKey(catalog, key));
+        const usedWithVariants = new Set(used.flatMap(variantsOf));
+        const unused = catalogKeys(catalog).filter((key) => !usedWithVariants.has(key) && !isIgnored(key, ignore));
+        return { locale, missing, unused };
+    });
+    return {
+        used,
+        usages: input.extraction.usages,
+        dynamic: input.extraction.dynamic,
+        locales,
+        ok: locales.every((audit) => audit.missing.length === 0),
+    };
+}
+/** The `x verify` gate. Throws on the first locale with a gap, naming file and keys. */
+export function assertCatalogsComplete(report) {
+    for (const audit of report.locales) {
+        if (audit.missing.length > 0)
+            throw catalogMissingKeys(audit.locale, audit.missing);
+    }
+}
+/** Merge per-file extractions before auditing. */
+export function mergeExtractions(...extractions) {
+    return {
+        usages: extractions.flatMap((extraction) => extraction.usages),
+        dynamic: extractions.flatMap((extraction) => extraction.dynamic),
+    };
+}
+/** Read + scan real files. Bun-only by design; the CLI passes the glob results. */
+export async function extractFromFiles(paths, options = {}) {
+    const extractions = await Promise.all(paths.map(async (path) => extractKeys(await Bun.file(path).text(), path, options)));
+    return mergeExtractions(...extractions);
+}
+function definesKey(catalog, key) {
+    return variantsOf(key).some((candidate) => Object.hasOwn(catalog, candidate));
+}
+function variantsOf(key) {
+    return [key, `${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
+}
+function isIgnored(key, patterns) {
+    return patterns.some((pattern) => pattern.endsWith('*') ? key.startsWith(pattern.slice(0, -1)) : key === pattern);
+}
+function positionOf(source, index) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < index; i += 1) {
+        if (source[i] === '\n') {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: index - lineStart + 1 };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+}
+//# sourceMappingURL=extract.js.map

package/src/extract.js.map

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

package/src/extract.ts

@@ -0,0 +1,184 @@
+/**
+ * Static extraction: which keys the source calls, which are missing per locale, which
+ * are defined and never used. `x verify` fails on a missing key in a shipped locale —
+ * a translation gap is a build error, not a ticket.
+ */
+
+import { type Catalog, catalogKeys } from './catalog';
+import { catalogMissingKeys } from './errors';
+import { PLURAL_CATEGORIES } from './interpolate';
+import type { Locale } from './locales';
+
+export interface KeyUsage {
+  key: string;
+  file: string;
+  line: number;
+  column: number;
+}
+
+/** `t(key)` where `key` is a variable — the extractor cannot verify it, so it says so. */
+export interface DynamicUsage {
+  expression: string;
+  file: string;
+  line: number;
+  column: number;
+}
+
+export interface Extraction {
+  usages: KeyUsage[];
+  dynamic: DynamicUsage[];
+}
+
+export interface LocaleAudit {
+  locale: Locale;
+  missing: string[];
+  unused: string[];
+}
+
+export interface ExtractReport {
+  /** Distinct static keys, sorted. */
+  used: string[];
+  usages: KeyUsage[];
+  dynamic: DynamicUsage[];
+  locales: LocaleAudit[];
+  ok: boolean;
+}
+
+export interface ExtractOptions {
+  /** Call names treated as translator calls. */
+  callees?: readonly string[];
+}
+
+const DEFAULT_CALLEES: readonly string[] = ['t', '$t', 'translate'];
+const STRING_LITERAL = /^(['"`])((?:[^\\]|\\.)*?)\1$/s;
+
+/**
+ * Scan one source file. Deliberately a lexer-free scan: a translator call is a
+ * recognisable shape, and a regex that runs in milliseconds over a whole repo beats a
+ * parser that needs a tsconfig to start.
+ */
+export function extractKeys(
+  source: string,
+  file = '<memory>',
+  options: ExtractOptions = {},
+): Extraction {
+  const callees = options.callees ?? DEFAULT_CALLEES;
+  const pattern = new RegExp(
+    // not preceded by an identifier char or `.`, so `ctx.t(` and `format(` don't match
+    String.raw`(?<![\w$.])(?:${callees.map(escapeRegExp).join('|')})(?:\.has)?\s*\(\s*([^,)]*)`,
+    'g',
+  );
+
+  const usages: KeyUsage[] = [];
+  const dynamic: DynamicUsage[] = [];
+
+  for (const match of source.matchAll(pattern)) {
+    const argument = (match[1] ?? '').trim();
+    const index = match.index ?? 0;
+    const position = positionOf(source, index);
+    if (argument === '') continue;
+    const literal = STRING_LITERAL.exec(argument);
+    const key = literal?.[2];
+    if (key === undefined || key.includes('${')) {
+      dynamic.push({ expression: argument, file, ...position });
+      continue;
+    }
+    usages.push({ key, file, ...position });
+  }
+
+  return { usages, dynamic };
+}
+
+export interface AuditInput {
+  extraction: Extraction;
+  /** Every locale that ships. A locale absent here is not audited. */
+  catalogs: Readonly<Record<Locale, Catalog>>;
+  /** Keys resolved at runtime (e.g. `time.cron.*`) — never reported unused. */
+  ignoreUnused?: readonly string[];
+}
+
+/**
+ * A used key counts as present when the locale defines it *or* any of its plural
+ * variants: `pl` legitimately defines `items_one`/`items_few`/`items_many` and no bare
+ * `items`, and that must not read as a missing key.
+ */
+export function auditCatalogs(input: AuditInput): ExtractReport {
+  const used = [...new Set(input.extraction.usages.map((usage) => usage.key))].sort();
+  const ignore = input.ignoreUnused ?? [];
+
+  const locales: LocaleAudit[] = Object.keys(input.catalogs)
+    .sort()
+    .map((locale) => {
+      const catalog = input.catalogs[locale] ?? {};
+      const missing = used.filter((key) => !definesKey(catalog, key));
+      const usedWithVariants = new Set(used.flatMap(variantsOf));
+      const unused = catalogKeys(catalog).filter(
+        (key) => !usedWithVariants.has(key) && !isIgnored(key, ignore),
+      );
+      return { locale, missing, unused };
+    });
+
+  return {
+    used,
+    usages: input.extraction.usages,
+    dynamic: input.extraction.dynamic,
+    locales,
+    ok: locales.every((audit) => audit.missing.length === 0),
+  };
+}
+
+/** The `x verify` gate. Throws on the first locale with a gap, naming file and keys. */
+export function assertCatalogsComplete(report: ExtractReport): void {
+  for (const audit of report.locales) {
+    if (audit.missing.length > 0) throw catalogMissingKeys(audit.locale, audit.missing);
+  }
+}
+
+/** Merge per-file extractions before auditing. */
+export function mergeExtractions(...extractions: readonly Extraction[]): Extraction {
+  return {
+    usages: extractions.flatMap((extraction) => extraction.usages),
+    dynamic: extractions.flatMap((extraction) => extraction.dynamic),
+  };
+}
+
+/** Read + scan real files. Bun-only by design; the CLI passes the glob results. */
+export async function extractFromFiles(
+  paths: readonly string[],
+  options: ExtractOptions = {},
+): Promise<Extraction> {
+  const extractions = await Promise.all(
+    paths.map(async (path) => extractKeys(await Bun.file(path).text(), path, options)),
+  );
+  return mergeExtractions(...extractions);
+}
+
+function definesKey(catalog: Catalog, key: string): boolean {
+  return variantsOf(key).some((candidate) => Object.hasOwn(catalog, candidate));
+}
+
+function variantsOf(key: string): string[] {
+  return [key, `${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
+}
+
+function isIgnored(key: string, patterns: readonly string[]): boolean {
+  return patterns.some((pattern) =>
+    pattern.endsWith('*') ? key.startsWith(pattern.slice(0, -1)) : key === pattern,
+  );
+}
+
+function positionOf(source: string, index: number): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < index; i += 1) {
+    if (source[i] === '\n') {
+      line += 1;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: index - lineStart + 1 };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}

package/src/framework.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The framework's own strings, flattened once at import.
+ * Register these before app catalogs so an app can override any framework key.
+ */
+import { type Catalog } from './catalog';
+import { type Locale } from './locales';
+/** `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`. */
+export declare const FRAMEWORK_CATALOG: Catalog;
+export declare const FRAMEWORK_CATALOG_LOCALE: Locale;
+/** Called by the HTTP layer at boot. Idempotent. */
+export declare function registerFrameworkCatalog(locale?: Locale): void;
+//# sourceMappingURL=framework.d.ts.map

package/src/framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework.d.ts","sourceRoot":"","sources":["framework.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAe,MAAM,WAAW,CAAC;AAGtD,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAExD,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,EAAE,OAAyB,CAAC;AAE1D,eAAO,MAAM,wBAAwB,EAAE,MAAuB,CAAC;AAE/D,oDAAoD;AACpD,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,MAAiC,GAAG,IAAI,CAExF"}

package/src/framework.js

@@ -0,0 +1,16 @@
+/**
+ * The framework's own strings, flattened once at import.
+ * Register these before app catalogs so an app can override any framework key.
+ */
+import { loadCatalog } from './catalog';
+import en from './catalogs/en.json';
+import { registerCatalog } from './context';
+import { DEFAULT_LOCALE } from './locales';
+/** `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`. */
+export const FRAMEWORK_CATALOG = loadCatalog(en);
+export const FRAMEWORK_CATALOG_LOCALE = DEFAULT_LOCALE;
+/** Called by the HTTP layer at boot. Idempotent. */
+export function registerFrameworkCatalog(locale = FRAMEWORK_CATALOG_LOCALE) {
+    registerCatalog(locale, FRAMEWORK_CATALOG);
+}
+//# sourceMappingURL=framework.js.map

package/src/framework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework.js","sourceRoot":"","sources":["framework.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,WAAW,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAe,MAAM,WAAW,CAAC;AAExD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,iBAAiB,GAAY,WAAW,CAAC,EAAE,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,wBAAwB,GAAW,cAAc,CAAC;AAE/D,oDAAoD;AACpD,MAAM,UAAU,wBAAwB,CAAC,MAAM,GAAW,wBAAwB;IAChF,eAAe,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAC7C,CAAC"}

package/src/framework.ts

@@ -0,0 +1,19 @@
+/**
+ * The framework's own strings, flattened once at import.
+ * Register these before app catalogs so an app can override any framework key.
+ */
+
+import { type Catalog, loadCatalog } from './catalog';
+import en from './catalogs/en.json';
+import { registerCatalog } from './context';
+import { DEFAULT_LOCALE, type Locale } from './locales';
+
+/** `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`. */
+export const FRAMEWORK_CATALOG: Catalog = loadCatalog(en);
+
+export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
+
+/** Called by the HTTP layer at boot. Idempotent. */
+export function registerFrameworkCatalog(locale: Locale = FRAMEWORK_CATALOG_LOCALE): void {
+  registerCatalog(locale, FRAMEWORK_CATALOG);
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+/** Public surface of @ultimat3/i18n. Explicit exports only. */
+export { type Catalog, catalogKeys, flattenCatalog, loadCatalog, mergeCatalogs, missingFrom, type NestedCatalog, parseNestedCatalog, } from './catalog';
+export { attachLocale, catalogFor, configureLocales, currentDirection, currentLocale, currentTranslator, LOCALE_COOKIE, type LocaleConfig, type LocaleResolution, type LocaleSourceName, type LocaleSources, localeConfig, localeCookieOf, localeOf, registerCatalog, registeredLocales, resetCatalogs, resolveLocale, t, translatorFor, } from './context';
+export { catalogInvalid, catalogMissingKeys, I18N_ERROR_CODES, I18nError, type I18nErrorCode, localeUnsupported, } from './errors';
+export { type AuditInput, assertCatalogsComplete, auditCatalogs, type DynamicUsage, type Extraction, type ExtractOptions, type ExtractReport, extractFromFiles, extractKeys, type KeyUsage, type LocaleAudit, mergeExtractions, } from './extract';
+export { FRAMEWORK_CATALOG, FRAMEWORK_CATALOG_LOCALE, registerFrameworkCatalog, } from './framework';
+export { type InterpolationValue, type InterpolationVars, interpolate, PLURAL_CATEGORIES, placeholdersOf, pluralCategory, pluralKeyCandidates, pluralVariantsOf, selectPluralKey, } from './interpolate';
+export { assertSupportedLocale, DEFAULT_LOCALE, type Direction, directionOf, isRtl, isSupportedLocale, type LanguageRange, type Locale, negotiateLocale, normalizeLocale, parseAcceptLanguage, SUPPORTED_LOCALES, } from './locales';
+export { createTranslator, isMiss, type TranslateVars, type Translator } from './translator';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EACL,KAAK,OAAO,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,KAAK,aAAa,EAClB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,CAAC,EACD,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,KAAK,aAAa,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,UAAU,EACf,sBAAsB,EACtB,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,gBAAgB,EAChB,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,SAAS,EACd,WAAW,EACX,KAAK,EACL,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/src/index.js

@@ -0,0 +1,10 @@
+/** Public surface of @ultimat3/i18n. Explicit exports only. */
+export { catalogKeys, flattenCatalog, loadCatalog, mergeCatalogs, missingFrom, parseNestedCatalog, } from './catalog';
+export { attachLocale, catalogFor, configureLocales, currentDirection, currentLocale, currentTranslator, LOCALE_COOKIE, localeConfig, localeCookieOf, localeOf, registerCatalog, registeredLocales, resetCatalogs, resolveLocale, t, translatorFor, } from './context';
+export { catalogInvalid, catalogMissingKeys, I18N_ERROR_CODES, I18nError, localeUnsupported, } from './errors';
+export { assertCatalogsComplete, auditCatalogs, extractFromFiles, extractKeys, mergeExtractions, } from './extract';
+export { FRAMEWORK_CATALOG, FRAMEWORK_CATALOG_LOCALE, registerFrameworkCatalog, } from './framework';
+export { interpolate, PLURAL_CATEGORIES, placeholdersOf, pluralCategory, pluralKeyCandidates, pluralVariantsOf, selectPluralKey, } from './interpolate';
+export { assertSupportedLocale, DEFAULT_LOCALE, directionOf, isRtl, isSupportedLocale, negotiateLocale, normalizeLocale, parseAcceptLanguage, SUPPORTED_LOCALES, } from './locales';
+export { createTranslator, isMiss } from './translator';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EAEL,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EAEX,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,aAAa,EAKb,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,CAAC,EACD,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EAET,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAEL,sBAAsB,EACtB,aAAa,EAKb,gBAAgB,EAChB,WAAW,EAGX,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,cAAc,EAEd,WAAW,EACX,KAAK,EACL,iBAAiB,EAGjB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAuC,MAAM,cAAc,CAAC"}

package/src/index.ts

@@ -0,0 +1,101 @@
+/** Public surface of @ultimat3/i18n. Explicit exports only. */
+
+export {
+  type Catalog,
+  catalogKeys,
+  flattenCatalog,
+  loadCatalog,
+  mergeCatalogs,
+  missingFrom,
+  type NestedCatalog,
+  nestCatalog,
+  parseNestedCatalog,
+} from './catalog';
+export {
+  attachLocale,
+  catalogFor,
+  configureLocales,
+  currentDirection,
+  currentLocale,
+  LOCALE_COOKIE,
+  type LocaleConfig,
+  type LocaleResolution,
+  type LocaleSourceName,
+  type LocaleSources,
+  localeConfig,
+  localeCookieOf,
+  localeOf,
+  registerCatalog,
+  registeredLocales,
+  resetCatalogs,
+  resolveLocale,
+  t,
+  translatorFor,
+  useI18n,
+} from './context';
+export {
+  type CatalogSet,
+  type CatalogSources,
+  type DefineCatalogsInput,
+  defineCatalogs,
+} from './define-catalogs';
+export {
+  catalogInvalid,
+  catalogMissingKeys,
+  I18N_ERROR_CODES,
+  I18N_ERROR_TITLES,
+  I18nError,
+  type I18nErrorCode,
+  localeUnsupported,
+} from './errors';
+export {
+  type AuditInput,
+  assertCatalogsComplete,
+  auditCatalogs,
+  type DynamicUsage,
+  type Extraction,
+  type ExtractOptions,
+  type ExtractReport,
+  extractFromFiles,
+  extractKeys,
+  type KeyUsage,
+  type LocaleAudit,
+  mergeExtractions,
+} from './extract';
+export {
+  FRAMEWORK_CATALOG,
+  FRAMEWORK_CATALOG_LOCALE,
+  registerFrameworkCatalog,
+} from './framework';
+export {
+  type InterpolationValue,
+  type InterpolationVars,
+  interpolate,
+  PLURAL_CATEGORIES,
+  placeholdersOf,
+  pluralCategory,
+  pluralKeyCandidates,
+  pluralVariantsOf,
+  selectPluralKey,
+} from './interpolate';
+export {
+  assertSupportedLocale,
+  DEFAULT_LOCALE,
+  type Direction,
+  directionOf,
+  isRtl,
+  isSupportedLocale,
+  type LanguageRange,
+  type Locale,
+  negotiateLocale,
+  normalizeLocale,
+  parseAcceptLanguage,
+  SUPPORTED_LOCALES,
+} from './locales';
+export {
+  createTranslator,
+  isMiss,
+  type TranslateVars,
+  type TranslationKey,
+  type Translator,
+} from './translator';

package/src/interpolate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `{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 declare const PLURAL_CATEGORIES: readonly Intl.LDMLPluralRule[];
+/**
+ * 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 declare function interpolate(template: string, vars?: InterpolationVars): string;
+/** Variable names a template expects — used by the extractor to flag arity drift. */
+export declare function placeholdersOf(template: string): string[];
+/**
+ * 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 declare function pluralCategory(count: number, locale: string): Intl.LDMLPluralRule;
+/**
+ * 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 declare function pluralKeyCandidates(key: string, count: number, locale: string): string[];
+/** First candidate that exists, per the caller's `has` predicate; falls back to `key`. */
+export declare function selectPluralKey(key: string, count: number, locale: string, has: (candidate: string) => boolean): string;
+/** All suffixed variants of `key` a locale could legitimately define. */
+export declare function pluralVariantsOf(key: string): string[];
+//# sourceMappingURL=interpolate.d.ts.map

package/src/interpolate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["interpolate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAEnE,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,EAAE,SAAS,IAAI,CAAC,cAAc,EAO3D,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAU9E;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,cAAc,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAIxF;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAClC,MAAM,CAKR;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD"}