@sveltia/i18n 0.1.1

package/dist/index.svelte.d.ts

@@ -0,0 +1,202 @@
+export type Formats = {
+    /**
+     * Custom number format presets.
+     */
+    number?: Record<string, Intl.NumberFormatOptions> | undefined;
+    /**
+     * Custom date format presets.
+     */
+    date?: Record<string, Intl.DateTimeFormatOptions> | undefined;
+    /**
+     * Custom time format presets.
+     */
+    time?: Record<string, Intl.DateTimeFormatOptions> | undefined;
+};
+export type MissingKeyHandler = (key: string, locale: string, defaultValue: string | undefined) => string | void;
+export type MessageObject = {
+    /**
+     * Message key.
+     */
+    id: string;
+    /**
+     * Variables to interpolate into the message.
+     */
+    values?: Record<string, any> | undefined;
+    /**
+     * Locale override for this call.
+     */
+    locale?: string | undefined;
+    /**
+     * Fallback string if the key is not found.
+     */
+    default?: string | undefined;
+};
+/**
+ * Date/time formatting options, extending `Intl.DateTimeFormatOptions` with `locale` and `format`
+ * overrides.
+ */
+export type DateFormatOptions = Intl.DateTimeFormatOptions & {
+    locale?: string;
+    format?: string;
+};
+/**
+ * Number formatting options, extending `Intl.NumberFormatOptions` with `locale` and `format`
+ * overrides.
+ */
+export type NumberFormatOptions = Intl.NumberFormatOptions & {
+    locale?: string;
+    format?: string;
+};
+/**
+ * Format a message by key.
+ *
+ * Supports two call signatures (matching svelte-i18n):
+ * - `format(id, options?)` — key as first argument
+ * - `format({ id, values, locale, default })` — options object only.
+ * @param {string | MessageObject} key Message key, or an object with `id` and options.
+ * @param {{ values?: Record<string, any>, locale?: string, default?: string }} [options] Formatting
+ * options when `key` is a string.
+ * @returns {string} The formatted message string.
+ */
+export function format(key: string | MessageObject, { values, locale: localeOverride, default: defaultString }?: {
+    values?: Record<string, any>;
+    locale?: string;
+    default?: string;
+}): string;
+/**
+ * Add new messages for a locale. Accepts flat or nested maps; nested objects are flattened to
+ * dot-separated keys (`field.name`). Multiple dicts can be passed and are merged in order, matching
+ * svelte-i18n's `addMessages(locale, ...dicts)` signature.
+ * @param {string} localeCode Locale.
+ * @param {...Record<string, any>} maps One or more message maps (flat or nested).
+ * @see https://messageformat.github.io/messageformat/api/messageformat.messageformat/
+ */
+export function addMessages(localeCode: string, ...maps: Record<string, any>[]): void;
+/**
+ * Format a date value as a localized date string.
+ * @param {Date} value The date to format.
+ * @param {DateFormatOptions} [options] Formatting options.
+ * @returns {string} The formatted date string.
+ */
+export function date(value: Date, { locale: loc, format: fmt, ...rest }?: DateFormatOptions): string;
+/**
+ * All registered resources.
+ * @type {Record<string, Record<string, Intl.MessageFormat>>}
+ */
+export const dictionary: Record<string, Record<string, Intl.MessageFormat>>;
+/**
+ * Get the locale from a `key=value` pair in `window.location.hash`.
+ * @param {string} hashKey The key to look for in the hash.
+ * @returns {string | undefined} The hash parameter value, or `undefined` if not in a browser or not
+ * found.
+ */
+export function getLocaleFromHash(hashKey: string): string | undefined;
+/**
+ * Get the locale from a pattern matched against `window.location.hostname`.
+ * @param {RegExp} hostnamePattern Pattern with a capture group for the locale code.
+ * @returns {string | undefined} The matched locale code, or `undefined` if not in a browser or no
+ * match.
+ */
+export function getLocaleFromHostname(hostnamePattern: RegExp): string | undefined;
+/**
+ * Get the user's preferred locale from the browser.
+ * @returns {string | undefined} The first navigator language, or `undefined` in non-browser
+ * environments.
+ */
+export function getLocaleFromNavigator(): string | undefined;
+/**
+ * Get the locale from a pattern matched against `window.location.pathname`.
+ * @param {RegExp} pathnamePattern Pattern with a capture group for the locale code.
+ * @returns {string | undefined} The matched locale code, or `undefined` if not in a browser or no
+ * match.
+ */
+export function getLocaleFromPathname(pathnamePattern: RegExp): string | undefined;
+/**
+ * Get the locale from a URL query string parameter.
+ * @param {string} queryKey The query string key to read.
+ * @returns {string | undefined} The query parameter value, or `undefined` if not in a browser or
+ * not found.
+ */
+export function getLocaleFromQueryString(queryKey: string): string | undefined;
+/**
+ * Initialize the locales.
+ * @param {object} args Arguments.
+ * @param {string} args.fallbackLocale Locale to be used for fallback.
+ * @param {string} [args.initialLocale] Locale to be used for the initial selection.
+ * @param {Formats} [args.formats] Custom named formats.
+ * @param {MissingKeyHandler} [args.handleMissingMessage] Called when a message key is not found.
+ * May return a string to use as a fallback.
+ */
+export function init(args: {
+    fallbackLocale: string;
+    initialLocale?: string | undefined;
+    formats?: Formats | undefined;
+    handleMissingMessage?: MissingKeyHandler | undefined;
+}): void;
+/**
+ * Whether locale messages are currently being loaded. Returns `true` after a locale is set but
+ * before its messages are available.
+ * @returns {boolean} `true` if messages are pending for the current locale, `false` otherwise.
+ */
+export function isLoading(): boolean;
+/**
+ * Whether the current locale is written right-to-left. Reactive: re-evaluates whenever the locale
+ * changes.
+ * @returns {boolean} `true` if the active locale is RTL, `false` otherwise.
+ */
+export function isRTL(): boolean;
+/**
+ * Return a nested object of formatted strings for all keys under the given prefix. Equivalent to
+ * svelte-i18n's `$json()`. Useful for iterating over a group of messages.
+ * @param {string} prefix Key prefix (e.g. `'nav'` matches `nav.home`, `nav.about`, …).
+ * @param {{ locale?: string }} [options] Lookup options.
+ * @returns {Record<string, string> | undefined} Object mapping suffix keys to formatted strings, or
+ * `undefined` if no keys match the prefix.
+ */
+export function json(prefix: string, { locale: localeOverride }?: {
+    locale?: string;
+}): Record<string, string> | undefined;
+export namespace locale {
+    const current: string;
+    /**
+     * Set the current locale. Negotiates against registered locales (e.g. En-CA → en-US), updates
+     * `<html lang>` / `<html dir>`, and auto-triggers any registered loader.
+     * @param {string} value The locale to set.
+     * @returns {Promise<void>}
+     */
+    function set(value: string): Promise<void>;
+}
+/**
+ * All registered locales.
+ * @type {string[]}
+ */
+export const locales: string[];
+/**
+ * Format a number as a localized string.
+ * @param {number} value The number to format.
+ * @param {NumberFormatOptions} [options] Formatting options.
+ * @returns {string} The formatted number string.
+ */
+export function number(value: number, { locale: loc, format: fmt, ...rest }?: NumberFormatOptions): string;
+/**
+ * Register an async loader for a locale. The loader is called the first time
+ * `waitLocale(localeCode)` is invoked for that locale.
+ * @param {string} localeCode Locale.
+ * @param {() => Promise<Record<string, string>>} loader Function returning a message map.
+ */
+export function register(localeCode: string, loader: () => Promise<Record<string, string>>): void;
+/**
+ * Format a date value as a localized time string.
+ * @param {Date} value The date to format.
+ * @param {DateFormatOptions} [options] Formatting options.
+ * @returns {string} The formatted time string.
+ */
+export function time(value: Date, { locale: loc, format: fmt, ...rest }?: DateFormatOptions): string;
+/**
+ * Execute the registered loader for the given locale (or the current locale if omitted) and wait
+ * until the messages are loaded. Subsequent calls for the same locale return the same promise.
+ * @param {string} [localeCode] Defaults to `locale.current`.
+ * @returns {Promise<void>}
+ */
+export function waitLocale(localeCode?: string): Promise<void>;
+export { format as _, format as t };