blendsdk 5.33.0

package/dist/i18n/json-file-source.js

@@ -0,0 +1,258 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, resolve, dirname } from "node:path";
+/**
+ * Translation source that loads from JSON files.
+ *
+ * Supports two file formats:
+ * 1. Multi-locale: `{ key: { locale: value } }` — all locales in one file
+ * 2. Single-locale: `{ key: value }` — one file per locale, locale from filename
+ *
+ * Format is auto-detected per file based on the structure of the first value.
+ *
+ * @example
+ * ```typescript
+ * const source = new JsonFileSource({
+ *     paths: ["./translations/*.json"],
+ * });
+ * const catalog = await source.load();
+ * ```
+ */
+export class JsonFileSource {
+    /** @inheritdoc */
+    name = "JsonFileSource";
+    /** Source configuration */
+    config;
+    /**
+     * Create a new JsonFileSource.
+     *
+     * @param config - File paths or glob patterns configuration
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Load all translations from configured JSON file paths.
+     *
+     * 1. Resolves all glob patterns to file paths
+     * 2. Reads and parses each JSON file
+     * 3. Auto-detects format (multi-locale vs single-locale)
+     * 4. Normalizes into TranslationCatalog entries
+     * 5. Merges all entries (later files override earlier for same key+locale)
+     *
+     * @returns The complete translation catalog from all matched files
+     * @throws Error if a file cannot be read or parsed
+     */
+    async load() {
+        const catalog = {};
+        // Resolve all glob patterns to file paths
+        const filePaths = await resolveGlobs(this.config.paths);
+        for (const filePath of filePaths) {
+            const content = await readFile(filePath, "utf-8");
+            let data;
+            try {
+                data = JSON.parse(content);
+            }
+            catch (error) {
+                throw new Error(`Failed to parse JSON file "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Auto-detect format and normalize into catalog
+            const format = detectFormat(data);
+            if (format === "multi-locale") {
+                // Multi-locale: { key: { locale: value } }
+                mergeMultiLocale(catalog, data);
+            }
+            else {
+                // Single-locale: { key: value }, locale from filename
+                const locale = extractLocaleFromFilename(basename(filePath));
+                mergeSingleLocale(catalog, data, locale);
+            }
+        }
+        return catalog;
+    }
+}
+/**
+ * Create a JsonFileSource instance. Convenience factory for plugin configuration.
+ *
+ * @param config - JSON file source configuration
+ * @returns A new JsonFileSource instance
+ *
+ * @example
+ * ```typescript
+ * app.use(createI18nPlugin({
+ *     sources: [
+ *         jsonFileSource({ paths: ["./translations/*.json"] }),
+ *     ],
+ * }));
+ * ```
+ */
+export function jsonFileSource(config) {
+    return new JsonFileSource(config);
+}
+/**
+ * Detect if a JSON file is multi-locale or single-locale format.
+ *
+ * Heuristic: Look at the first value in the object.
+ * - If it's a string or array → single-locale (flat key→value)
+ * - If it's a plain object → multi-locale (key→{locale: value})
+ * - Empty object → defaults to multi-locale (no keys to process anyway)
+ *
+ * @param data - Parsed JSON object
+ * @returns "multi-locale" or "single-locale"
+ */
+function detectFormat(data) {
+    const firstValue = Object.values(data)[0];
+    // Empty file — treat as multi-locale (no entries either way)
+    if (firstValue === undefined) {
+        return "multi-locale";
+    }
+    // String or array → single-locale format
+    if (typeof firstValue === "string" || Array.isArray(firstValue)) {
+        return "single-locale";
+    }
+    // Object → multi-locale format
+    if (typeof firstValue === "object" && firstValue !== null) {
+        return "multi-locale";
+    }
+    // Fallback: treat as single-locale
+    return "single-locale";
+}
+/**
+ * Extract locale from a filename.
+ *
+ * Supports patterns:
+ * - "en.json" → "en"
+ * - "nl_NL.json" → "nl_NL"
+ * - "translations.en.json" → "en"
+ * - "strings.nl.json" → "nl"
+ *
+ * Uses the last segment before the final .json extension.
+ *
+ * @param filename - The file name (without directory path)
+ * @returns The extracted locale string
+ * @throws Error if no locale can be determined from the filename
+ */
+function extractLocaleFromFilename(filename) {
+    // Remove the .json extension
+    const withoutExt = filename.replace(/\.json$/i, "");
+    // Split by dots and take the last segment
+    const segments = withoutExt.split(".");
+    const locale = segments[segments.length - 1];
+    if (!locale) {
+        throw new Error(`Cannot determine locale from filename "${filename}"`);
+    }
+    return locale;
+}
+/**
+ * Merge a multi-locale file's data into an existing catalog.
+ *
+ * Multi-locale format: { key: { locale: value } }
+ *
+ * @param catalog - The target catalog to merge into (mutated)
+ * @param data - The multi-locale file data
+ */
+function mergeMultiLocale(catalog, data) {
+    for (const [key, localeMap] of Object.entries(data)) {
+        if (!catalog[key]) {
+            catalog[key] = {};
+        }
+        for (const [locale, value] of Object.entries(localeMap)) {
+            // Normalize the value to TranslationValue
+            catalog[key][locale] = normalizeValue(value);
+        }
+    }
+}
+/**
+ * Merge a single-locale file's data into an existing catalog.
+ *
+ * Single-locale format: { key: value } with locale from filename.
+ *
+ * @param catalog - The target catalog to merge into (mutated)
+ * @param data - The single-locale file data
+ * @param locale - The locale extracted from the filename
+ */
+function mergeSingleLocale(catalog, data, locale) {
+    for (const [key, value] of Object.entries(data)) {
+        if (!catalog[key]) {
+            catalog[key] = {};
+        }
+        catalog[key][locale] = normalizeValue(value);
+    }
+}
+/**
+ * Normalize a raw JSON value to a TranslationValue.
+ *
+ * - Strings pass through as-is
+ * - Arrays of exactly 2 strings become [singular, plural] tuples
+ * - Other values are converted to string via String()
+ *
+ * @param value - The raw value from JSON
+ * @returns Normalized TranslationValue
+ */
+function normalizeValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    // Check for plural array [singular, plural]
+    if (Array.isArray(value) && value.length === 2 && typeof value[0] === "string" && typeof value[1] === "string") {
+        return value;
+    }
+    // Fallback: convert to string
+    return String(value);
+}
+/**
+ * Resolve glob patterns to file paths.
+ *
+ * Supports simple glob patterns like "dir/*.json" by listing the
+ * directory and filtering by extension. Non-glob paths are returned
+ * as-is (resolved to absolute).
+ *
+ * @param patterns - Array of file paths or glob patterns
+ * @returns Array of resolved file paths, sorted for deterministic ordering
+ */
+async function resolveGlobs(patterns) {
+    const allPaths = [];
+    for (const pattern of patterns) {
+        // Check if it's a glob pattern (contains * or ?)
+        if (pattern.includes("*") || pattern.includes("?")) {
+            const matches = await expandSimpleGlob(pattern);
+            allPaths.push(...matches);
+        }
+        else {
+            // Plain file path — resolve to absolute
+            allPaths.push(resolve(pattern));
+        }
+    }
+    // Sort for deterministic file ordering
+    return allPaths.sort();
+}
+/**
+ * Expand a simple glob pattern like "dir/*.json" into matching file paths.
+ *
+ * Supports only `*` wildcards in the filename part (not recursive `**`).
+ * This covers the primary use case for translation files without needing
+ * an external glob library.
+ *
+ * @param pattern - A glob pattern (e.g., "./translations/*.json")
+ * @returns Array of matching absolute file paths
+ */
+async function expandSimpleGlob(pattern) {
+    const dir = dirname(pattern);
+    const filePattern = basename(pattern);
+    // Convert glob pattern to regex: * → [^/]*, ? → [^/]
+    const regexStr = filePattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape regex special chars (except * and ?)
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]");
+    const regex = new RegExp(`^${regexStr}$`);
+    try {
+        const entries = await readdir(resolve(dir));
+        return entries
+            .filter((entry) => regex.test(entry))
+            .map((entry) => resolve(dir, entry));
+    }
+    catch {
+        // Directory doesn't exist — return empty (no matches)
+        return [];
+    }
+}
+//# sourceMappingURL=json-file-source.js.map

package/dist/i18n/json-file-source.js.map

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

package/dist/i18n/merge-catalogs.d.ts

@@ -0,0 +1,20 @@
+import type { TranslationCatalog } from "./types.js";
+/**
+ * Merge multiple translation catalogs into one.
+ *
+ * Catalogs are merged in array order. For duplicate key+locale pairs,
+ * the later source wins (predictable override order). This allows
+ * layered translation loading where database overrides can sit on top
+ * of file-based defaults.
+ *
+ * @param catalogs - Array of catalogs to merge (in priority order, last wins)
+ * @returns The merged catalog containing all keys from all sources
+ *
+ * @example
+ * const base = { greeting: { en: "Hello", nl: "Hallo" } };
+ * const overrides = { greeting: { en: "Hi" } };
+ * mergeCatalogs([base, overrides]);
+ * // → { greeting: { en: "Hi", nl: "Hallo" } }
+ */
+export declare function mergeCatalogs(catalogs: TranslationCatalog[]): TranslationCatalog;
+//# sourceMappingURL=merge-catalogs.d.ts.map

package/dist/i18n/merge-catalogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-catalogs.d.ts","sourceRoot":"","sources":["../src/merge-catalogs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,CAgBhF"}

package/dist/i18n/merge-catalogs.js

@@ -0,0 +1,34 @@
+/**
+ * Merge multiple translation catalogs into one.
+ *
+ * Catalogs are merged in array order. For duplicate key+locale pairs,
+ * the later source wins (predictable override order). This allows
+ * layered translation loading where database overrides can sit on top
+ * of file-based defaults.
+ *
+ * @param catalogs - Array of catalogs to merge (in priority order, last wins)
+ * @returns The merged catalog containing all keys from all sources
+ *
+ * @example
+ * const base = { greeting: { en: "Hello", nl: "Hallo" } };
+ * const overrides = { greeting: { en: "Hi" } };
+ * mergeCatalogs([base, overrides]);
+ * // → { greeting: { en: "Hi", nl: "Hallo" } }
+ */
+export function mergeCatalogs(catalogs) {
+    const result = {};
+    for (const catalog of catalogs) {
+        for (const [key, entry] of Object.entries(catalog)) {
+            if (!result[key]) {
+                // First occurrence of this key — copy the entry
+                result[key] = { ...entry };
+            }
+            else {
+                // Merge locale entries — later sources override earlier
+                Object.assign(result[key], entry);
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=merge-catalogs.js.map

package/dist/i18n/merge-catalogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-catalogs.js","sourceRoot":"","sources":["../src/merge-catalogs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAC,QAA8B;IACxD,MAAM,MAAM,GAAuB,EAAE,CAAC;IAEtC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBACf,gDAAgD;gBAChD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACJ,wDAAwD;gBACxD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YACtC,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/i18n/node.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Node.js entry point for @blendsdk/i18n.
+ *
+ * This module re-exports the entire browser-safe core (Translator, mergeCatalogs,
+ * types, TranslationSource) plus the Node.js-only file-based translation sources
+ * (JsonFileSource, ContentFileSource) that depend on `node:fs` and `node:path`.
+ *
+ * **Import paths:**
+ * - `@blendsdk/i18n`      — Browser-safe core (works everywhere)
+ * - `@blendsdk/i18n/node`  — Full package including file-based sources (Node.js only)
+ *
+ * @module @blendsdk/i18n/node
+ */
+export { Translator, mergeCatalogs, } from "./index.js";
+export type { TranslationValue, TranslationEntry, TranslationCatalog, TranslatorConfig, LocaleParts, TranslationSource, } from "./index.js";
+export { JsonFileSource, jsonFileSource } from "./json-file-source.js";
+export type { JsonFileSourceConfig } from "./json-file-source.js";
+export { ContentFileSource, contentFileSource } from "./content-file-source.js";
+export type { ContentFileSourceConfig } from "./content-file-source.js";
+//# sourceMappingURL=node.d.ts.map

package/dist/i18n/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACH,UAAU,EACV,aAAa,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACR,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChF,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/i18n/node.js

@@ -0,0 +1,19 @@
+/**
+ * Node.js entry point for @blendsdk/i18n.
+ *
+ * This module re-exports the entire browser-safe core (Translator, mergeCatalogs,
+ * types, TranslationSource) plus the Node.js-only file-based translation sources
+ * (JsonFileSource, ContentFileSource) that depend on `node:fs` and `node:path`.
+ *
+ * **Import paths:**
+ * - `@blendsdk/i18n`      — Browser-safe core (works everywhere)
+ * - `@blendsdk/i18n/node`  — Full package including file-based sources (Node.js only)
+ *
+ * @module @blendsdk/i18n/node
+ */
+// Re-export everything from the browser-safe core
+export { Translator, mergeCatalogs, } from "./index.js";
+// Node.js-only sources
+export { JsonFileSource, jsonFileSource } from "./json-file-source.js";
+export { ContentFileSource, contentFileSource } from "./content-file-source.js";
+//# sourceMappingURL=node.js.map

package/dist/i18n/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kDAAkD;AAClD,OAAO,EACH,UAAU,EACV,aAAa,GAChB,MAAM,YAAY,CAAC;AAWpB,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/i18n/translation-source.d.ts

@@ -0,0 +1,35 @@
+import type { TranslationCatalog } from "./types.js";
+/**
+ * Abstract interface for translation data sources.
+ *
+ * A TranslationSource loads translations from an external backend
+ * (JSON files, database, remote API, etc.) and returns them as a
+ * TranslationCatalog. Sources are composable — multiple sources
+ * can be loaded and merged into a single catalog.
+ *
+ * Each source implementation is responsible for:
+ * 1. Connecting to its backend (file system, database, etc.)
+ * 2. Reading translation data
+ * 3. Normalizing data into the TranslationCatalog format
+ *
+ * Sources are loaded at application startup and optionally re-loaded
+ * when a reload is triggered (e.g., via pub/sub).
+ */
+export interface TranslationSource {
+    /**
+     * Human-readable name for logging (e.g., "JsonFileSource", "PostgreSQLSource").
+     */
+    readonly name: string;
+    /**
+     * Load all translations from this source.
+     *
+     * Called at application startup and on reload events.
+     * Must return a complete TranslationCatalog.
+     * If the source is unavailable, should throw with a descriptive error.
+     *
+     * @returns The complete translation catalog from this source
+     * @throws Error if the source cannot be read
+     */
+    load(): Promise<TranslationCatalog>;
+}
+//# sourceMappingURL=translation-source.d.ts.map

package/dist/i18n/translation-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-source.d.ts","sourceRoot":"","sources":["../src/translation-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACvC"}

package/dist/i18n/translation-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=translation-source.js.map

package/dist/i18n/translation-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-source.js","sourceRoot":"","sources":["../src/translation-source.ts"],"names":[],"mappings":""}

package/dist/i18n/translator.d.ts

@@ -0,0 +1,162 @@
+import type { TranslationCatalog, TranslationEntry, TranslationValue, TranslatorConfig, LocaleParts } from "./types.js";
+/**
+ * Core translation engine.
+ *
+ * Provides translation lookup with locale fallback, plural support,
+ * and string interpolation via `formatString`. The catalog is treated
+ * as immutable after construction — use `setCatalog()` for atomic
+ * replacement (e.g., on reload).
+ *
+ * Runtime-agnostic: no Node.js or browser-specific APIs.
+ *
+ * @example
+ * ```typescript
+ * const translator = new Translator({
+ *     defaultLocale: "en",
+ *     catalog: {
+ *         greeting: { en: "Hello ${name}", nl: "Hallo ${name}" },
+ *         book: { en: ["${count} book", "${count} books"] },
+ *     },
+ * });
+ *
+ * translator.translate("greeting", "en", { name: "Alice" });
+ * // → "Hello Alice"
+ *
+ * translator.translate("book", "en", { count: 5 });
+ * // → "5 books"
+ * ```
+ */
+export declare class Translator {
+    /** The default locale used when none is specified */
+    protected defaultLocale: string;
+    /** The translation catalog (atomic reference for reload safety) */
+    protected catalog: TranslationCatalog;
+    /** Cache for parsed locale parts to avoid repeated parsing */
+    protected localeCache: Map<string, LocaleParts>;
+    /** Optional callback for missing translations */
+    protected onMissingTranslation?: (key: string, locale: string) => void;
+    /**
+     * Create a new Translator instance.
+     *
+     * @param config - Optional configuration (defaults to "en" locale, empty catalog)
+     */
+    constructor(config?: TranslatorConfig);
+    /**
+     * Translate a key for a given locale with optional parameter interpolation.
+     *
+     * Locale fallback chain: exact locale → language only → key as-is.
+     * Plural selection: if the translation value is a [singular, plural] tuple
+     * and params contains a `count` property, the appropriate form is selected.
+     *
+     * @param key - Translation key (e.g., "greeting", "auth.login")
+     * @param locale - Target locale (e.g., "en_GB", "nl"). Uses defaultLocale if omitted.
+     * @param params - Optional interpolation parameters
+     * @returns The translated, interpolated string
+     *
+     * @example
+     * translator.translate("greeting", "en", { name: "Alice" })
+     * // → "Hello Alice"
+     *
+     * translator.translate("book", "en", { count: 1 })
+     * // → "1 book"
+     *
+     * translator.translate("book", "en", { count: 5 })
+     * // → "5 books"
+     *
+     * translator.translate("unknown.key", "en")
+     * // → "unknown.key" (key returned as-is)
+     */
+    translate(key: string, locale?: string, params?: Record<string, unknown>): string;
+    /**
+     * Get all translations for a specific locale as a flat key-value map.
+     *
+     * Resolves each key using the locale fallback chain (exact → language).
+     * Plural values are returned as-is (the array form) since the client
+     * needs both forms for dynamic count-based selection.
+     *
+     * Primarily used to serve translations to frontend clients.
+     *
+     * @param locale - Target locale (e.g., "en", "nl_NL")
+     * @returns Flat map of { key: resolvedValue } for the locale
+     *
+     * @example
+     * translator.getTranslationsForLocale("nl")
+     * // → { greeting: "Hallo ${name}", book: ["${count} boek", "${count} boeken"] }
+     */
+    getTranslationsForLocale(locale: string): Record<string, TranslationValue>;
+    /**
+     * Check if a translation key exists, optionally for a specific locale.
+     *
+     * @param key - Translation key
+     * @param locale - Optional: check for this specific locale (with fallback)
+     * @returns true if the key exists (and has a value for the locale if specified)
+     */
+    hasKey(key: string, locale?: string): boolean;
+    /**
+     * Atomically replace the translation catalog.
+     *
+     * Used by the reload mechanism to swap in a new catalog without
+     * affecting ongoing translations. The old catalog serves current
+     * requests; the new catalog serves subsequent ones.
+     *
+     * @param catalog - The new translation catalog
+     */
+    setCatalog(catalog: TranslationCatalog): void;
+    /**
+     * Get the current translation catalog.
+     * Primarily useful for testing and debugging.
+     *
+     * @returns The current TranslationCatalog
+     */
+    getCatalog(): TranslationCatalog;
+    /**
+     * Get the configured default locale.
+     * @returns The default locale string
+     */
+    getDefaultLocale(): string;
+    /**
+     * Parse and cache a locale string into its component parts.
+     *
+     * Handles formats like:
+     * - "en" → { full: "en", language: "en" }
+     * - "en_GB" → { full: "en_GB", language: "en", region: "GB" }
+     * - "en-GB" → { full: "en_GB", language: "en", region: "GB" } (normalizes dash to underscore)
+     * - "en_GB.UTF-8" → { full: "en_GB", language: "en", region: "GB" } (strips encoding)
+     *
+     * Results are cached in a Map for O(1) subsequent lookups.
+     *
+     * @param locale - The locale string to parse
+     * @returns Parsed LocaleParts
+     */
+    protected parseLocale(locale: string): LocaleParts;
+    /**
+     * Resolve the best translation value from an entry for a given locale.
+     *
+     * Fallback chain:
+     * 1. Exact match: entry[locale_full] (e.g., entry["en_GB"])
+     * 2. Language match: entry[language] (e.g., entry["en"])
+     * 3. undefined (not found)
+     *
+     * @param entry - The translation entry for a key
+     * @param localeParts - Parsed locale parts
+     * @returns The resolved value, or undefined if no match
+     */
+    protected resolveValue(entry: TranslationEntry, localeParts: LocaleParts): TranslationValue | undefined;
+    /**
+     * Select singular or plural form based on the `count` parameter.
+     *
+     * If the value is a [singular, plural] tuple and params.count exists
+     * and is a number:
+     * - count === 1 → singular (index 0)
+     * - count !== 1 → plural (index 1)
+     *
+     * If the value is a simple string, returns it unchanged.
+     * If count is not a valid number, defaults to singular.
+     *
+     * @param value - The translation value (string or [singular, plural])
+     * @param params - Parameters that may contain a `count` property
+     * @returns The selected string form
+     */
+    protected selectPlural(value: TranslationValue, params?: Record<string, unknown>): string;
+}
+//# sourceMappingURL=translator.d.ts.map

package/dist/i18n/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../src/translator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACR,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,UAAU;IACnB,qDAAqD;IACrD,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;IAEhC,mEAAmE;IACnE,SAAS,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAEtC,8DAA8D;IAC9D,SAAS,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAEhD,iDAAiD;IACjD,SAAS,CAAC,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvE;;;;OAIG;gBACS,MAAM,CAAC,EAAE,gBAAgB;IAOrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IA2BjF;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAc1E;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO;IAU7C;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAM7C;;;;;OAKG;IACH,UAAU,IAAI,kBAAkB;IAIhC;;;OAGG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW;IA4BlD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,YAAY,CAClB,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,WAAW,GACzB,gBAAgB,GAAG,SAAS;IAe/B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;CAe5F"}