@mmstack/translate 20.5.10 → 20.5.12

package/index.d.ts

@@ -1,5 +1,6 @@
-import * as i0 from '@angular/core';
-import { Signal, WritableSignal, Provider } from '@angular/core';
+import * as _angular_core from '@angular/core';
+import { Signal, Provider, WritableSignal } from '@angular/core';
+import * as _mmstack_translate from '@mmstack/translate';
 import { ResolveFn, ActivatedRouteSnapshot, CanMatchFn } from '@angular/router';
 import * as _formatjs_intl from '@formatjs/intl';
 import { IntlConfig } from '@formatjs/intl';
@@ -23,7 +24,28 @@ type extractParams<T extends string> = T extends `${infer _Start}{${infer Var}}$
 type mergeParams<TExtracted extends [string, any]> = {
     [K in TExtracted as K[0]]: K[1];
 };
-type flattenParams<TKey extends string, TVal> = TVal extends UnknownStringKeyObject ? inferParamTupples<TVal, `${TKey}.`> : TVal extends string ? extractParams<TVal> extends never ? [TKey] : [TKey, mergeParams<extractParams<TVal>>] : never;
+declare const PARAM_BRAND: unique symbol;
+/**
+ * Branded string type produced by `withParams<P>(message)`. The brand carries
+ * both the declared parameter shape `P` and the original literal message `S` —
+ * the literal lives inside the brand (not just on the intersection) so the
+ * inference machinery can recover it without going through template-literal
+ * pattern matching on a branded intersection (which widens `infer` slots to
+ * `string` and breaks auto-extraction). Module-local `unique symbol`, so the
+ * brand is not constructible outside this package.
+ */
+type WithParams<P extends Record<string, unknown>, S extends string = string> = S & {
+    readonly [PARAM_BRAND]: {
+        params: P;
+        literal: S;
+    };
+};
+type flattenParams<TKey extends string, TVal> = TVal extends {
+    readonly [PARAM_BRAND]: {
+        params: infer P;
+        literal: infer S extends string;
+    };
+} ? P extends Record<string, unknown> ? extractParams<S> extends never ? [TKey, P] : [TKey, Omit<mergeParams<extractParams<S>>, keyof P> & P] : [TKey] : TVal extends UnknownStringKeyObject ? inferParamTupples<TVal, `${TKey}.`> : TVal extends string ? extractParams<TVal> extends never ? [TKey] : [TKey, mergeParams<extractParams<TVal>>] : never;
 type inferParamTupples<T extends UnknownStringKeyObject, TPrefix extends string = ''> = Simplify<{
     [K in keyof T]: K extends string ? flattenParams<`${TPrefix}${K}`, T[K]> : never;
 }[keyof T]>;
@@ -35,7 +57,9 @@ type TypeEnsuringAllPlaceholders<PlaceholdersUnion extends string> = StringConta
 type extractParamString<T extends string> = T extends `${infer _Start}{${infer Var}}${infer End}` ? Var extends `${infer VarName},${string}` ? `{${VarName}, ${string}}` | extractParamString<End> : `{${Var}}` | extractParamString<End> : never;
 type inferParamsFromValue<V extends string> = extractParamString<V> extends never ? string : TypeEnsuringAllPlaceholders<extractParamString<V>>;
 type inferTranslationShape<T extends UnknownStringKeyObject> = {
-    [K in keyof T]: T[K] extends UnknownStringKeyObject ? inferTranslationShape<T[K]> : T[K] extends string ? inferParamsFromValue<T[K]> : never;
+    [K in keyof T]: T[K] extends {
+        readonly [PARAM_BRAND]: any;
+    } ? string : T[K] extends UnknownStringKeyObject ? inferTranslationShape<T[K]> : T[K] extends string ? inferParamsFromValue<T[K]> : never;
 };
 
 declare const INTERNAL_SYMBOL: unique symbol;
@@ -67,7 +91,48 @@ type TranslationNamespace<TNS extends string, T extends CompiledTranslation<Unkn
 };
 declare function createNamespace<const T extends UnknownStringKeyObject, TNS extends string>(ns: TNS, translation: T): TranslationNamespace<TNS, CompiledTranslation<T, TNS, string>, inferTranslationShape<T>>;
 
-declare const FORMAT_PRESETS: Record<string, Intl.DateTimeFormatOptions>;
+declare const FORMAT_PRESETS: {
+    short: {
+        dateStyle: "short";
+        timeStyle: "short";
+    };
+    medium: {
+        dateStyle: "medium";
+        timeStyle: "medium";
+    };
+    long: {
+        dateStyle: "long";
+        timeStyle: "long";
+    };
+    full: {
+        dateStyle: "full";
+        timeStyle: "full";
+    };
+    shortDate: {
+        dateStyle: "short";
+    };
+    mediumDate: {
+        dateStyle: "medium";
+    };
+    longDate: {
+        dateStyle: "long";
+    };
+    fullDate: {
+        dateStyle: "full";
+    };
+    shortTime: {
+        timeStyle: "short";
+    };
+    mediumTime: {
+        timeStyle: "medium";
+    };
+    longTime: {
+        timeStyle: "long";
+    };
+    fullTime: {
+        timeStyle: "full";
+    };
+};
 type DateFormat = keyof typeof FORMAT_PRESETS;
 /**
  * Supported date inputs
@@ -85,21 +150,43 @@ type FormatDateOptions = {
      * Format to use for formatting
      * @default 'medium'
      */
-    format?: DateFormat;
+    format?: DateFormat | Intl.DateTimeFormatOptions;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatDateOptions = Omit<FormatDateOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 /**
- * Format a date using the current or provided locale & timezone
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param date - Date to format
- * @param opt - Options for formatting
- * @returns Formatted date string
+ * @example formatDate(this.date, this.locale)
+ */
+declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, locale: string | Signal<string>): string;
+/**
+ * @example formatDate(this.date, { locale: 'sl-SI', format: 'shortDate' })
+ */
+declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt: FormatDateOptions | Signal<FormatDateOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatDate()` instead, or pass locale explicitly.
+ * @example formatDate(this.date)
+ */
+declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt?: UnsafeFormatDateOptions | Signal<UnsafeFormatDateOptions>): string;
+declare const provideFormatDateDefaults: (valueOrFn: Omit<Partial<FormatDateOptions>, "locale"> | (() => Omit<Partial<FormatDateOptions>, "locale"> | Signal<Omit<Partial<FormatDateOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe date formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatDate = injectFormatDate();
+ * readonly displayDate = computed(() => formatDate(this.date()));
  */
-declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput>, opt?: FormatDateOptions | Signal<FormatDateOptions>): string;
+declare function injectFormatDate(): (date: SupportedDateInput | Signal<SupportedDateInput>, optOrLocale?: Partial<FormatDateOptions> | Signal<Partial<FormatDateOptions>> | string | Signal<string>) => string;
 
 /**
  * Options for formatting a display name
@@ -107,24 +194,46 @@ declare function formatDate(date: SupportedDateInput | Signal<SupportedDateInput
 type FormatDisplayNameOptions = {
     /**
      * The display style for the result set
+     * @default 'long'
      */
-    style: Intl.RelativeTimeFormatStyle;
+    style?: Intl.RelativeTimeFormatStyle;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatDisplayNameOptions = Omit<FormatDisplayNameOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 type SupportedCode = string | null | undefined;
 /**
- * Format a display name using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The code to format
- * @param type - The type of display name to format
- * @param opt - Options for formatting
- * @returns Formatted display name string
+ * @example formatDisplayName(this.value, 'region', this.locale)
+ */
+declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, locale: string | Signal<string>): string;
+/**
+ * @example formatDisplayName(this.value, 'region', {locale: 'en-US', style: 'long'})
+ */
+declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatDisplayName()` instead, or pass locale explicitly.
+ * @example formatDisplayName(this.value)
+ */
+declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt?: UnsafeFormatDisplayNameOptions | Signal<UnsafeFormatDisplayNameOptions>): string;
+declare const provideFormatDisplayNameDefaults: (valueOrFn: Omit<Partial<FormatDisplayNameOptions>, "locale"> | (() => Omit<Partial<FormatDisplayNameOptions>, "locale"> | Signal<Omit<Partial<FormatDisplayNameOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe date formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatDisplayName = injectFormatDisplayName();
+ * readonly region = computed(() => formatDisplayName('US', 'region'));
  */
-declare function formatDisplayName(value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, opt?: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions>): string;
+declare function injectFormatDisplayName(): (value: SupportedCode | Signal<SupportedCode>, type: Intl.DisplayNamesType | Signal<Intl.DisplayNamesType>, localeOrOpt?: FormatDisplayNameOptions | Signal<FormatDisplayNameOptions> | string | Signal<string>) => string;
 
 type ListType = 'conjunction' | 'disjunction' | 'unit';
 type ListStyle = 'long' | 'short' | 'narrow';
@@ -135,26 +244,50 @@ type SupportedListInput = string[] | null | undefined;
 type FormatListOptions = {
     /**
      * The type of list to format
+     * @default 'conjunction'
      */
     type?: ListType;
     /**
      * The style of list to format
+     * @default 'long'
      */
     style?: ListStyle;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatListOptions = Omit<FormatListOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 /**
- * Format a list using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The list to format
- * @param opt - Options for formatting
- * @returns Formatted list string
+ * @example formatList(this.items, this.locale)
  */
-declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt?: FormatListOptions | Signal<FormatListOptions>): string;
+declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, locale: string | Signal<string>): string;
+/**
+ * @example formatList(this.items, { locale: 'sl-SI', type: 'disjunction' })
+ */
+declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt: FormatListOptions | Signal<FormatListOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatList()` instead, or pass locale explicitly.
+ * @example formatList(this.items)
+ */
+declare function formatList(value: SupportedListInput | Signal<SupportedListInput>, opt?: UnsafeFormatListOptions | Signal<UnsafeFormatListOptions>): string;
+declare const provideFormatListDefaults: (valueOrFn: Omit<Partial<FormatListOptions>, "locale"> | (() => Omit<Partial<FormatListOptions>, "locale"> | Signal<Omit<Partial<FormatListOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe list formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatList = injectFormatList();
+ * readonly displayList = computed(() => formatList(this.items()));
+ */
+declare function injectFormatList(): (value: SupportedListInput | Signal<SupportedListInput>, optOrLocale?: Partial<FormatListOptions> | Signal<Partial<FormatListOptions>> | string | Signal<string>) => string;
 
 type NumberNotation = 'standard' | 'scientific' | 'engineering' | 'compact';
 type SupportedNumberValue = number | null | undefined;
@@ -164,6 +297,7 @@ type SupportedNumberValue = number | null | undefined;
 type FormatNumberOptions = {
     /**
      * The notation to use for formatting
+     * @default 'standard'
      */
     notation?: NumberNotation;
     /**
@@ -176,27 +310,50 @@ type FormatNumberOptions = {
     maxFractionDigits?: number;
     /**
      * Whether to use grouping
+     * @default true
      */
     useGrouping?: boolean;
-    /**
-     * Locale to use for formatting, opts out to dynamic locale changes
-     */
-    locale?: string;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
 };
 /**
- * Format a number using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param number - Number to format
- * @param opt - Options for formatting
- * @returns Formatted number string
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatNumberOptions = Omit<FormatNumberOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
+};
+/**
+ * @example formatNumber(this.value, this.locale)
+ */
+declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, locale: string | Signal<string>): string;
+/**
+ * @example formatNumber(this.value, { locale: 'de-DE', notation: 'compact' })
+ */
+declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt: FormatNumberOptions | Signal<FormatNumberOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatNumber()` instead, or pass locale explicitly.
+ * @example formatNumber(this.value)
+ */
+declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: UnsafeFormatNumberOptions | Signal<UnsafeFormatNumberOptions>): string;
+declare const provideFormatNumberDefaults: (valueOrFn: Omit<Partial<FormatNumberOptions>, "locale"> | (() => Omit<Partial<FormatNumberOptions>, "locale"> | Signal<Omit<Partial<FormatNumberOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe number formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatNumber = injectFormatNumber();
+ * readonly display = computed(() => formatNumber(this.value()));
  */
-declare function formatNumber(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatNumberOptions | Signal<FormatNumberOptions>): string;
+declare function injectFormatNumber(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, optOrLocale?: Partial<FormatNumberOptions> | Signal<Partial<FormatNumberOptions>> | string | Signal<string>) => string;
 /**
  * Options for formatting a percentage value
  */
@@ -209,42 +366,97 @@ type FormatPercentOptions = {
      * Maximum number of fraction digits to use
      */
     maxFractionDigits?: number;
-    /**
-     * Locale to use for formatting, opts out to dynamic locale changes
-     */
-    locale?: string;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
 };
 /**
- * Format a percentage using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param number - Number to format
- * @param opt - Options for formatting
- * @returns Formatted percentage string
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
  */
-declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: FormatPercentOptions | Signal<FormatPercentOptions>): string;
+type UnsafeFormatPercentOptions = Omit<FormatPercentOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
+};
+/**
+ * @example formatPercent(this.value, this.locale)
+ */
+declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, locale: string | Signal<string>): string;
+/**
+ * @example formatPercent(this.value, { locale: 'de-DE', maxFractionDigits: 2 })
+ */
+declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt: FormatPercentOptions | Signal<FormatPercentOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatPercent()` instead, or pass locale explicitly.
+ * @example formatPercent(this.value)
+ */
+declare function formatPercent(value: SupportedNumberValue | Signal<SupportedNumberValue>, opt?: UnsafeFormatPercentOptions | Signal<UnsafeFormatPercentOptions>): string;
+declare const provideFormatPercentDefaults: (valueOrFn: Omit<Partial<FormatPercentOptions>, "locale"> | (() => Omit<Partial<FormatPercentOptions>, "locale"> | Signal<Omit<Partial<FormatPercentOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe percent formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ */
+declare function injectFormatPercent(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, optOrLocale?: Partial<FormatPercentOptions> | Signal<Partial<FormatPercentOptions>> | string | Signal<string>) => string;
 type CurrencyDisplay = 'symbol' | 'narrowSymbol' | 'code' | 'name';
 /**
  * Options for formatting a currency
  */
 type FormatCurrencyOptions = {
-    display?: CurrencyDisplay;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * The display type for the currency format
+     * @default 'symbol'
      */
-    locale?: string;
+    display?: CurrencyDisplay;
     /**
      * If the number is not a valid number, return formatted 0. By default formatter returns an empty string
      * @default false
      */
     fallbackToZero?: boolean;
+    /**
+     * Locale to use for formatting
+     */
+    locale: string;
 };
-declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt?: FormatCurrencyOptions | Signal<FormatCurrencyOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatCurrencyOptions = Omit<FormatCurrencyOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
+    locale?: string;
+};
+/**
+ * @example formatCurrency(this.value, 'USD', this.locale)
+ */
+declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, locale: string | Signal<string>): string;
+/**
+ * @example formatCurrency(this.value, 'EUR', { locale: 'de-DE', display: 'code' })
+ */
+declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt: FormatCurrencyOptions | Signal<FormatCurrencyOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatCurrency()` instead, or pass locale explicitly.
+ * @example formatCurrency(this.value, 'USD')
+ */
+declare function formatCurrency(value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, opt?: UnsafeFormatCurrencyOptions | Signal<UnsafeFormatCurrencyOptions>): string;
+declare const provideFormatCurrencyDefaults: (valueOrFn: Omit<Partial<FormatCurrencyOptions>, "locale"> | (() => Omit<Partial<FormatCurrencyOptions>, "locale"> | Signal<Omit<Partial<FormatCurrencyOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe currency formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ */
+declare function injectFormatCurrency(): (value: SupportedNumberValue | Signal<SupportedNumberValue>, currency: string | Signal<string>, optOrLocale?: Partial<FormatCurrencyOptions> | Signal<Partial<FormatCurrencyOptions>> | string | Signal<string>) => string;
+
+declare function createFormatterProvider<T extends {
+    locale: string;
+}>(formatterName: string, libraryDefaults: Omit<T, 'locale'>, nonLocaleEqual: (a: Omit<T, 'locale'>, b: Omit<T, 'locale'>) => boolean): readonly [(valueOrFn: Omit<Partial<T>, "locale"> | (() => Omit<Partial<T>, "locale"> | Signal<Omit<Partial<T>, "locale">>)) => Provider, () => Signal<T>];
+type inferProvideParameter<T extends ReturnType<typeof createFormatterProvider>[0]> = Parameters<T>[0];
 
 /**
  * Options for formatting a relative time value
@@ -261,22 +473,63 @@ type FormatRelativeTimeOptions = {
      */
     numeric?: Intl.RelativeTimeFormatNumeric;
     /**
-     * Locale to use for formatting, opts out to dynamic locale changes
+     * Locale to use for formatting
      */
+    locale: string;
+};
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. Omiting the locale property forces a fallback to a process-level global singleton.
+ */
+type UnsafeFormatRelativeTimeOptions = Omit<FormatRelativeTimeOptions, 'locale'> & {
+    /** Optional locale string falling back to the legacy global signal */
     locale?: string;
 };
 type RelativeTimeUnit = Intl.RelativeTimeFormatUnit;
 type SupportedRelativeTimeInput = number | null | undefined;
 /**
- * Format a relative time using the current or provided locale
- * By default it is reactive to the global dynamic locale, works best when wrapped in a computed() if you need to react to locale changes
- *
- * @param value - The numeric value to use in the relative time internationalization message
- * @param unit - The unit to use in the relative time internationalization message
- * @param opt - Options for formatting
- * @returns Formatted relative time string
+ * @example formatRelativeTime(this.value, this.unit, this.locale)
+ */
+declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, locale: string | Signal<string>): string;
+/**
+ * @example formatRelativeTime(this.value, 'day', { locale: 'sl-SI', numeric: 'auto' })
+ */
+declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt: FormatRelativeTimeOptions | Signal<FormatRelativeTimeOptions>): string;
+/**
+ * @deprecated UNSAFE FOR SSR/EDGE. This signature reads from a process-level global singleton, will be fully removed when Angular 23 drops
+ * Use `injectFormatRelativeTime()` instead, or pass locale explicitly.
+ * @example formatRelativeTime(this.value, 'day')
  */
-declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt?: FormatRelativeTimeOptions | Signal<FormatRelativeTimeOptions>): string;
+declare function formatRelativeTime(value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, opt?: UnsafeFormatRelativeTimeOptions | Signal<UnsafeFormatRelativeTimeOptions>): string;
+declare const provideFormatRelativeTimeDefaults: (valueOrFn: Omit<Partial<FormatRelativeTimeOptions>, "locale"> | (() => Omit<Partial<FormatRelativeTimeOptions>, "locale"> | Signal<Omit<Partial<FormatRelativeTimeOptions>, "locale">>)) => _angular_core.Provider;
+
+/**
+ * Inject a context-safe relative time formatting function tied to the current injector.
+ * Uses the libraries locale signal & provided default configuration to react to locale/config changes
+ * @example
+ * const formatRelativeTime = injectFormatRelativeTime();
+ * readonly relativeAge = computed(() => formatRelativeTime(this.delta(), 'day'));
+ */
+declare function injectFormatRelativeTime(): (value: SupportedRelativeTimeInput | Signal<SupportedRelativeTimeInput>, unit: RelativeTimeUnit | Signal<RelativeTimeUnit>, optOrLocale?: Partial<FormatRelativeTimeOptions> | Signal<Partial<FormatRelativeTimeOptions>> | string | Signal<string>) => string;
+
+type FormatDefaults = {
+    date?: inferProvideParameter<typeof provideFormatDateDefaults>;
+    displayName?: inferProvideParameter<typeof provideFormatDisplayNameDefaults>;
+    list?: inferProvideParameter<typeof provideFormatListDefaults>;
+    relativeTime?: inferProvideParameter<typeof provideFormatRelativeTimeDefaults>;
+    number?: inferProvideParameter<typeof provideFormatNumberDefaults>;
+    percent?: inferProvideParameter<typeof provideFormatPercentDefaults>;
+    currency?: inferProvideParameter<typeof provideFormatCurrencyDefaults>;
+};
+declare function provideFormatDefaults(cfg: FormatDefaults): Provider[];
+declare function injectFormatters(): {
+    date: (date: _mmstack_translate.SupportedDateInput | _angular_core.Signal<_mmstack_translate.SupportedDateInput>, optOrLocale?: Partial<_mmstack_translate.FormatDateOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatDateOptions>> | string | _angular_core.Signal<string>) => string;
+    displayName: (value: (string | null | undefined) | _angular_core.Signal<string | null | undefined>, type: Intl.DisplayNamesType | _angular_core.Signal<Intl.DisplayNamesType>, localeOrOpt?: _mmstack_translate.FormatDisplayNameOptions | _angular_core.Signal<_mmstack_translate.FormatDisplayNameOptions> | string | _angular_core.Signal<string>) => string;
+    list: (value: _mmstack_translate.SupportedListInput | _angular_core.Signal<_mmstack_translate.SupportedListInput>, optOrLocale?: Partial<_mmstack_translate.FormatListOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatListOptions>> | string | _angular_core.Signal<string>) => string;
+    relativeTime: (value: (number | null | undefined) | _angular_core.Signal<number | null | undefined>, unit: _mmstack_translate.RelativeTimeUnit | _angular_core.Signal<_mmstack_translate.RelativeTimeUnit>, optOrLocale?: Partial<_mmstack_translate.FormatRelativeTimeOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatRelativeTimeOptions>> | string | _angular_core.Signal<string>) => string;
+    number: (value: (number | null | undefined) | _angular_core.Signal<number | null | undefined>, optOrLocale?: Partial<_mmstack_translate.FormatNumberOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatNumberOptions>> | string | _angular_core.Signal<string>) => string;
+    percent: (value: (number | null | undefined) | _angular_core.Signal<number | null | undefined>, optOrLocale?: Partial<_mmstack_translate.FormatPercentOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatPercentOptions>> | string | _angular_core.Signal<string>) => string;
+    currency: (value: (number | null | undefined) | _angular_core.Signal<number | null | undefined>, currency: string | _angular_core.Signal<string>, optOrLocale?: Partial<_mmstack_translate.FormatCurrencyOptions> | _angular_core.Signal<Partial<_mmstack_translate.FormatCurrencyOptions>> | string | _angular_core.Signal<string>) => string;
+};
 
 type BaseConfig = Omit<IntlConfig, 'locale' | 'messages'> & {
     /** Checks next locale is in provided array before switching locales */
@@ -326,6 +579,24 @@ declare function injectIntl(): Signal<_formatjs_intl.IntlShape<string>>;
 declare function injectDynamicLocale(): WritableSignal<string> & {
     isLoading: Signal<boolean>;
 };
+/**
+ * Power-user escape hatch for adding translations imperatively (e.g. content
+ * loaded from a remote API after bootstrap). Returns a function that registers
+ * a flat per-locale map of keys under a given namespace
+ *
+ * Pair with {@link injectUnsafeT} to read the added keys without compile-time
+ * constraints.
+ *
+ * @example
+ * ```ts
+ * const addTranslations = injectAddTranslations();
+ * addTranslations('remote', {
+ *   'en-US': { greeting: 'Hi {name}' },
+ *   'sl-SI': { greeting: 'Zdravo {name}' },
+ * });
+ * ```
+ */
+declare function injectAddTranslations(): (ns: string, translations: Record<string, Record<string, string>>) => void;
 
 type TFunction<TMap extends AnyStringRecord> = <TKey extends keyof TMap & string>(key: TKey, ...args: TMap[TKey] extends void ? [] : [TMap[TKey]]) => string;
 type SignalTFunction<TMap extends AnyStringRecord> = <TKey extends keyof TMap & string>(key: TKey, ...args: TMap[TKey] extends void ? [] : [() => TMap[TKey]]) => Signal<string>;
@@ -348,6 +619,23 @@ declare function registerRemoteNamespace<TNS extends string>(ns: TNS, defaultTra
     injectNamespaceT: () => UntypedTFunction<TNS>;
     resolveNamespaceTranslation: ResolveFn<void>;
 };
+/**
+ * Power-user escape hatch that returns a fully untyped translation function.
+ * Intended for use alongside {@link injectAddTranslations} when translations
+ * are added imperatively (e.g. from a remote API), or for cross-namespace
+ * lookups where the typed API would be impractical.
+ *
+ * @example
+ * ```ts
+ * const t = injectUnsafeT();
+ * t('any.namespace.key', { name: 'Alice', count: 3 });
+ * const sig = t.asSignal('any.namespace.key', () => ({ name: name() }));
+ * ```
+ */
+declare function injectUnsafeT(): {
+    (key: string, params?: Record<string, string | number>): string;
+    asSignal(key: string, params?: () => Record<string, string | number>): Signal<string>;
+};
 
 declare function injectResolveParamLocale(snapshot: ActivatedRouteSnapshot): string;
 
@@ -426,10 +714,10 @@ declare function provideMockTranslations(options?: MockTranslationOptions): Prov
 
 declare abstract class Translate<TInput extends string, T extends CompiledTranslation<UnknownStringKeyObject, string>, TMap extends inferCompiledTranslationMap<T> = inferCompiledTranslationMap<T>, TKey extends TInput & keyof TMap & string = TInput & keyof TMap & string> {
     private readonly t;
-    readonly translate: i0.InputSignal<TMap[TKey] extends void ? TKey | [key: TKey] : [key: TKey, vars: TMap[TKey]]>;
+    readonly translate: _angular_core.InputSignal<TMap[TKey] extends void ? TKey | [key: TKey] : [key: TKey, vars: TMap[TKey]]>;
     constructor();
-    static ɵfac: i0.ɵɵFactoryDeclaration<Translate<any, any, any, any>, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<Translate<any, any, any, any>, never, never, { "translate": { "alias": "translate"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Translate<any, any, any, any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Translate<any, any, any, any>, never, never, { "translate": { "alias": "translate"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 type TransformTFn<T extends CompiledTranslation<UnknownStringKeyObject, string>, TMap extends inferCompiledTranslationMap<T>> = <TKey extends keyof TMap & string>(key: TKey, ...args: TMap[TKey] extends void ? [locale?: string] : [TMap[TKey], locale?: string]) => string;
@@ -438,5 +726,30 @@ declare abstract class Translator<T extends CompiledTranslation<UnknownStringKey
     transform: TransformTFn<T, TMap>;
 }
 
-export { Translate, Translator, canMatchLocale, compileTranslation, createNamespace, formatCurrency, formatDate, formatDisplayName, formatList, formatNumber, formatPercent, formatRelativeTime, injectDynamicLocale, injectIntl, injectResolveParamLocale, injectSupportedLocales, provideIntlConfig, provideMockTranslations, registerNamespace, registerRemoteNamespace };
-export type { CompiledTranslation, FormatCurrencyOptions, FormatDateOptions, FormatDisplayNameOptions, FormatListOptions, FormatNumberOptions, FormatPercentOptions, FormatRelativeTimeOptions, RelativeTimeUnit, SupportedDateInput, SupportedListInput, inferCompiledTranslationMap, inferCompiledTranslationNamespace, inferCompiledTranslationShape, mergeTranslationMaps };
+/**
+ * Power-user escape hatch for ICU messages whose parameters can't be inferred
+ * from the message string — typically variables nested inside `plural` /
+ * `select` / `selectordinal` arms, which the type-level extractor skips.
+ *
+ * Declared params are merged with auto-extracted ones; on key conflict, the
+ * declared params win. Non-default locales for a key wrapped with `withParams`
+ * may be plain strings — they don't need to repeat the wrapper.
+ *
+ * @example
+ * ```ts
+ * const ns = createNamespace('quote', {
+ *   // auto-extracts `count`; `name` is declared explicitly because it
+ *   // lives inside the plural arms and can't be inferred
+ *   stats: withParams<{ name: string }>(
+ *     '{count, plural, one {1 quote from {name}} other {# quotes from {name}}}',
+ *   ),
+ * });
+ *
+ * // t inferred as: (key, { count: number; name: string }) => string
+ * t('quote.stats', { count: 3, name: 'Alice' });
+ * ```
+ */
+declare function withParams<const P extends Record<string, unknown>, const S extends string = string>(message: S): WithParams<P, S>;
+
+export { Translate, Translator, canMatchLocale, compileTranslation, createNamespace, formatCurrency, formatDate, formatDisplayName, formatList, formatNumber, formatPercent, formatRelativeTime, injectAddTranslations, injectDynamicLocale, injectFormatCurrency, injectFormatDate, injectFormatDisplayName, injectFormatList, injectFormatNumber, injectFormatPercent, injectFormatRelativeTime, injectFormatters, injectIntl, injectResolveParamLocale, injectSupportedLocales, injectUnsafeT, provideFormatCurrencyDefaults, provideFormatDateDefaults, provideFormatDefaults, provideFormatDisplayNameDefaults, provideFormatListDefaults, provideFormatNumberDefaults, provideFormatPercentDefaults, provideFormatRelativeTimeDefaults, provideIntlConfig, provideMockTranslations, registerNamespace, registerRemoteNamespace, withParams };
+export type { CompiledTranslation, FormatCurrencyOptions, FormatDateOptions, FormatDisplayNameOptions, FormatListOptions, FormatNumberOptions, FormatPercentOptions, FormatRelativeTimeOptions, RelativeTimeUnit, SupportedDateInput, SupportedListInput, UnsafeFormatCurrencyOptions, UnsafeFormatDateOptions, UnsafeFormatDisplayNameOptions, UnsafeFormatListOptions, UnsafeFormatNumberOptions, UnsafeFormatPercentOptions, UnsafeFormatRelativeTimeOptions, inferCompiledTranslationMap, inferCompiledTranslationNamespace, inferCompiledTranslationShape, mergeTranslationMaps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/translate",
-  "version": "20.5.10",
+  "version": "20.5.12",
   "keywords": [
     "angular",
     "localize",