waybetter 0.1.0 → 0.6.0

package/dist/runtime/i18n.d.ts

@@ -0,0 +1,138 @@
+export type Messages = Readonly<Record<string, string>>;
+export type Dir = 'ltr' | 'rtl';
+export type Params = Readonly<Record<string, unknown>>;
+/** A catalog file (`locales/<bcp47>.json`). See `i18n.schema.json` in the `waybetter` package. */
+export type Catalog = {
+    $schema?: string;
+    /** BCP 47 tag of this file (`tr`, `pt`, `zh-Hant`, `ar-x-fm`). */
+    locale: string;
+    /** The language's own name ("Türkçe"). */
+    name: string;
+    /** Its English name ("Turkish"). */
+    englishName: string;
+    dir?: Dir;
+    /** `source` (English), `machine` (machine-drafted, needs a human), `reviewed` (checked by people). */
+    status: 'source' | 'machine' | 'reviewed';
+    reviewers?: string[];
+    /** Falls back to this locale before English (e.g. `ar-x-fm` -> `ar`). */
+    fallback?: string;
+    messages: Record<string, string>;
+};
+/**
+ * A tag in canonical BCP 47 form (`en_gb` -> `en-GB`, `zh-cn` -> `zh-Hans`, `msa` -> `ms`), or null
+ * when it is not a language tag at all. Private-use subtags survive (`ar-x-fm`).
+ */
+export declare function normalizeLocale(input: unknown): string | null;
+/** The primary language subtag (`pt-BR` -> `pt`). */
+export declare function languageOf(locale: string): string;
+/** Writing direction of a locale. */
+export declare function direction(locale: string): Dir;
+/**
+ * Where lookups go, most specific first, ending with the source locale: `pt-BR` -> [pt-BR, pt, en].
+ * `fallbacks` maps a locale to the one it inherits from (a catalog's `fallback`, e.g. ar-x-fm -> ar).
+ * Script variants never fall back to another script: `zh-Hant` does not use `zh-Hans`.
+ */
+export declare function fallbackChain(locale: string, source?: string, fallbacks?: Readonly<Record<string, string>>): string[];
+/**
+ * Picks the best available locale for a list of preferences (most wanted first), by fallback chain:
+ * `['pt-PT', 'en']` with `pt` available -> `pt`. Returns `fallback` when nothing matches.
+ */
+export declare function matchLocale(preferred: readonly unknown[], available: readonly string[], fallback?: string): string;
+type Part = string | {
+    kind: 'arg';
+    name: string;
+    format?: 'number' | 'date' | 'time';
+    style?: string;
+} | {
+    kind: 'pound';
+} | {
+    kind: 'plural';
+    name: string;
+    ordinal: boolean;
+    offset: number;
+    options: Record<string, Part[]>;
+} | {
+    kind: 'select';
+    name: string;
+    options: Record<string, Part[]>;
+};
+export declare class MessageSyntaxError extends Error {
+    readonly source: string;
+    readonly index: number;
+    constructor(message: string, source: string, index: number);
+}
+/** Parses a message into parts; throws `MessageSyntaxError` on malformed ICU. */
+export declare function parseMessage(source: string): Part[];
+/** Placeholder names a message uses (plural/select arguments included), sorted. */
+export declare function placeholders(source: string): string[];
+/** Plural/select structure of a message: `{ count: { kind: 'plural', options: ['one', 'other'] } }`. */
+export declare function argumentShapes(source: string): Record<string, {
+    kind: 'plural' | 'selectordinal' | 'select';
+    options: string[];
+}>;
+export declare function numberFormat(locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat;
+export declare function dateFormat(locale: string, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+export declare function pluralRules(locale: string, ordinal?: boolean): Intl.PluralRules;
+/** CLDR plural categories a locale uses (`tr`: one, other; `ar`: zero, one, two, few, many, other). */
+export declare function pluralCategories(locale: string, ordinal?: boolean): string[];
+/**
+ * Formats one message. Placeholder values are inserted as plain text; a malformed message renders
+ * as its raw text (and `onError` hears about it) rather than throwing in the UI.
+ */
+export declare function formatMessage(source: string, params?: Params, locale?: string, hooks?: {
+    onError?: (error: Error) => void;
+    onMissingParam?: (name: string) => void;
+}): string;
+export type I18nOptions = {
+    /** The source locale; its messages are complete (default `en`). */
+    sourceLocale?: string;
+    /** Source messages (English). Always loaded. */
+    source: Messages;
+    /** Locales that have catalogs (the source included). */
+    available: readonly string[];
+    /** Per-locale inheritance before the source (a catalog's `fallback`). */
+    fallbacks?: Readonly<Record<string, string>>;
+    /** Loads one locale's messages (lazy import of `locales/<tag>.json`), or null when there are none. */
+    load?: (locale: string) => Promise<Messages | null | undefined> | Messages | null | undefined;
+    /** Initial locale (default: the source). */
+    locale?: string;
+    /** A key the chain does not have, or a message that failed to parse. Once per key and locale. */
+    onMissing?: (key: string, locale: string, reason: 'key' | 'syntax' | 'param') => void;
+};
+export type I18n<K extends string = string> = {
+    /** Active locale (a catalog tag, e.g. `pt`, `zh-Hant`). */
+    readonly locale: string;
+    readonly dir: Dir;
+    /** Lookup order for the active locale, ending with the source. */
+    readonly chain: readonly string[];
+    readonly available: readonly string[];
+    /** The message for `key` in the active locale, formatted with `params`. Unknown keys return the key. */
+    t(key: K, params?: Params): string;
+    /** Like `t` for keys built at runtime; returns `fallback` (default the key) when missing. */
+    tx(key: string, params?: Params, fallback?: string): string;
+    has(key: string): boolean;
+    /** Switches locale (loading its catalog and its chain's). Resolves with the effective locale. */
+    setLocale(locale: string): Promise<string>;
+    /** Adds messages for a locale (framework catalogs, plugin strings); later adds win. */
+    add(locale: string, messages: Messages): void;
+    onChange(listener: (locale: string) => void): () => void;
+    /** Resolved messages of the active locale for keys starting with one of `prefixes` (the chain merged). */
+    resolved(prefixes?: readonly string[]): Record<string, string>;
+    number(value: number, options?: Intl.NumberFormatOptions): string;
+    date(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+    /** "3 minutes ago", "in 2 days" (Intl.RelativeTimeFormat, numeric: auto). */
+    relative(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+    /** "a, b and c" (Intl.ListFormat). */
+    list(items: readonly string[], options?: {
+        type?: 'conjunction' | 'disjunction' | 'unit';
+        style?: 'long' | 'short' | 'narrow';
+    }): string;
+    plural(count: number, ordinal?: boolean): Intl.LDMLPluralRule;
+};
+export declare function createI18n<K extends string = string>(options: I18nOptions): I18n<K>;
+/** Picks a relative-time unit for a timestamp: "just now" granularity down to seconds. */
+export declare function relativeParts(then: number, now?: number): {
+    value: number;
+    unit: Intl.RelativeTimeFormatUnit;
+};
+export {};