@ayinza_dev/i18n-config 1.3.0

package/dist/formatters.js

@@ -0,0 +1,163 @@
+// Default locale mappings
+const defaultLocaleMapping = {
+    en: "en-US",
+    ar: "ar-SA",
+    es: "es-ES",
+    fr: "fr-FR",
+    de: "de-DE",
+    zh: "zh-CN",
+    ja: "ja-JP",
+    pt: "pt-BR",
+    it: "it-IT",
+    ru: "ru-RU",
+};
+export class I18nFormatters {
+    normalizeLanguage(code) {
+        const lower = code.toLowerCase();
+        const [base] = lower.split(/[\-_]/);
+        return { full: lower, base };
+    }
+    //Initialize formatter configs
+    constructor(config = {}) {
+        this.fallbackLocale =
+            config.fallbackLocale || defaultLocaleMapping.en || "en-US";
+        this.currencyConfig = {
+            defaultCurrency: config.currency?.defaultCurrency || "USD",
+            localeMapping: {
+                ...defaultLocaleMapping,
+                ...config.currency?.localeMapping,
+            },
+        };
+        this.numberConfig = {
+            localeMapping: {
+                ...defaultLocaleMapping,
+                ...config.number?.localeMapping,
+            },
+        };
+        this.dateConfig = {
+            localeMapping: {
+                ...defaultLocaleMapping,
+                ...config.date?.localeMapping,
+            },
+            defaultFormat: config.date?.defaultFormat || {
+                year: "numeric",
+                month: "long",
+                day: "numeric",
+            },
+        };
+    }
+    getLocale(language, mapping) {
+        const { full, base } = this.normalizeLanguage(language);
+        return mapping[full] || mapping[base] || this.fallbackLocale;
+    }
+    /**
+     * Format with locale-specific formatting
+     */
+    formatCurrency(amount, language, currency, options) {
+        const locale = this.getLocale(language, this.currencyConfig.localeMapping);
+        const currencyCode = currency || this.currencyConfig.defaultCurrency;
+        try {
+            return new Intl.NumberFormat(locale, {
+                style: "currency",
+                currency: currencyCode,
+                ...options,
+            }).format(amount);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Currency formatting error:", error);
+            return `${currencyCode} ${amount}`;
+        }
+    }
+    formatNumber(value, language, options) {
+        const locale = this.getLocale(language, this.numberConfig.localeMapping);
+        try {
+            return new Intl.NumberFormat(locale, options).format(value);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Number formatting error:", error);
+            return String(value);
+        }
+    }
+    formatPercent(value, language, options) {
+        const locale = this.getLocale(language, this.numberConfig.localeMapping);
+        try {
+            return new Intl.NumberFormat(locale, {
+                style: "percent",
+                ...options,
+            }).format(value);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Percent formatting error:", error);
+            return `${value * 100}%`;
+        }
+    }
+    formatDate(date, language, options) {
+        const locale = this.getLocale(language, this.dateConfig.localeMapping);
+        const dateObj = date instanceof Date ? date : new Date(date);
+        if (Number.isNaN(dateObj.getTime())) {
+            return new Date().toLocaleDateString(this.fallbackLocale);
+        }
+        try {
+            return new Intl.DateTimeFormat(locale, {
+                ...this.dateConfig.defaultFormat,
+                ...options,
+            }).format(dateObj);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Date formatting error:", error);
+            return dateObj.toLocaleDateString(this.fallbackLocale);
+        }
+    }
+    formatTime(date, language, options) {
+        const locale = this.getLocale(language, this.dateConfig.localeMapping);
+        const dateObj = date instanceof Date ? date : new Date(date);
+        if (Number.isNaN(dateObj.getTime())) {
+            return new Date().toLocaleTimeString(this.fallbackLocale);
+        }
+        try {
+            return new Intl.DateTimeFormat(locale, {
+                hour: "numeric",
+                minute: "numeric",
+                ...options,
+            }).format(dateObj);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Time formatting error:", error);
+            return dateObj.toLocaleTimeString(this.fallbackLocale);
+        }
+    }
+    formatDateTime(date, language, options) {
+        const locale = this.getLocale(language, this.dateConfig.localeMapping);
+        const dateObj = date instanceof Date ? date : new Date(date);
+        if (Number.isNaN(dateObj.getTime())) {
+            return new Date().toLocaleString(this.fallbackLocale);
+        }
+        try {
+            return new Intl.DateTimeFormat(locale, {
+                year: "numeric",
+                month: "long",
+                day: "numeric",
+                hour: "numeric",
+                minute: "numeric",
+                ...options,
+            }).format(dateObj);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] DateTime formatting error:", error);
+            return dateObj.toLocaleString(this.fallbackLocale);
+        }
+    }
+    formatRelativeTime(value, unit, language, options) {
+        const locale = this.getLocale(language, this.dateConfig.localeMapping);
+        try {
+            return new Intl.RelativeTimeFormat(locale, {
+                numeric: "auto",
+                ...options,
+            }).format(value, unit);
+        }
+        catch (error) {
+            console.error("[i18n-formatters] Relative time formatting error:", error);
+            return `${value} ${unit}`;
+        }
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,111 @@
+export interface UseFormattingReturn {
+    formatCurrency: (amount: number, currency?: string, options?: Intl.NumberFormatOptions) => string;
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+    formatPercent: (value: number, options?: Intl.NumberFormatOptions) => string;
+    formatDate: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatTime: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatDateTime: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatRelativeTime: (value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) => string;
+}
+/**
+ * Custom hook that provides formatting functions based on current language
+ */
+export declare const useFormatting: () => UseFormattingReturn;
+/**
+ * Combined hook that provides both translation and formatting
+ */
+export declare const useI18n: () => {
+    formatCurrency: (amount: number, currency?: string, options?: Intl.NumberFormatOptions) => string;
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+    formatPercent: (value: number, options?: Intl.NumberFormatOptions) => string;
+    formatDate: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatTime: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatDateTime: (date: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+    formatRelativeTime: (value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) => string;
+    0: import("i18next").TFunction<"translation", undefined>;
+    1: import("i18next").i18n;
+    2: boolean;
+    length: 3;
+    toString(): string;
+    toLocaleString(): string;
+    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions & Intl.DateTimeFormatOptions): string;
+    pop(): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined> | undefined;
+    push(...items: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]): number;
+    concat(...items: ConcatArray<boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>[]): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    concat(...items: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined> | ConcatArray<boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>)[]): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    join(separator?: string): string;
+    reverse(): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    shift(): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined> | undefined;
+    slice(start?: number, end?: number): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    sort(compareFn?: ((a: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, b: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>) => number) | undefined): import("react-i18next").UseTranslationResponse<"translation", undefined>;
+    splice(start: number, deleteCount?: number): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    splice(start: number, deleteCount: number, ...items: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    unshift(...items: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]): number;
+    indexOf(searchElement: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, fromIndex?: number): number;
+    lastIndexOf(searchElement: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, fromIndex?: number): number;
+    every<S extends boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => value is S, thisArg?: any): this is S[];
+    every(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => unknown, thisArg?: any): boolean;
+    some(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => unknown, thisArg?: any): boolean;
+    forEach(callbackfn: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => void, thisArg?: any): void;
+    map<U>(callbackfn: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => U, thisArg?: any): U[];
+    filter<S extends boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => value is S, thisArg?: any): S[];
+    filter(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => unknown, thisArg?: any): (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[];
+    reduce(callbackfn: (previousValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>;
+    reduce(callbackfn: (previousValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, initialValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>;
+    reduce<U>(callbackfn: (previousValue: U, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => U, initialValue: U): U;
+    reduceRight(callbackfn: (previousValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>;
+    reduceRight(callbackfn: (previousValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, initialValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>;
+    reduceRight<U>(callbackfn: (previousValue: U, currentValue: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, currentIndex: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => U, initialValue: U): U;
+    find<S extends boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, obj: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => value is S, thisArg?: any): S | undefined;
+    find(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, obj: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => unknown, thisArg?: any): boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined> | undefined;
+    findIndex(predicate: (value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, obj: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => unknown, thisArg?: any): number;
+    fill(value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, start?: number, end?: number): import("react-i18next").UseTranslationResponse<"translation", undefined>;
+    copyWithin(target: number, start: number, end?: number): import("react-i18next").UseTranslationResponse<"translation", undefined>;
+    entries(): ArrayIterator<[number, boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>]>;
+    keys(): ArrayIterator<number>;
+    values(): ArrayIterator<boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>;
+    includes(searchElement: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, fromIndex?: number): boolean;
+    flatMap<U, This = undefined>(callback: (this: This, value: boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>, index: number, array: (boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>)[]) => U | readonly U[], thisArg?: This | undefined): U[];
+    flat<A, D extends number = 1>(this: A, depth?: D | undefined): FlatArray<A, D>[];
+    [Symbol.iterator](): ArrayIterator<boolean | import("i18next").i18n | import("i18next").TFunction<"translation", undefined>>;
+    [Symbol.unscopables]: {
+        [x: number]: boolean | undefined;
+        length?: boolean | undefined;
+        toString?: boolean | undefined;
+        toLocaleString?: boolean | undefined;
+        pop?: boolean | undefined;
+        push?: boolean | undefined;
+        concat?: boolean | undefined;
+        join?: boolean | undefined;
+        reverse?: boolean | undefined;
+        shift?: boolean | undefined;
+        slice?: boolean | undefined;
+        sort?: boolean | undefined;
+        splice?: boolean | undefined;
+        unshift?: boolean | undefined;
+        indexOf?: boolean | undefined;
+        lastIndexOf?: boolean | undefined;
+        every?: boolean | undefined;
+        some?: boolean | undefined;
+        forEach?: boolean | undefined;
+        map?: boolean | undefined;
+        filter?: boolean | undefined;
+        reduce?: boolean | undefined;
+        reduceRight?: boolean | undefined;
+        find?: boolean | undefined;
+        findIndex?: boolean | undefined;
+        fill?: boolean | undefined;
+        copyWithin?: boolean | undefined;
+        entries?: boolean | undefined;
+        keys?: boolean | undefined;
+        values?: boolean | undefined;
+        includes?: boolean | undefined;
+        flatMap?: boolean | undefined;
+        flat?: boolean | undefined;
+        [Symbol.iterator]?: boolean | undefined;
+        readonly [Symbol.unscopables]?: boolean | undefined;
+    };
+    t: import("i18next").TFunction<"translation", undefined>;
+    i18n: import("i18next").i18n;
+    ready: boolean;
+};

package/dist/hooks.js

@@ -0,0 +1,31 @@
+import { useTranslation } from "react-i18next";
+import { getFormatters } from "./config.js";
+import { useMemo } from "react";
+/**
+ * Custom hook that provides formatting functions based on current language
+ */
+export const useFormatting = () => {
+    const { i18n } = useTranslation();
+    const formatters = getFormatters();
+    const currentLanguage = i18n.language;
+    return useMemo(() => ({
+        formatCurrency: (amount, currency, options) => formatters.formatCurrency(amount, currentLanguage, currency, options),
+        formatNumber: (value, options) => formatters.formatNumber(value, currentLanguage, options),
+        formatPercent: (value, options) => formatters.formatPercent(value, currentLanguage, options),
+        formatDate: (date, options) => formatters.formatDate(date, currentLanguage, options),
+        formatTime: (date, options) => formatters.formatTime(date, currentLanguage, options),
+        formatDateTime: (date, options) => formatters.formatDateTime(date, currentLanguage, options),
+        formatRelativeTime: (value, unit, options) => formatters.formatRelativeTime(value, unit, currentLanguage, options),
+    }), [currentLanguage, formatters]);
+};
+/**
+ * Combined hook that provides both translation and formatting
+ */
+export const useI18n = () => {
+    const translation = useTranslation();
+    const formatting = useFormatting();
+    return {
+        ...translation,
+        ...formatting,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { initializeI18n, getI18nInstance, getFormatters, defaultConfig, createI18nConfig, } from "./config.js";
+export type { I18nConfig, I18nInitOptions, FormattersConfig, LocaleMapping, ParserPushConfig, NewKeyPayload, TranslationSnapshot, } from "./types.js";
+export { I18nFormatters } from "./formatters.js";
+export { useFormatting, useI18n } from "./hooks.js";
+export { createI18nextParserConfig } from "./parser-config.js";
+export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, } from "./parser-hooks.js";
+export { useTranslation, Trans, Translation } from "react-i18next";
+export { type TFunction } from "i18next";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { initializeI18n, getI18nInstance, getFormatters, defaultConfig, createI18nConfig, } from "./config.js";
+export { I18nFormatters } from "./formatters.js";
+export { useFormatting, useI18n } from "./hooks.js";
+export { createI18nextParserConfig } from "./parser-config.js";
+export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, } from "./parser-hooks.js";
+// Re-export commonly used utilities from react-i18next
+export { useTranslation, Trans, Translation } from "react-i18next";

package/dist/parser-config.d.ts

@@ -0,0 +1,11 @@
+import type { UserConfig } from "i18next-parser";
+export interface ParserPresetOptions extends Partial<UserConfig> {
+    /** Limit glob set used by the parser. Defaults to src/*.{ts,tsx,js,jsx}. */
+    input?: string | string[];
+    /** Override parser defaults (indentation, separators, lexers etc.). */
+    overrides?: Partial<UserConfig>;
+}
+/**
+ * Create a shared parser config so every portal extracts translations the same way.
+ */
+export declare const createI18nextParserConfig: (options?: ParserPresetOptions) => UserConfig;

package/dist/parser-config.js

@@ -0,0 +1,100 @@
+const defaultInputGlobs = ["src/**/*.{ts,tsx,js,jsx}"];
+const baseLexerFunctions = ["t", "i18next.t"];
+const baseNamespaceFunctions = ["useTranslation", "useI18n"];
+const jsxComponentFunctions = ["Trans", "Translation"];
+const defaultLexers = {
+    js: [
+        {
+            lexer: "JavascriptLexer",
+            functions: baseLexerFunctions,
+            namespaceFunctions: baseNamespaceFunctions,
+        },
+    ],
+    ts: [
+        {
+            lexer: "JavascriptLexer",
+            functions: baseLexerFunctions,
+            namespaceFunctions: baseNamespaceFunctions,
+        },
+    ],
+    jsx: [
+        {
+            lexer: "JsxLexer",
+            functions: baseLexerFunctions,
+            namespaceFunctions: baseNamespaceFunctions,
+            componentFunctions: jsxComponentFunctions,
+            attr: "i18nKey",
+        },
+    ],
+    tsx: [
+        {
+            lexer: "JsxLexer",
+            functions: baseLexerFunctions,
+            namespaceFunctions: baseNamespaceFunctions,
+            componentFunctions: jsxComponentFunctions,
+            attr: "i18nKey",
+        },
+    ],
+    default: [
+        {
+            lexer: "JavascriptLexer",
+            functions: baseLexerFunctions,
+            namespaceFunctions: baseNamespaceFunctions,
+        },
+    ],
+};
+const parserDefaults = {
+    contextSeparator: "_",
+    createOldCatalogs: true,
+    defaultNamespace: "translation",
+    defaultValue: "",
+    indentation: 2,
+    keepRemoved: false,
+    keySeparator: ".",
+    lexers: defaultLexers,
+    lineEnding: "auto",
+    locales: ["en"],
+    namespaceSeparator: ":",
+    output: "locales/$LOCALE/$NAMESPACE.json",
+    pluralSeparator: "_",
+    sort: true,
+    verbose: false,
+    input: defaultInputGlobs,
+};
+const normalizeInput = (input) => {
+    if (!input) {
+        return defaultInputGlobs;
+    }
+    return Array.isArray(input) ? input : [input];
+};
+/**
+ * Create a shared parser config so every portal extracts translations the same way.
+ */
+export const createI18nextParserConfig = (options = {}) => {
+    const { overrides, input, lexers, ...rest } = options;
+    const merged = {
+        ...parserDefaults,
+        ...rest,
+        input: normalizeInput(input ?? parserDefaults.input),
+        lexers: {
+            ...parserDefaults.lexers,
+            ...lexers,
+        },
+    };
+    if (overrides) {
+        merged.input = normalizeInput(overrides.input ?? merged.input);
+        merged.lexers = {
+            ...merged.lexers,
+            ...overrides.lexers,
+        };
+        return {
+            ...merged,
+            ...overrides,
+            lexers: {
+                ...merged.lexers,
+                ...overrides.lexers,
+            },
+        };
+    }
+    return merged;
+};

package/dist/parser-hooks.d.ts

@@ -0,0 +1,23 @@
+import type { NewKeyPayload, ParserPushConfig, TranslationSnapshot } from "./types.js";
+export interface CreateTranslationSnapshotOptions {
+    locale: string;
+    namespaces: Record<string, Record<string, unknown>>;
+}
+export interface CollectNewTranslationKeysOptions {
+    previous?: TranslationSnapshot | null;
+    next: TranslationSnapshot;
+    namespaces?: string[];
+}
+export interface HandleNewTranslationKeysOptions {
+    newKeys: NewKeyPayload[];
+    pushConfig: ParserPushConfig;
+    requestInit?: RequestInit;
+    logger?: Pick<Console, "log" | "warn" | "error">;
+}
+export interface HandleNewTranslationKeysResult {
+    pushed: number;
+    dryRun: boolean;
+}
+export declare const createTranslationSnapshot: (options: CreateTranslationSnapshotOptions) => TranslationSnapshot;
+export declare const collectNewTranslationKeys: (options: CollectNewTranslationKeysOptions) => NewKeyPayload[];
+export declare const handleNewTranslationKeys: (options: HandleNewTranslationKeysOptions) => Promise<HandleNewTranslationKeysResult>;

package/dist/parser-hooks.js

@@ -0,0 +1,125 @@
+const formatValue = (value) => {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+};
+const flattenCatalog = (node, prefix = "", acc = {}) => {
+    for (const [key, value] of Object.entries(node)) {
+        const nextKey = prefix ? `${prefix}.${key}` : key;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            flattenCatalog(value, nextKey, acc);
+        }
+        else {
+            acc[nextKey] = formatValue(value);
+        }
+    }
+    return acc;
+};
+export const createTranslationSnapshot = (options) => {
+    const { locale, namespaces } = options;
+    const entries = {};
+    for (const [namespace, tree] of Object.entries(namespaces)) {
+        entries[namespace] = flattenCatalog(tree);
+    }
+    return { locale, namespaces: entries };
+};
+export const collectNewTranslationKeys = (options) => {
+    const { previous, next } = options;
+    const targetNamespaces = options.namespaces ?? Object.keys(next.namespaces);
+    const additions = [];
+    for (const namespace of targetNamespaces) {
+        const nextEntries = next.namespaces[namespace] ?? {};
+        const prevEntries = previous?.namespaces[namespace] ?? {};
+        for (const [key, defaultValue] of Object.entries(nextEntries)) {
+            if (Object.prototype.hasOwnProperty.call(prevEntries, key)) {
+                continue;
+            }
+            additions.push({
+                key,
+                namespace,
+                defaultValue,
+                locale: next.locale,
+            });
+        }
+    }
+    return additions.sort((a, b) => {
+        const namespaceCompare = a.namespace.localeCompare(b.namespace);
+        if (namespaceCompare !== 0) {
+            return namespaceCompare;
+        }
+        return a.key.localeCompare(b.key);
+    });
+};
+const headersToRecord = (headers) => {
+    if (!headers) {
+        return {};
+    }
+    if (typeof Headers !== "undefined" && headers instanceof Headers) {
+        const out = {};
+        headers.forEach((value, key) => {
+            out[key] = value;
+        });
+        return out;
+    }
+    if (Array.isArray(headers)) {
+        return headers.reduce((acc, [key, value]) => {
+            acc[key] = value;
+            return acc;
+        }, {});
+    }
+    return { ...headers };
+};
+export const handleNewTranslationKeys = async (options) => {
+    const { newKeys, pushConfig, requestInit, logger = console } = options;
+    const dryRun = pushConfig.dryRun || !pushConfig.pushUrl;
+    if (!newKeys.length) {
+        logger.log(`🗒️  No new translation keys for ${pushConfig.portalName}.`);
+        return { pushed: 0, dryRun };
+    }
+    const translations = {};
+    for (const keyEntry of newKeys) {
+        translations[keyEntry.key] = keyEntry.defaultValue;
+    }
+    const payload = {
+        data: {
+            translations,
+        },
+    };
+    if (dryRun) {
+        logger.log(`💡 Dry run for ${pushConfig.portalName}:\n` +
+            newKeys.map((key) => ` • ${key.namespace}:${key.key}`).join("\n"));
+        return { pushed: 0, dryRun: true };
+    }
+    const fetchImpl = pushConfig.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("No fetch implementation available. Provide pushConfig.fetchImpl in non-Node 18 environments.");
+    }
+    const headerBag = {
+        "Content-Type": "application/json",
+        ...pushConfig.headers,
+    };
+    if (pushConfig.authorizationToken && !headerBag.Authorization) {
+        headerBag.Authorization = `Bearer ${pushConfig.authorizationToken}`;
+    }
+    Object.assign(headerBag, headersToRecord(requestInit?.headers));
+    const init = {
+        ...requestInit,
+        method: "POST",
+        body: JSON.stringify(payload),
+        headers: headerBag,
+    };
+    const response = await fetchImpl(pushConfig.pushUrl, init);
+    if (!response.ok) {
+        const errorBody = await response.text().catch(() => "");
+        throw new Error(`Failed to push new translation keys (${response.status}): ${errorBody}`);
+    }
+    logger.log(`✅ Pushed ${newKeys.length} keys for ${pushConfig.portalName}.`);
+    return { pushed: newKeys.length, dryRun: false };
+};

package/dist/remote-catalog.d.ts

@@ -0,0 +1,18 @@
+import { LocalizationConfig } from "./types.js";
+/** Minimal surface of the i18next instance the loader needs. Keeps this module
+ *  decoupled from i18next so it is trivially unit-testable. */
+export interface I18nLike {
+    addResourceBundle(lng: string, ns: string, resources: Record<string, unknown>, deep?: boolean, overwrite?: boolean): void;
+}
+/** Build the catalog URL for a language from the localization config. */
+export declare function buildCatalogUrl(loc: LocalizationConfig, lng: string): string;
+/** Unwrap the Ayinza `{ data: { translations } }` envelope. Tolerates a bare
+ *  `{ translations }` or a flat map, and returns `{}` for anything else. */
+export declare function extractTranslations(payload: unknown): Record<string, string>;
+/**
+ * Create a function that fetches a language's catalog from localization-service
+ * and overlays it (deep-merge, remote wins) onto whatever i18next already holds
+ * for that language. De-duplicates by language; never throws; a failed load is
+ * not marked done, so a later `languageChanged` can retry.
+ */
+export declare function createRemoteCatalogLoader(i18n: I18nLike, loc: LocalizationConfig, ns: string, fetchImpl?: typeof fetch): (lng: string) => Promise<void>;

package/dist/remote-catalog.js

@@ -0,0 +1,51 @@
+const DEFAULT_PATH = "/l10n/translations/{{lng}}";
+/** Build the catalog URL for a language from the localization config. */
+export function buildCatalogUrl(loc, lng) {
+    const path = (loc.path ?? DEFAULT_PATH).replace("{{lng}}", encodeURIComponent(lng));
+    const base = loc.baseUrl.replace(/\/+$/, "");
+    const query = loc.category
+        ? `?category=${encodeURIComponent(loc.category)}`
+        : "";
+    return `${base}${path}${query}`;
+}
+/** Unwrap the Ayinza `{ data: { translations } }` envelope. Tolerates a bare
+ *  `{ translations }` or a flat map, and returns `{}` for anything else. */
+export function extractTranslations(payload) {
+    const p = payload;
+    const translations = p?.data?.translations ?? p?.translations;
+    return translations && typeof translations === "object"
+        ? translations
+        : {};
+}
+/**
+ * Create a function that fetches a language's catalog from localization-service
+ * and overlays it (deep-merge, remote wins) onto whatever i18next already holds
+ * for that language. De-duplicates by language; never throws; a failed load is
+ * not marked done, so a later `languageChanged` can retry.
+ */
+export function createRemoteCatalogLoader(i18n, loc, ns, fetchImpl = fetch) {
+    const handled = new Set();
+    return async function load(lng) {
+        if (!lng || handled.has(lng)) {
+            return;
+        }
+        handled.add(lng);
+        try {
+            const res = await fetchImpl(buildCatalogUrl(loc, lng), loc.headers ? { headers: loc.headers } : undefined);
+            if (!res.ok) {
+                handled.delete(lng);
+                return;
+            }
+            const translations = extractTranslations(await res.json());
+            if (Object.keys(translations).length > 0) {
+                // deep=true, overwrite=true: remote values win over the bundled base;
+                // keys absent remotely keep their bundled-English fallback.
+                i18n.addResourceBundle(lng, ns, translations, true, true);
+            }
+        }
+        catch (err) {
+            handled.delete(lng);
+            console.warn(`[i18n] Failed to load remote catalog for ${lng}:`, err);
+        }
+    };
+}