langsys-js-typescript 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.2.1 - 2026-06-11
+
+### Changed
+
+- **Migrated off the deprecated API routes onto the current endpoints.** No public API change — the same `t()`, `<Phrase>`, and `<Translate>` usage now talks to:
+    - Reads: `GET /translations?project_id=…&locale=…` (was the deprecated `GET /projects/{id}/translations`).
+    - Writes: `POST /translatable-items` with a unified `{ project_id, translatable_items: [{ type: 'phrase' | 'content_block', … }] }` body (was the deprecated `POST /projects/{id}/tokens` and `POST /projects/{id}/content-blocks`).
+- Missing-phrase registration now chunks into batches of 200 to respect the `/translatable-items` per-request cap.
+- Added `LangsysAppAPI.createTranslatableItems()` as the single write entry point for both phrases and content blocks.
+
 ## 0.1.0 - 2026-05-19
 
 Initial public release. Framework-agnostic TypeScript SDK for the Langsys Translation Manager — the foundation that `langsys-js-svelte` (and future framework-specific bindings) build on.

package/README.md

@@ -9,7 +9,7 @@ This is the base SDK. Framework-specific bindings (`langsys-js-svelte`, and simi
 ## What's inside
 
 - `LangsysApp` singleton — init, locale switching, localized country/currency/locale helpers, preferred-locale detection.
-- `t(category, phrase, params?)` — the everyday translation function. The phrase is both the lookup key *and* the base-language default. Curly-brace placeholders interpolate from `params` and are compile-time type-checked.
+- `t(phrase, category?, params?)` — the everyday translation function. The phrase is both the lookup key *and* the base-language default. Curly-brace placeholders interpolate from `params` and are compile-time type-checked.
 - `tSignal: Signal<TFunction>` — reactive primitive that re-emits a fresh `t` on every translations/locale change. Framework bindings subscribe to this to drive re-renders.
 - `Translate` class — wraps a DOM element, walks text + translatable attributes, registers a content block with the Translation Manager, re-translates on locale change.
 - `Signal<T>` — tiny subscribe/set/update/get primitive. Compatible with Svelte's store contract by design, so the Svelte binding is nearly trivial.
@@ -42,13 +42,13 @@ const response = await LangsysApp.init({
 
 if (!response.status) console.error('Langsys init failed', response.errors);
 
-// 3. Translate
-document.querySelector('h1')!.textContent = t('Home', 'Welcome to my app');
-document.querySelector('#tagline')!.textContent = t('Marketing', 'We translate everything');
+// 3. Translate — t(phrase, category?, params?)
+document.querySelector('h1')!.textContent = t('Welcome to my app', 'Home');
+document.querySelector('#tagline')!.textContent = t('We translate everything', 'Marketing');
 
 // 4. Interpolate
 document.querySelector('#greeting')!.textContent =
-    t('Greetings', 'Hello, {name}!', { name: 'Sarah' });
+    t('Hello, {name}!', 'Greetings', { name: 'Sarah' });
 
 // 5. Change locale — all subscribed consumers re-translate
 userLocale.set('es-es');
@@ -56,27 +56,27 @@ userLocale.set('es-es');
 
 ### How `t()` works
 
-The phrase is the lookup key. The first time `t('Home', 'Welcome to my app')` runs with a write key, Langsys registers the phrase in the Translation Manager under the "Home" category. On subsequent locale changes, the SDK fetches translations and `t()` returns the translated version. If no translation exists yet, you get back the original phrase — your base language stays visible while translations get filled in.
+The signature is `t(phrase, category?, params?)` — the phrase comes first, the category is optional, params come last. The phrase is the lookup key. The first time `t('Welcome to my app', 'Home')` runs with a write key, Langsys registers the phrase in the Translation Manager under the "Home" category. On subsequent locale changes, the SDK fetches translations and `t()` returns the translated version. If no translation exists yet, you get back the original phrase — your base language stays visible while translations get filled in.
 
 #### Compile-time-checked interpolation
 
 Placeholder names are extracted from the phrase string literal via template-literal types, so missing or extra keys in `params` are TypeScript errors at the call site:
 
 ```ts
-t('Greetings', 'Hello, {name}!', { name: 'Sarah' });           // OK
-t('Greetings', 'Hello, {name}!', {});                          // ❌ Property 'name' missing
-t('Greetings', 'Hello, {name}!', { name: 'x', extra: 'y' });   // ❌ Unknown property 'extra'
+t('Hello, {name}!', 'Greetings', { name: 'Sarah' });           // OK
+t('Hello, {name}!', 'Greetings', {});                          // ❌ Property 'name' missing
+t('Hello, {name}!', 'Greetings', { name: 'x', extra: 'y' });   // ❌ Unknown property 'extra'
 ```
 
 Allowed value types: `string | number | Date | boolean`. Dates serialize to ISO 8601.
 
-> Future versions will swap the simple `{name}` runtime for ICU MessageFormat — adding plural / select / date formatting — without changing the public signature. Today's `t('Cart', '{count} items', { count })` will evolve to `t('Cart', '{count, plural, one {# item} other {# items}}', { count })`.
+> Future versions will swap the simple `{name}` runtime for ICU MessageFormat — adding plural / select / date formatting — without changing the public signature. Today's `t('{count} items', 'Cart', { count })` will evolve to `t('{count, plural, one {# item} other {# items}}', 'Cart', { count })`.
 
 #### Categorization disambiguates context
 
 ```ts
-t('Main Menu', 'Home');         // 'Inicio' in Spanish
-t('Home repairs', 'Home');      // 'Hogar' in Spanish
+t('Home', 'Main Menu');         // 'Inicio' in Spanish
+t('Home', 'Home repairs');      // 'Hogar' in Spanish
 ```
 
 The same phrase in different categories can have different translations. Without categorization, "Home" would only have one. Langsys's philosophy: *translate once, use everywhere* — categorize when the same phrase legitimately means different things in different parts of the app.
@@ -101,7 +101,7 @@ import { tSignal } from 'langsys-js-typescript';
 
 const unsub = tSignal.subscribe((t) => {
     // t is the current translation function — call it for the latest translations
-    document.querySelector('h1')!.textContent = t('Home', 'Welcome');
+    document.querySelector('h1')!.textContent = t('Welcome', 'Home');
 });
 ```
 
@@ -122,11 +122,11 @@ export function useT(): TFunction {
 // In a component:
 function Header() {
     const t = useT();
-    return <h1>{t('Home', 'Welcome, {name}!', { name: 'Sarah' })}</h1>;
+    return <h1>{t('Welcome, {name}!', 'Home', { name: 'Sarah' })}</h1>;
 }
 ```
 
-When a `langsys-js-react` package exists, it'll ship that hook plus a `<TranslateBlock>` wrapper around the DOM `Translate` class. Until then, the snippet above is the whole binding.
+The dedicated [`langsys-js-react`](https://github.com/langsys/langsys-js-react) package ships that hook (as `useT`) plus a `<Translate>` component around the DOM `Translate` class. The snippet above is the whole binding if you'd rather not add the dependency.
 
 ### Svelte
 
@@ -195,7 +195,7 @@ const locale = LangsysApp.detectPreferredLocale(
 );
 ```
 
-The matcher tries exact match first (`en-US`), then language-only (`en` matches `en-GB`), then returns `null`.
+The matcher tries exact match first (`en-US`), then language-only (`en` matches `en-GB`). When you pass `supported` and none match, it falls back to the user's top preference (normalized); it returns `false` only when no preference can be determined at all.
 
 ## Localized country / currency / locale lists
 
@@ -261,7 +261,7 @@ import type {
 - `LangsysApp.getCurrencies(inLocale?)` / `.getCurrencyName(code, inLocale?)`
 - `LangsysApp.getLocales(inLocale?)` / `.getLocalesFlat(inLocale?)` / `.getLocalesData(inLocale?, force?)`
 - `LangsysApp.getLocaleName(code, short?, inLocale?)` / `.getLocaleNameWithLookup(...)`
-- Top-level: `t`, `tSignal`, `currentlyLoadedLocale`, `sTranslations`, `contentBlocks`, `LangsysAppAPI`, `Translate`, `createSignal`, `getValue`, `persist`, `interpolate`, `Logger`, `logger`, `md5`, `isEmpty`.
+- Top-level: `t`, `tSignal`, `currentlyLoadedLocale`, `sTranslations`, `LangsysAppAPI`, `Translate`, `createSignal`, `getValue`, `persist`, `interpolate`, `Logger`, `logger`, `md5`, `isEmpty`.
 
 ## License
 

package/dist/index.d.mts

@@ -60,17 +60,37 @@ type iCategories = {
     __uncategorized__: iTranslations;
 };
 
+/**
+ * Minimum interface for a user-locale source.
+ *
+ * The SDK only ever READS and SUBSCRIBES to this — never writes. That lets
+ * each framework adapt its native state into this shape with a small adapter:
+ *
+ *   - Svelte: a `writable<string>` satisfies this directly.
+ *   - React:  wrap `useState` via `useSyncExternalStore` — a 5-line adapter.
+ *   - Vue:    wrap `ref<string>` via `watch` + a `.value` getter.
+ *   - Angular: a `BehaviorSubject<string>` satisfies this directly.
+ *   - Vanilla: use the SDK's own `createSignal<string>('en-us')`.
+ *
+ * Designed as the smallest possible contract so framework wrappers stay thin.
+ */
+interface LocaleSource {
+    /** Read the current locale synchronously. */
+    get(): string;
+    /** Register a callback for locale changes. Returns an unsubscribe function. */
+    subscribe(run: (locale: string) => void): () => void;
+}
 interface iLangsysInitConfig {
     /** The ID (UUID) of the project created in Langsys */
     projectid: string;
     /** The API key associated with the project */
     key: string;
     /**
-     * A reactive holder for the user's selected locale. Accepts any object
-     * with `subscribe`, `set`, and `get` methods (our `Signal<string>` works
-     * out of the box). Use `createSignal('en-us')` if you have nothing of your own.
+     * A reactive source for the user's selected locale. See `LocaleSource`
+     * for the minimum contract. The SDK's own `createSignal('en-us')` works
+     * out of the box if you don't have a framework-native store of your own.
      */
-    UserLocaleStore: Signal<string>;
+    UserLocaleStore: LocaleSource;
     /**
      * Base language/locale for the source strings in your code.
      * @default 'en'
@@ -102,7 +122,7 @@ interface iLangsysInitConfig {
 interface iLangsysConfig {
     projectid: string;
     key: string;
-    sUserLocale: Signal<string>;
+    sUserLocale: LocaleSource;
     baseLocale: string;
     debug?: boolean;
     /** Permission level of the API key, set automatically after successful authorization. */
@@ -122,7 +142,7 @@ interface iLangsysConfig {
  *
  * The big trick here is `ExtractParamKeys` — a recursive template-literal
  * type that pulls placeholder names out of a phrase at compile time, so
- * `t('Cat', 'Hello, {name}!', { name: 'Sarah' })` is type-checked: passing
+ * `t('Hello, {name}!', { name: 'Sarah' })` is type-checked: passing
  * an object without `name`, or with a key not in the phrase, is a TS error.
  */
 /** Allowed value types for interpolation. Mirrors what ICU MessageFormat will accept. */
@@ -147,9 +167,22 @@ type ParamsFor<S extends string> = {
 type TArgs<P extends string> = [ExtractParamKeys<P>] extends [never] ? [] : [params: ParamsFor<P>];
 /** Loose params type — used inside generic stores where the phrase isn't a known literal. */
 type TranslationParams = Record<string, ParamPrimitive>;
-/** The translation function signature. */
+/**
+ * The translation function signature.
+ *
+ *   t('Save')                                     // no category, no params
+ *   t('Save', 'UI')                               // categorized
+ *   t('Hello, {name}!', { name: 'X' })            // no category, with params
+ *   t('Hello, {name}!', 'Greetings', { name: 'X' }) // category + params
+ *
+ * Two overloads discriminate on the type at position 2 (string → category,
+ * object → params). `category` is required for the second overload —
+ * pass any non-empty string. There is no "null category" wire concept:
+ * absent category means absent.
+ */
 interface TFunction {
-    <P extends string>(category: string, phrase: P, ...args: TArgs<P>): string;
+    <P extends string>(phrase: P, ...args: TArgs<P>): string;
+    <P extends string>(phrase: P, category: string, ...args: TArgs<P>): string;
 }
 
 /**
@@ -170,10 +203,20 @@ declare class Translations {
     private timer;
     private flushScheduled;
     private isFirstClientRun;
+    private readyResolve;
+    private readyPromise;
     debug: Logger;
     /** Reactive holder for the current translation function. Re-emits on every catalog/locale change. */
     tSignal: Signal<TFunction>;
     constructor(config: iLangsysConfig);
+    /**
+     * Resolves once the first `getTranslations` call has completed (or
+     * immediately if no fetch is configured). Callers that need to read
+     * `sTranslations` before issuing a write — e.g. the `Translate` DOM
+     * class deciding whether to POST a content block — should await this
+     * to avoid acting on an empty cache during the cold-start race.
+     */
+    ready(): Promise<void>;
     /** Current translation function. Reads fresh state on every call. */
     get t(): TFunction;
     /** Subscribe to translation snapshot changes. Fires immediately with the current value. */
@@ -185,6 +228,13 @@ declare class Translations {
      * a missing token — the DOM class manages its own lifecycle via content blocks.
      */
     lookupContent(category: string, customId: string, token: string): string | null;
+    /**
+     * Raw stored translation for a phrase, without interpolation or
+     * missing-token registration. Returns null when no (non-empty) translation
+     * is cached. Used by the `Phrase` rich-text handler, which needs the
+     * un-interpolated template (it supplies its own markup-token values).
+     */
+    lookup(phrase: string, category: string): string | null;
     private buildTFn;
     private missingToken;
     private scheduleTokenFlush;
@@ -273,7 +323,8 @@ declare class LangsysAppClass {
     refresh(): Promise<boolean>;
     /**
      * Initialize Langsys. Configuration must include at least `projectid`,
-     * `key`, and `UserLocaleStore` (any Signal<string>).
+     * `key`, and `UserLocaleStore` (anything satisfying `LocaleSource` — see
+     * its docstring for framework-specific adapters).
      */
     init(initConfig: iLangsysInitConfig): Promise<ResponseObject>;
     getDialCodes(inLocale?: string): Promise<iCountryDialCode[]>;
@@ -329,7 +380,6 @@ interface TranslateOptions {
 declare class Translate {
     private element;
     private options;
-    private contentClone;
     private tokens;
     private parseComplete;
     private isTokenizing;
@@ -342,17 +392,115 @@ declare class Translate {
     private translateUpdate;
     private tokenizeContent;
     private handleContentBlock;
-    private tokenize;
-    private tokenizeAttributes;
-    private findNode;
     private translate;
     private getTranslation;
     private translateAttributes;
     private translateAttribute;
-    private generateCustomId;
-    private applyStylesToNode;
 }
 
+/** Attribute marker the `Translate` tokenizer uses to skip a `<Phrase>` subtree. */
+declare const PHRASE_MARKER_ATTR = "data-ls-phrase";
+interface PhraseOptions {
+    /** Category the phrase registers under (disambiguation for translators). */
+    category?: string;
+    /** Interpolation params — `{n}` for pluralization, `{name}`, etc. */
+    params?: Record<string, unknown>;
+}
+/**
+ * DOM handler for a markup-bearing "rich" phrase (`<Phrase>`).
+ *
+ * Wraps an element whose inner content is ONE translatable phrase even though
+ * it contains inline markup. On mount it encodes the subtree to a single phrase
+ * string with neutral `{mNo}`/`{mNc}` markup tokens (the real elements stay in
+ * the SDK — see richtext.ts), registers it, and renders the translation by
+ * reconstituting the original elements around the translated text. Re-renders
+ * on locale change and whenever params change.
+ *
+ *   new Phrase(el, { category: 'ProductCard', params: { n: reviewCount } });
+ */
+declare class Phrase {
+    private host;
+    private category;
+    private params;
+    private phrase;
+    private slots;
+    private unsubscribers;
+    private ready;
+    constructor(host: HTMLElement, options?: PhraseOptions);
+    /** Update interpolation params (e.g. a changed count) and re-render. */
+    setParams(params: Record<string, unknown>): void;
+    /** Stop reacting to locale/translation changes. Safe to call multiple times. */
+    destroy(): void;
+    private _init;
+    private _render;
+}
+
+/**
+ * Rich-text (markup-bearing) phrase encoding for the `<Phrase>` artifact.
+ *
+ * The problem: a phrase like `You have {n} <strong>reviews</strong>` must stay
+ * ONE phrase (so pluralization sees `{n}` next to `reviews`), but we must NOT
+ * send the SPA's real markup — and especially not framework-internal scoped-CSS
+ * classes (`svelte-a1b2c3`, Vue scoped hashes) — to the translator. Those
+ * classes get mangled, and worse they change on every build, which would make
+ * the phrase key drift and silently re-translate everything.
+ *
+ * The approach: replace each inline element with a pair of neutral MARKUP
+ * TOKENS — `{m0o}` ... `{m0c}` (markup, slot 0, open/close). These are ordinary
+ * ICU placeholders: valid MessageFormat argument names, so plural/select still
+ * parse, and the model treats them like `{n}` — it preserves them and PLACES
+ * them around the translated word (which is what fixes reordering languages,
+ * e.g. `<span>White</span> House` -> `Casa <span>Blanca</span>`).
+ *
+ * The real DOM elements never leave the SDK. At render time we resolve the
+ * translation, substitute each markup token with a private-use SENTINEL char
+ * (transient — never sent anywhere), then reconstitute the DOM by wrapping the
+ * sentinel-delimited spans in the ORIGINAL framework-owned elements. Scoped CSS
+ * survives because we reuse the real element; the phrase key is stable because
+ * the wire form only ever contains `{m0o}`/`{m0c}`, never build-specific hashes.
+ */
+/** A captured inline element: a shallow clone (tag + attributes, no children). */
+interface RichSlot {
+    /** Shallow clone of the original element — preserves tag, class, href, etc. */
+    template: HTMLElement;
+}
+interface EncodedRichText {
+    /**
+     * The phrase string with inline elements replaced by `{mNo}`...`{mNc}` markup
+     * tokens. This is what gets registered + sent for translation.
+     */
+    phrase: string;
+    /** Captured inline elements, indexed by markup-token slot number. */
+    slots: RichSlot[];
+}
+/**
+ * Walk an element's subtree and produce the encoded phrase + captured slots.
+ *
+ * Text nodes contribute their (whitespace-collapsed) text. Each child element
+ * becomes a markup-token pair wrapping its recursively-encoded contents, and a
+ * shallow clone of the element is captured as a slot. Nesting is preserved.
+ */
+declare function encodeRichText(root: HTMLElement): EncodedRichText;
+/**
+ * The param values to feed alongside the user's params when resolving a rich
+ * phrase. Each markup token maps to its sentinel pair so the resolved string
+ * carries machine-findable delimiters for reconstitution.
+ */
+declare function markupTokenValues(slotCount: number): Record<string, string>;
+/**
+ * Rebuild DOM nodes from a resolved string containing sentinel-delimited spans.
+ *
+ * The original (framework-owned) elements are reused as wrappers — so scoped
+ * CSS classes / attributes survive — with the translated text placed inside.
+ *
+ * Robust to model mistakes: if sentinels are unbalanced (a tag dropped or a
+ * stray close), we fall back to a single plain-text node (markers stripped) —
+ * "lose the markup, keep the meaning" rather than throw.
+ */
+declare function reconstitute(resolved: string, slots: RichSlot[], doc?: Document): Node[];
+/** Remove any sentinel markers from a string, leaving the bare text. */
+declare function stripSentinels(value: string): string;
+
 declare class LangsysAppAPIClass {
     private apiurl;
     config: iLangsysConfig;
@@ -363,6 +511,12 @@ declare class LangsysAppAPIClass {
     setBaseUrl(url: string): void;
     validate(config: iLangsysConfig): Promise<ResponseObject>;
     getTranslations(locale: string): Promise<ResponseObject>;
+    /**
+     * Register phrases and/or content blocks via the current unified endpoint.
+     * Each item carries `type: 'phrase' | 'content_block'`. Replaces the
+     * deprecated `projects/{id}/tokens` and `projects/{id}/content-blocks` routes.
+     */
+    createTranslatableItems(items: Array<Record<string, unknown>>): Promise<ResponseObject>;
     post(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
     get(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
     delete(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
@@ -372,13 +526,6 @@ declare class LangsysAppAPIClass {
 }
 declare const LangsysAppAPI: LangsysAppAPIClass;
 
-/**
- * Create a Signal whose value is persisted to localStorage (when available).
- * Falls back to in-memory behavior during SSR or when storage is unavailable
- * or quota-exceeded. Stored value is JSON-encoded.
- */
-declare function persist<T>(key: string, initial: T): Signal<T>;
-
 interface iContentBlock {
     custom_id: string;
     category: string;
@@ -387,23 +534,139 @@ interface iContentBlock {
     tokens: string[];
 }
 
+/**
+ * Framework-agnostic content-block helpers.
+ *
+ * The DOM-mutating `Translate` class in `translate.ts` is one consumer of
+ * these — it walks a live element, tokenizes it, registers the content
+ * block, and mutates the same element in place. That model fits Svelte
+ * and vanilla JS, where the SDK genuinely owns the DOM node.
+ *
+ * For React/Vue/Angular wrappers, mutating the DOM directly is an anti-
+ * pattern — those frameworks own their rendered output. Wrappers should
+ * import the helpers below to handle the framework-agnostic parts (token
+ * discovery, content-block registration, dedup against the local cache)
+ * and render translated content through their framework's native means.
+ *
+ * Wrapper pattern:
+ *
+ *   1. After mount, grab the rendered DOM via the framework's ref/binding.
+ *   2. `const { tokens, content } = tokenizeElement(el);`
+ *   3. `const customId = generateCustomId(category, tokens);`
+ *   4. `if (!isContentBlockKnown(category, customId)) {`
+ *      `    await registerContentBlock({ custom_id: customId, category, content, tokens, label });`
+ *      `}`
+ *   5. Subscribe to `sTranslations` + `currentlyLoadedLocale`; on change,
+ *      look up each token via `Translations.lookupContent(category, customId, token)`
+ *      and render via your framework's templating.
+ */
+
+/**
+ * Compute the deterministic content-block id from a `(category, tokens)` pair.
+ *
+ * JSON-stringifies the tuple so each token is unambiguously delimited
+ * (the previous `tokens.join('-')` was collision-prone for tokens
+ * containing a hyphen, e.g. `'e-mail'`).
+ *
+ * Pure function — same inputs always produce the same id. Exported so
+ * framework wrappers can compute the id themselves before deciding
+ * whether to call `registerContentBlock`.
+ */
+declare function generateCustomId(category: string, tokens: string[]): string;
+/**
+ * True iff the local translations cache already has the content block
+ * for the given `(category, customId)` — meaning the backend knows about
+ * it and there's no need to re-register.
+ *
+ * The cache is keyed under `'__uncategorized__'` for null/empty categories,
+ * matching the convention the server uses in its GET /translations response.
+ */
+declare function isContentBlockKnown(category: string, customId: string): boolean;
+/**
+ * POST a content block to the backend, then stamp its custom_id into the
+ * local translations cache so subsequent mounts in this session — and
+ * subsequent reloads, since the cache is persisted — skip the POST.
+ *
+ * Mirrors the standalone-phrase path's cache writeback semantics. Respects
+ * `key_type === 'write'`: read-only keys silently no-op (resolves with
+ * `{ status: true }` so the caller can still render the cached translation).
+ *
+ * Errors are logged via the SDK's logger and returned as `{ status: false }`
+ * — never thrown. Callers can decide whether to surface to UI or swallow.
+ */
+declare function registerContentBlock(contentBlock: iContentBlock): Promise<{
+    status: boolean;
+    errors?: unknown[];
+}>;
+/**
+ * Walk an `HTMLElement`, collecting tokens for translation and producing a
+ * cloned-and-stylized snapshot of its outerHTML for the Translation Manager.
+ *
+ * Tokens harvested:
+ *  - text-node content (whitespace-normalized, trimmed)
+ *  - translatable attribute values (`placeholder`, `alt`, `title`, `aria-*`, etc.)
+ *  - button/input/select value text
+ *
+ * Skips subtrees marked with `translate="no"`.
+ *
+ * The returned `content` is a string snapshot — the live element is not
+ * mutated. Computed semantic styles (color, font, spacing, etc.) are inlined
+ * onto the clone so translators see content styled the way end-users do.
+ *
+ * Requires that `element` is mounted in the document so `getComputedStyle`
+ * can read its style. For SSR / pre-mount callers, the style capture step
+ * silently no-ops and the snapshot is plain (without inlined styles).
+ */
+declare function tokenizeElement(element: HTMLElement): {
+    tokens: string[];
+    content: string;
+};
+
+/**
+ * Create a Signal whose value is persisted to localStorage (when available).
+ * Falls back to in-memory behavior during SSR or when storage is unavailable
+ * or quota-exceeded. Stored value is JSON-encoded.
+ */
+declare function persist<T>(key: string, initial: T): Signal<T>;
+
 declare const sTranslations: Signal<iCategories>;
 declare const currentlyLoadedLocale: Signal<string>;
-declare const contentBlocks: Signal<iContentBlock[]>;
 
 declare const isEmpty: (data: unknown) => boolean;
 declare function md5(inputString: string): string;
 
 /**
- * Substitute `{name}`-style placeholders in a translated string with values
- * from `params`. Unknown placeholders are left untouched so missing data is
- * visible to the developer rather than silently rendering empty strings.
+ * Detects ICU MessageFormat syntax in a translation string.
+ *
+ *   - Matches `{var, plural, …}`, `{var, select, …}`, `{var, selectordinal, …}`,
+ *     `{var, number, …}`, `{var, date, …}`, `{var, time, …}`.
+ *   - Doesn't match plain interpolation slots like `{name}` or `{count}`.
+ *
+ * Exported because the Translation Manager UI needs the same detection logic
+ * to decide whether to render a plural-slot editor vs. a single text field.
+ */
+declare function isICU(template: string): boolean;
+/**
+ * Substitute placeholders in a translated string with values from `params`.
+ *
+ * Two paths:
+ *   - ICU MessageFormat (target string contains `{var, plural|select|…, …}`):
+ *     parsed and formatted via `intl-messageformat`, which knows every
+ *     target locale's plural rules (Arabic's 6 categories, Russian's 4,
+ *     etc.) and gender-select branches.
+ *   - Simple `{name}` interpolation: cheap regex replacement. Unknown
+ *     placeholders are left untouched so missing data is visible to the
+ *     developer rather than silently rendering empty strings.
+ *
+ * Malformed ICU falls through to simple interpolation rather than throwing,
+ * so the developer sees a broken-but-visible string instead of a runtime crash.
+ * Backend-side validation in langsys-ai is supposed to prevent this — the
+ * fall-through is defense in depth.
  *
- * Dates are serialized to ISO 8601; everything else goes through `String()`.
- * Designed as a forward-compatible stop-gap until ICU MessageFormat is wired
- * in for plurals/select/date formatting.
+ * `locale` is required for ICU formatting (drives plural-rule selection).
+ * Falls back to `'en'` if absent — simple-interpolation path ignores it.
  */
-declare function interpolate(template: string, params: Record<string, unknown>): string;
+declare function interpolate(template: string, params: Record<string, unknown>, locale?: string): string;
 
 interface iProject {
     id: string;
@@ -425,4 +688,4 @@ interface iProject {
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
 
-export { type ExtractParamKeys, LangsysApp, LangsysAppAPI, Logger, type ParamPrimitive, type ParamsFor, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, contentBlocks, createSignal, currentlyLoadedLocale, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isEmpty, logger, md5, persist, sTranslations, t, tSignal };
+export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, createSignal, currentlyLoadedLocale, encodeRichText, generateCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };