@vireocodedev/localization

export type CreateHistoryResourcesConfig<L extends string> = {
    /** The full set of locales the consumer app wants to support. */
    locales: readonly L[];
    /** Base locale used to seed locales the namespace does not ship. Defaults to `"en"`. */
    seedFrom?: HistoryBaseLocale;
    /** Optional per-locale value overrides, deep-merged over the seeded base. */
    overrides?: Partial<Record<L, HistoryResourcesOverride>>;
};

export type CreatePlatformResourcesConfig<L extends string> = {
    /** The full set of locales the consumer app wants to support. */
    locales: readonly L[];
    /** Base locale used to seed locales the platform does not ship. Defaults to `"en"`. */
    seedFrom?: PlatformBaseLocale;
    /** Optional per-locale value overrides, deep-merged over the seeded base. */
    overrides?: Partial<Record<L, PlatformResourcesOverride>>;
};

export type CreateQueryEngineResourcesConfig<L extends string> = {
    /** The full set of locales the consumer app wants to support. */
    locales: readonly L[];
    /** Base locale used to seed locales the namespace does not ship. Defaults to `"en"`. */
    seedFrom?: QueryEngineBaseLocale;
    /** Optional per-locale value overrides, deep-merged over the seeded base. */
    overrides?: Partial<Record<L, QueryEngineResourcesOverride>>;
};

export type CreateStarterResourcesConfig<L extends string> = {
    /** The full set of locales the consumer app wants to support. */
    locales: readonly L[];
    /** Base locale used to seed locales the starter does not ship. Defaults to `"en"`. */
    seedFrom?: StarterBaseLocale;
    /** Optional per-locale, per-namespace value overrides, deep-merged over the seeded base. */
    overrides?: Partial<Record<L, StarterResourcesOverride>>;
};

A recursively partial version of `T`. Consumers use it to supply per-locale value overrides without having to restate the full resource shape.

/**
 * A recursively partial version of `T`. Consumers use it to supply per-locale
 * value overrides without having to restate the full resource shape.
 */
export type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? {
    [K in keyof T]?: DeepPartial<T[K]>;
} : T;

Locales the History namespace ships out of the box.

/** Locales the History namespace ships out of the box. */
export declare const HISTORY_BASE_LOCALES: readonly [
    "en",
    "hr"
];

export declare const HISTORY_TRANSLATION_NAMESPACE: "history";

export type HistoryBaseLocale = (typeof HISTORY_BASE_LOCALES)[number];

The canonical History resource shape. English is the key source of truth.

/** The canonical History resource shape. English is the key source of truth. */
export type HistoryResources = WidenLeaves<typeof HISTORY_EN>;

A recursively partial resource, used for per-locale value overrides. Leaves are widened, so an override may supply any string for a shipped key.

/**
 * A recursively partial resource, used for per-locale value overrides. Leaves
 * are widened, so an override may supply any string for a shipped key.
 */
export type HistoryResourcesOverride = DeepPartial<HistoryResources>;

export type HistoryTranslationNamespace = typeof HISTORY_TRANSLATION_NAMESPACE;

export type IntlNumberFormatRequest = {
    locale: string;
    options?: Intl.NumberFormatOptions;
    fallback?: (value: number) => string;
};

Locales the platform ships out of the box.

/** Locales the platform ships out of the box. */
export declare const PLATFORM_BASE_LOCALES: readonly [
    "en",
    "hr"
];

export declare const PLATFORM_TRANSLATION_NAMESPACE: "platform";

export type PlatformBaseLocale = (typeof PLATFORM_BASE_LOCALES)[number];

The canonical platform resource shape. English is the key source of truth.

/** The canonical platform resource shape. English is the key source of truth. */
export type PlatformResources = WidenLeaves<typeof PLATFORM_EN>;

A recursively partial platform resource, used for per-locale value overrides. Leaves are widened, so an override may supply any string for a shipped key.

/**
 * A recursively partial platform resource, used for per-locale value overrides.
 * Leaves are widened, so an override may supply any string for a shipped key.
 */
export type PlatformResourcesOverride = DeepPartial<PlatformResources>;

export type PlatformTranslationNamespace = typeof PLATFORM_TRANSLATION_NAMESPACE;

Locales the QueryEngine namespace ships out of the box.

/** Locales the QueryEngine namespace ships out of the box. */
export declare const QUERYENGINE_BASE_LOCALES: readonly [
    "en",
    "hr"
];

export declare const QUERYENGINE_TRANSLATION_NAMESPACE: "queryengine";

export type QueryEngineBaseLocale = (typeof QUERYENGINE_BASE_LOCALES)[number];

The canonical Query Engine resource shape. English is the key source of truth.

/** The canonical Query Engine resource shape. English is the key source of truth. */
export type QueryEngineResources = WidenLeaves<typeof QUERYENGINE_EN>;

A recursively partial resource, used for per-locale value overrides. Leaves are widened, so an override may supply any string for a shipped key.

/**
 * A recursively partial resource, used for per-locale value overrides. Leaves
 * are widened, so an override may supply any string for a shipped key.
 */
export type QueryEngineResourcesOverride = DeepPartial<QueryEngineResources>;

export type QueryEngineTranslationNamespace = typeof QUERYENGINE_TRANSLATION_NAMESPACE;

Locales every starter namespace ships out of the box.

/** Locales every starter namespace ships out of the box. */
export declare const STARTER_BASE_LOCALES: readonly [
    "en",
    "hr"
];

Every i18next namespace shipped by the starter libraries.

/** Every i18next namespace shipped by the starter libraries. */
export declare const STARTER_TRANSLATION_NAMESPACES: readonly [
    "platform",
    "queryengine",
    "history"
];

export type StarterBaseLocale = (typeof STARTER_BASE_LOCALES)[number];

The resources contributed by the starter libraries, keyed by namespace.

/** The resources contributed by the starter libraries, keyed by namespace. */
export type StarterNamespaceResources = {
    [PLATFORM_TRANSLATION_NAMESPACE]: PlatformResources;
    [QUERYENGINE_TRANSLATION_NAMESPACE]: QueryEngineResources;
    [HISTORY_TRANSLATION_NAMESPACE]: HistoryResources;
};

Per-locale, per-namespace value overrides.

/** Per-locale, per-namespace value overrides. */
export type StarterResourcesOverride = {
    [PLATFORM_TRANSLATION_NAMESPACE]?: PlatformResourcesOverride;
    [QUERYENGINE_TRANSLATION_NAMESPACE]?: QueryEngineResourcesOverride;
    [HISTORY_TRANSLATION_NAMESPACE]?: HistoryResourcesOverride;
};

export type StarterTranslationNamespace = (typeof STARTER_TRANSLATION_NAMESPACES)[number];

Widens leaf string/number/boolean literals to their base primitive while preserving object structure. Used to type base resource maps whose non-seed locales share the shape but not the literal values of the canonical locale.

/**
 * Widens leaf string/number/boolean literals to their base primitive while
 * preserving object structure. Used to type base resource maps whose non-seed
 * locales share the shape but not the literal values of the canonical locale.
 */
export type WidenLeaves<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends (infer U)[] ? WidenLeaves<U>[] : T extends object ? {
    [K in keyof T]: WidenLeaves<T[K]>;
} : T;

Builds a fully-populated History resource map for every requested locale.

/**
 * Builds a fully-populated History resource map for every requested locale.
 */
export declare function createHistoryResources<L extends string>(config: CreateHistoryResourcesConfig<L>): Record<L, {
    [HISTORY_TRANSLATION_NAMESPACE]: HistoryResources;
}>;

Builds a fully-populated i18next resource map for every requested locale. For each locale the merge chain is: 1. Start from the `seedFrom` base resource (guarantees every key exists). 2. If the locale is a shipped base locale, layer its shipped resource. 3. Layer the consumer's partial override, if any. The result is `Record<Locale, { [namespace]: TShape }>`, so no key is ever missing for any requested locale — including brand-new languages the library does not ship, which fall back to the seed until translated.

/**
 * Builds a fully-populated i18next resource map for every requested locale.
 *
 * For each locale the merge chain is:
 *   1. Start from the `seedFrom` base resource (guarantees every key exists).
 *   2. If the locale is a shipped base locale, layer its shipped resource.
 *   3. Layer the consumer's partial override, if any.
 *
 * The result is `Record<Locale, { [namespace]: TShape }>`, so no key is ever
 * missing for any requested locale — including brand-new languages the library
 * does not ship, which fall back to the seed until translated.
 */
export declare function createNamespaceResources<TShape extends object, B extends string, L extends string, N extends string>(config: CreateNamespaceResourcesConfig<TShape, B, L> & {
    namespace: N;
}): Record<L, Record<N, TShape>>;

Builds a fully-populated platform resource map for every requested locale. Consumers can override any shipped value per locale and add brand-new languages (seeded from a base locale until translated) without ever ending up with a missing platform key.

/**
 * Builds a fully-populated platform resource map for every requested locale.
 *
 * Consumers can override any shipped value per locale and add brand-new
 * languages (seeded from a base locale until translated) without ever ending
 * up with a missing platform key.
 */
export declare function createPlatformResources<L extends string>(config: CreatePlatformResourcesConfig<L>): Record<L, {
    [PLATFORM_TRANSLATION_NAMESPACE]: PlatformResources;
}>;

Builds a fully-populated QueryEngine resource map for every requested locale.

/**
 * Builds a fully-populated QueryEngine resource map for every requested locale.
 */
export declare function createQueryEngineResources<L extends string>(config: CreateQueryEngineResourcesConfig<L>): Record<L, {
    [QUERYENGINE_TRANSLATION_NAMESPACE]: QueryEngineResources;
}>;

Builds every starter-owned namespace for the requested locales in a single call, so apps spread one object per locale into their i18next resources and pick up new starter namespaces without touching their wiring.

/**
 * Builds every starter-owned namespace for the requested locales in a single
 * call, so apps spread one object per locale into their i18next resources and
 * pick up new starter namespaces without touching their wiring.
 */
export declare function createStarterResources<L extends string>(config: CreateStarterResourcesConfig<L>): Record<L, StarterNamespaceResources>;

Recursively merges `override` onto `base`, returning a new value. - Plain objects are merged key-by-key. - Any non-plain-object value (string, number, array, etc.) in `override` replaces the corresponding value in `base`. - `undefined` values in `override` are ignored, so partial overrides never erase base keys. - Inputs and nested values are cloned, so callers cannot mutate source resources through the returned object. - Prototype-mutating keys are ignored. The result always retains the full shape of `base`, which is what guarantees that a partial locale override can never introduce a missing translation key.

/**
 * Recursively merges `override` onto `base`, returning a new value.
 *
 * - Plain objects are merged key-by-key.
 * - Any non-plain-object value (string, number, array, etc.) in `override`
 *   replaces the corresponding value in `base`.
 * - `undefined` values in `override` are ignored, so partial overrides never
 *   erase base keys.
 * - Inputs and nested values are cloned, so callers cannot mutate source
 *   resources through the returned object.
 * - Prototype-mutating keys are ignored.
 *
 * The result always retains the full shape of `base`, which is what guarantees
 * that a partial locale override can never introduce a missing translation key.
 */
export declare function deepMerge<T>(base: T, override: unknown): T;

Locale-neutral formatting primitive; application locale/default policy stays at the call site.

/** Locale-neutral formatting primitive; application locale/default policy stays at the call site. */
export declare function formatIntlNumber(value: number, request: IntlNumberFormatRequest): string;

export declare const historyBaseResources: Record<HistoryBaseLocale, HistoryResources>;

export declare const platformBaseResources: Record<PlatformBaseLocale, PlatformResources>;

export declare const queryEngineBaseResources: Record<QueryEngineBaseLocale, QueryEngineResources>;

Imperatively registers every starter namespace onto an existing i18next instance. Useful when resources are added after i18next has been initialized.

/**
 * Imperatively registers every starter namespace onto an existing i18next
 * instance. Useful when resources are added after i18next has been initialized.
 */
export declare function registerStarterResources<L extends string>(i18n: I18nInstance, config: CreateStarterResourcesConfig<L>): void;