@ng-linguo/linguo 0.9.0

package/types/ng-linguo-linguo.d.ts

@@ -0,0 +1,454 @@
+import * as _ngrx_signals from '@ngrx/signals';
+import * as _angular_core from '@angular/core';
+import { EnvironmentProviders, PipeTransform, OnInit, TemplateRef, InjectionToken } from '@angular/core';
+
+/**
+ * A flat map of translation keys to their resolved string values for a single
+ * language. Values are plain strings (optionally containing `[name]...[/name]`
+ * slot tags and ICU syntax) — never HTML. This is the on-disk JSON shape, kept
+ * stable since v1 so translators can keep using existing tooling.
+ */
+type Translations = Readonly<Record<string, string>>;
+/**
+ * Strategy for fetching the {@link Translations} for a given language.
+ *
+ * Implementations live in their own packages (for example
+ * `@ng-linguo/linguo/http`); `@ng-linguo/linguo` only depends on this interface
+ * so it never reaches for `fetch`/XHR itself.
+ */
+interface TranslationLoader {
+    /**
+     * Resolve the translations for `lang`. Rejecting the promise signals a load
+     * failure to the store; resolving with an empty map is a valid "no
+     * translations" result.
+     *
+     * @param lang BCP-47 language tag, for example `'en'` or `'pl'`.
+     */
+    load(lang: string): Promise<Translations>;
+}
+/**
+ * Bootstrap configuration for the translation runtime, passed to
+ * `provideTranslate`. Loading is never started implicitly from this config —
+ * the consumer triggers the first load explicitly.
+ */
+interface TranslateConfig {
+    /** Language the store reports as current before anything is loaded. */
+    readonly defaultLang: string;
+    /**
+     * How translations are fetched. Either a ready-made {@link TranslationLoader}
+     * (e.g. a static dictionary or a `fetch`-based loader), or a **factory** that
+     * returns one. The factory runs inside Angular's injection context, so use it
+     * for loaders that inject Angular services — such as `createHttpLoader()` from
+     * `@ng-linguo/linguo/http`, which needs `HttpClient`:
+     *
+     * ```ts
+     * provideTranslate({ defaultLang: 'en', loader: () => createHttpLoader() });
+     * ```
+     */
+    readonly loader: TranslationLoader | (() => TranslationLoader);
+    /**
+     * Languages the app ships. Used by {@link TranslateStore.restoreLang} to match
+     * a persisted or browser-preferred value to one that actually exists. Browser
+     * matching is skipped when this is omitted (so an unshipped language is never
+     * auto-selected).
+     */
+    readonly supportedLangs?: readonly string[];
+    /**
+     * Write the active language to `localStorage` whenever it changes (the
+     * **persist** side). Defaults to `true`. SSR-safe (a no-op when not running
+     * in a browser). To stop reading the saved value on startup as well, see
+     * {@link restoreSelectedLanguage}.
+     */
+    readonly persistSelectedLanguage?: boolean;
+    /**
+     * Read the persisted language back on startup, inside
+     * {@link TranslateStore.restoreLang} (the **restore** side). Decoupled from
+     * {@link persistSelectedLanguage} so an app can keep persisting while owning
+     * the restore decision itself — set this to `false` and run your own
+     * selection logic, or just call `setLang(...)` instead of `restoreLang()`.
+     *
+     * Defaults to `persistSelectedLanguage` (so disabling persistence alone still
+     * disables restore, as before); set it explicitly to override. SSR-safe.
+     */
+    readonly restoreSelectedLanguage?: boolean;
+    /** `localStorage` key for the persisted language. Defaults to `ng-linguo.lang`. */
+    readonly persistKey?: string;
+    /**
+     * On first run (nothing persisted), use the browser's preferred language
+     * (`navigator.languages`) matched against {@link supportedLangs}. Defaults to
+     * `true`. SSR-safe.
+     */
+    readonly detectBrowserLanguage?: boolean;
+}
+/**
+ * Options for the `t` pipe, passed as a single object:
+ * `{{ 'Hello {$name}!' | t: { params: { name } } }}`.
+ */
+interface TranslateOptions {
+    /** ICU arguments, formatted via `@ng-linguo/linguo/icu` when provided. */
+    readonly params?: Record<string, unknown>;
+    /**
+     * Disambiguating/contextual text for keys that share the same source text.
+     * It is part of the key (gettext `msgctxt`), so distinct contexts get
+     * distinct translations; it may be descriptive ("Button that starts a game").
+     */
+    readonly context?: string;
+}
+
+/**
+ * The reactive translation runtime, implemented as an `@ngrx/signals`
+ * `signalStore`. Consumers inject it and read state through signals; there are
+ * no `Observable` getters on the public surface.
+ *
+ * State is not loaded implicitly. Call {@link TranslateStore.restoreLang} once
+ * at startup to pick the language (persisted → browser → default) and load it,
+ * or {@link TranslateStore.setLang} to switch to a specific one.
+ * {@link TranslateStore.isReady} stays `false` until a language has loaded, so
+ * UI can gate on it to avoid a flash of untranslated content.
+ *
+ * @example
+ * ```ts
+ * const store = inject(TranslateStore);
+ * store.currentLang(); // Signal<string>
+ * store.isReady();     // Signal<boolean>
+ * await store.restoreLang(); // startup: persisted ?? browser ?? default
+ * await store.setLang('pl'); // explicit switch
+ * store.translate('greeting');
+ * ```
+ */
+declare const TranslateStore: _angular_core.Type<{
+    readonly currentLang: _angular_core.Signal<string>;
+    readonly isReady: _angular_core.Signal<boolean>;
+    readonly translations: _angular_core.Signal<Readonly<Record<string, string>>>;
+    setLang: (lang: string) => Promise<void>;
+    restoreLang: () => Promise<void>;
+    translate: (key: string, context?: string) => string;
+} & _ngrx_signals.StateSource<{
+    readonly currentLang: string;
+    readonly isReady: boolean;
+    readonly translations: Translations;
+}>>;
+
+/**
+ * Register the translation runtime for an application or a feature scope.
+ *
+ * Add the returned providers to `bootstrapApplication`'s `providers` (or a
+ * route's `providers`). This only wires up configuration — it never starts a
+ * load, so no HTTP is fired during DI initialization. Trigger the first load
+ * explicitly via `TranslateStore.setLang`.
+ *
+ * The `loader` may be a ready-made loader object, or a factory `() => loader`
+ * that is run inside the injection context — use the factory form for loaders
+ * that inject Angular services (e.g. `createHttpLoader()`, which needs
+ * `HttpClient`).
+ *
+ * @example
+ * ```ts
+ * // a static dictionary or fetch-based loader
+ * provideTranslate({ defaultLang: 'en', loader: myLoader });
+ *
+ * // an HttpClient-backed loader (factory form)
+ * provideTranslate({ defaultLang: 'en', loader: () => createHttpLoader() });
+ * ```
+ */
+declare function provideTranslate(config: TranslateConfig): EnvironmentProviders;
+
+/**
+ * Resolve a translation key to its string for the current language, with options
+ * passed as a single object: ICU `params` and a disambiguating `context`.
+ *
+ * @example
+ * ```html
+ * {{ 'Play' | t }}
+ * {{ 'Play' | t: { context: 'game' } }}
+ * {{ 'Hello {$name}!' | t: { params: { name } } }}
+ * ```
+ *
+ * The key is the source text; a missing key renders as itself. ICU `params` are
+ * applied by the formatter from `@ng-linguo/linguo/icu` (`provideIcu`); without
+ * it the message is returned unformatted.
+ *
+ * Impure so it re-evaluates against the store's signals each change detection,
+ * re-rendering when the language changes. To keep that cheap it **memoizes** by
+ * value: the lookup/format only re-runs when the key, `context`, `params`
+ * contents, or the active language actually change — so a fresh `{ params: … }`
+ * literal on every change-detection pass costs only an equality check. For hot
+ * or looped bindings, prefer `injectTranslate()` inside a `computed()`, which
+ * does zero work per change-detection pass.
+ */
+declare class TranslatePipe implements PipeTransform {
+    private readonly t;
+    private readonly translations;
+    private cache;
+    transform(key: string, options?: TranslateOptions): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslatePipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<TranslatePipe, "t", true>;
+}
+
+/**
+ * Resolves a key to its translation for the current language, with optional ICU
+ * `params` and `context` — the function form of the `t` pipe.
+ */
+type TranslateFn = (key: string, options?: TranslateOptions) => string;
+/**
+ * Obtain a {@link TranslateFn} for use in component code — the TypeScript
+ * counterpart of the `t` pipe.
+ *
+ * Call it in an injection context (a field initializer or constructor); the
+ * returned `t` reads the store's signals each time it runs, so it stays reactive
+ * when used in a template binding or inside a `computed`.
+ *
+ * @example
+ * ```ts
+ * export class Greeting {
+ *   private readonly t = injectTranslate();
+ *   protected readonly name = signal('Ada');
+ *   protected readonly text = computed(() =>
+ *     this.t('Hello {$name}!', { params: { name: this.name() } }),
+ *   );
+ * }
+ * ```
+ */
+declare function injectTranslate(): TranslateFn;
+
+/**
+ * Options for {@link mark}. Only `context` is read (by `@ng-linguo/extract`);
+ * `params` is accepted so a single options object can be shared with the `t`
+ * pipe / directive call that ultimately renders the message.
+ */
+interface MarkOptions {
+    /**
+     * Disambiguating/contextual text recorded as the catalog `msgctxt`. It is part
+     * of the key, so it must match the `context` passed at the consuming
+     * pipe/directive for the runtime lookup to resolve. It doubles as a note for
+     * translators (e.g. `'file = a document on disk'`).
+     */
+    readonly context?: string;
+}
+/**
+ * Mark a string as a translatable message so `@ng-linguo/extract` collects it,
+ * returning the string unchanged (it does not translate at runtime).
+ *
+ * Use it for messages that are not written inline at a `t` pipe or `[t]`
+ * directive — for example an ICU message kept in a component field (an MF2
+ * pattern contains `{{ … }}`, which collides with Angular's `{{ }}` binding).
+ * The marked string is still translated at render time by the pipe/directive
+ * that consumes it.
+ *
+ * Pass `context` to record a `msgctxt`/translator note for the entry. Because
+ * context is part of the key, the **same** `context` must be supplied where the
+ * marked string is rendered (`| t: { context }` or `tContext`), or the runtime
+ * lookup will not find the contextual entry.
+ *
+ * @example
+ * ```ts
+ * readonly fileCount = mark(
+ *   '.input {$count :number} .match $count one {{{$count} file}} * {{{$count} files}}',
+ *   { context: 'file = a document on disk' },
+ * );
+ * // template: {{ fileCount | t: { params: { count: count() }, context: 'file = a document on disk' } }}
+ * ```
+ */
+declare function mark(message: string, options?: MarkOptions): string;
+
+/**
+ * A node in a parsed slot tree produced by {@link parseSlots}.
+ *
+ * - `text` nodes carry literal, translator-authored text. They are rendered as
+ *   DOM text nodes — never as HTML — which is how the library keeps its XSS
+ *   surface at zero by construction.
+ * - `slot` nodes correspond to a `[name]...[/name]` region that the developer
+ *   fills with an `<ng-template>`. The bracket syntax resembles BBCode, but the
+ *   names are arbitrary and author-chosen and carry no predefined rendering —
+ *   each is a named slot bound to a template. Slots may nest.
+ */
+type SlotNode = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'slot';
+    readonly name: string;
+    readonly children: readonly SlotNode[];
+};
+/**
+ * Parse a translator-authored string into a tree of {@link SlotNode}s.
+ *
+ * The parser is total: every input produces a tree, and any malformed
+ * construct (a stray `[`, an unclosed tag, a mismatched closing tag) degrades
+ * gracefully to literal text rather than throwing. Well-formed
+ * `[name]...[/name]` regions — including nested ones — become `slot` nodes. To
+ * include a literal `[` (so text such as `[note]` is not read as a tag), double
+ * it: `[[` parses to a single `[`.
+ *
+ * @example
+ * ```ts
+ * parseSlots('Hello [b]world[/b]!');
+ * // [
+ * //   { kind: 'text', value: 'Hello ' },
+ * //   { kind: 'slot', name: 'b', children: [{ kind: 'text', value: 'world' }] },
+ * //   { kind: 'text', value: '!' },
+ * // ]
+ *
+ * parseSlots('See [[b] for bold');
+ * // [{ kind: 'text', value: 'See [b] for bold' }]
+ * ```
+ */
+declare function parseSlots(input: string): readonly SlotNode[];
+/**
+ * Flatten a slot string to plain text: slot tags are dropped and their inner
+ * text is kept. This is how the `t` pipe and {@link injectTranslate} render a
+ * message containing `[name]...[/name]` slots — they return a string, so the
+ * markup degrades to text (the `[t]` directive renders the slots into templates
+ * instead).
+ *
+ * @example
+ * ```ts
+ * slotsToText('Read the [docs]documentation[/docs] now'); // 'Read the documentation now'
+ * slotsToText('Press [[Enter] to send'); // 'Press [Enter] to send'
+ * ```
+ */
+declare function slotsToText(input: string): string;
+
+/**
+ * Context handed to a slot's `<ng-template tFor>`:
+ *
+ * - `$implicit` — the slot's inner text, flattened to a string. `let-text` binds
+ *   it, so `{{ text }}` renders a plain-text slot (the common case).
+ * - `children` — the slot's parsed child nodes, for binding *nested* slots to
+ *   their own templates with `*tRender` instead of flattening them to text. Bind
+ *   it with `let-kids="children"`. See `TranslateSlotOutlet`.
+ */
+interface TranslateSlotContext {
+    readonly $implicit: string;
+    readonly children: readonly SlotNode[];
+}
+
+/**
+ * Provides an `<ng-template>` as the renderer for a named slot of the enclosing
+ * `[t]` element. The `[name]...[/name]` bracket syntax resembles BBCode, but the
+ * name is arbitrary and author-chosen — it identifies a slot to fill, not a tag
+ * with predefined HTML. Declared as a child of the `[t]` element (it renders as
+ * an invisible anchor), so the name is scoped to that element. The template
+ * receives the slot's inner text (`let-text`) and parsed children
+ * (`let-kids="children"`, for nesting via `*tRender`) as its context.
+ *
+ * @example
+ * ```html
+ * <ng-template tFor="docs" let-text>
+ *   <a routerLink="/docs">{{ text }}</a>
+ * </ng-template>
+ * ```
+ */
+declare class TranslateSlot {
+    /** Slot name, matching `[name]...[/name]` in the translation. */
+    readonly name: _angular_core.InputSignal<string>;
+    readonly templateRef: TemplateRef<TranslateSlotContext>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslateSlot, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TranslateSlot, "ng-template[tFor]", never, { "name": { "alias": "tFor"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Translate the `t` message and render it into the element, applying ICU `tParams`
+ * and binding any `[name]...[/name]` slot regions to `<ng-template tFor>`
+ * children.
+ *
+ * The message is the `t` attribute (a string expression), so it may contain both
+ * ICU (`{$name}`) and slot tags (`[name]`) safely. Rendered text is emitted as DOM
+ * text nodes, never HTML (CLAUDE.md §5.1); a slot with no matching template
+ * degrades to its inner text. Nested slots bind to their own templates when the
+ * parent template marks where they go with `*tRender` (see
+ * `TranslateSlotOutlet`); otherwise a nested slot renders as text. Re-renders
+ * when the language, params, or a slot template changes.
+ *
+ * @example
+ * ```html
+ * <p t="Hello {$name}!" [tParams]="{ name }"></p>
+ *
+ * <p t="Read the [docs]documentation[/docs] to get started">
+ *   <ng-template tFor="docs" let-text>
+ *     <a routerLink="/docs">{{ text }}</a>
+ *   </ng-template>
+ * </p>
+ * ```
+ */
+declare class TranslateDirective implements OnInit {
+    private readonly store;
+    private readonly host;
+    private readonly renderer;
+    private readonly formatter;
+    private readonly slotRenderer;
+    /** Source message (the translation key); may contain ICU and slot tags. */
+    readonly message: _angular_core.InputSignal<string>;
+    /** ICU arguments, formatted via `@ng-linguo/linguo/icu` when provided. */
+    readonly tParams: _angular_core.InputSignal<Record<string, unknown> | undefined>;
+    /** Optional disambiguating/contextual text (part of the key). */
+    readonly tContext: _angular_core.InputSignal<string>;
+    private readonly slots;
+    private templates;
+    constructor();
+    ngOnInit(): void;
+    /**
+     * Render a nested slot's `nodes` into `parent` before `before`, reusing the
+     * current templates and the shared renderer. Internal: called by
+     * `TranslateSlotOutlet` (`*tRender`); not part of the consumer-facing API.
+     */
+    renderChildren(parent: Node, before: Node, nodes: readonly SlotNode[]): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslateDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TranslateDirective, "[t]", never, { "message": { "alias": "t"; "required": true; "isSignal": true; }; "tParams": { "alias": "tParams"; "required": false; "isSignal": true; }; "tContext": { "alias": "tContext"; "required": false; "isSignal": true; }; }, {}, ["slots"], never, true, never>;
+}
+
+/**
+ * Renders the *children* of a slot at this position, so a nested slot binds to
+ * its own `<ng-template>` instead of flattening to text. Without it, a slot
+ * inside a templated slot renders as plain text (its `$implicit` value); with
+ * it, each nested slot finds its own `tFor` template.
+ *
+ * Bind the `children` from the enclosing slot's context and place the outlet
+ * where the nested content should appear:
+ *
+ * @example
+ * ```html
+ * <p t="Agree to our [link]Terms and [b]Conditions[/b][/link]">
+ *   <ng-template tFor="link" let-kids="children">
+ *     <a href="/terms"><ng-container *tRender="kids" /></a>
+ *   </ng-template>
+ *   <ng-template tFor="b" let-text><strong>{{ text }}</strong></ng-template>
+ * </p>
+ * ```
+ *
+ * Valid only inside a `[t]` element's slot template — it resolves the enclosing
+ * {@link TranslateDirective} and renders through its shared engine, so nested
+ * views are torn down with the rest on a language or params change.
+ */
+declare class TranslateSlotOutlet implements OnInit {
+    /** The nodes to render — the `children` value from the slot context. */
+    readonly nodes: _angular_core.InputSignal<readonly SlotNode[]>;
+    private readonly host;
+    private readonly anchor;
+    ngOnInit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslateSlotOutlet, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TranslateSlotOutlet, "[tRender]", never, { "nodes": { "alias": "tRender"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Formats a resolved message against runtime arguments — the seam that lets the
+ * `translate` pipe render ICU messages without `core` depending on any ICU
+ * library. `@ng-linguo/linguo/icu`'s `provideIcu` supplies an implementation; when none
+ * is provided the pipe simply returns the message unformatted.
+ */
+interface MessageFormatter {
+    /**
+     * @param message The resolved (translated) message, possibly containing ICU
+     *   placeholders.
+     * @param args Named arguments to substitute (counts, names, dates…).
+     * @param locale BCP-47 locale for plural rules and number/date formatting.
+     */
+    format(message: string, args: Record<string, unknown>, locale: string): string;
+}
+/**
+ * DI token for an optional {@link MessageFormatter}. Provided by
+ * `@ng-linguo/linguo/icu`'s `provideIcu`; absent by default.
+ */
+declare const MESSAGE_FORMATTER: InjectionToken<MessageFormatter>;
+
+export { MESSAGE_FORMATTER, TranslateDirective, TranslatePipe, TranslateSlot, TranslateSlotOutlet, TranslateStore, injectTranslate, mark, parseSlots, provideTranslate, slotsToText };
+export type { MarkOptions, MessageFormatter, SlotNode, TranslateConfig, TranslateFn, TranslateOptions, TranslateSlotContext, TranslationLoader, Translations };