langsys-js-typescript 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.3.0 - 2026-07-03
+
+Full CLDR compliance, matching the backend's CLDR migration. Everything rides on the platform's native `Intl` APIs — no new dependencies, no bundled locale data.
+
+### Changed
+
+- **Locale identifiers are now BCP 47 canonical everywhere.** `en-us` → `en-US`, `zh-hant-tw` → `zh-Hant-TW`, `en_US` → `en-US`, legacy aliases resolved (`iw` → `he`). Canonicalization happens at every input boundary (init config, user-locale store emissions, `detectPreferredLocale`, API params), so the canonical form is what goes on the wire and what keys every internal cache. Lowercase locales in existing configs keep working — they're canonicalized on the way in.
+- **`detectPreferredLocale` matching is script-aware** via CLDR likely-subtags (`Intl.Locale.maximize()`). `es-MX` matches a supported `es-ES` or `es`; `zh-TW` matches `zh-Hant` and never `zh-Hans` — cross-script fallbacks are refused instead of guessed. Previously matching truncated to the bare language code, which could hand a Traditional Chinese reader a Simplified catalog.
+- **Simple `{name}` interpolation formats numbers and Dates per the target locale's CLDR rules.** Numbers go through `Intl.NumberFormat` (`1234.5` → `1.234,5` in `de-DE`); Dates through `Intl.DateTimeFormat` medium date style (previously ISO 8601). Pass values as strings to opt out — e.g. IDs that must not get grouping separators.
+
+### Fixed
+
+- **Style-less ICU arguments (`{n, number}`, `{d, date}`, `{t, time}`) now format correctly.** The ICU detector required a style argument, so these valid ICU forms fell through to simple interpolation and rendered as literal `{n, number}` text.
+- Locale equality checks (fetch dedup, country/currency/dial-code caches) no longer miss when the same locale arrives with different casing.
+
+### Added
+
+- `canonicalizeLocale(locale)` — exported BCP 47 canonicalizer, useful when seeding your own `UserLocaleStore`.
+
 ## 0.2.1 - 2026-06-11
 
 ### Changed

package/README.md

@@ -29,14 +29,14 @@ import { LangsysApp, createSignal, t } from 'langsys-js-typescript';
 
 // 1. A reactive holder for the user's current locale. Use `createSignal` if you
 //    have nothing of your own — any object with subscribe/set/update/get works.
-const userLocale = createSignal('en-us');
+const userLocale = createSignal('en-US');
 
 // 2. Initialize
 const response = await LangsysApp.init({
     projectid: process.env.LANGSYS_PROJECT_ID!,
     key: process.env.LANGSYS_API_KEY!,
     UserLocaleStore: userLocale,
-    baseLocale: 'en-us',
+    baseLocale: 'en-US',
     debug: false,
 });
 
@@ -51,7 +51,7 @@ document.querySelector('#greeting')!.textContent =
     t('Hello, {name}!', 'Greetings', { name: 'Sarah' });
 
 // 5. Change locale — all subscribed consumers re-translate
-userLocale.set('es-es');
+userLocale.set('es-ES');
 ```
 
 ### How `t()` works
@@ -68,9 +68,9 @@ t('Hello, {name}!', 'Greetings', {});                          // ❌ Property '
 t('Hello, {name}!', 'Greetings', { name: 'x', extra: 'y' });   // ❌ Unknown property 'extra'
 ```
 
-Allowed value types: `string | number | Date | boolean`. Dates serialize to ISO 8601.
+Allowed value types: `string | number | Date | boolean`. Numbers and Dates format per the active locale's CLDR rules (`1234.5` → `1.234,5` in `de-DE`; Dates use the medium date style). Pass values as strings to opt out — e.g. IDs and codes that must not get grouping separators.
 
-> 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 })`.
+> Translations containing ICU MessageFormat syntax — `{count, plural, one {# item} other {# items}}`, `{gender, select, …}`, `{n, number}`, `{d, date}` — are rendered with full CLDR plural rules for the active locale (Arabic's six categories, Russian's four, etc.). Plain `{name}` slots keep working unchanged.
 
 #### Categorization disambiguates context
 
@@ -167,9 +167,9 @@ await LangsysApp.init({
     projectid: env.LANGSYS_PROJECT_ID,
     key: env.LANGSYS_API_KEY,
     UserLocaleStore: userLocale,
-    baseLocale: 'en-us',
+    baseLocale: 'en-US',
     initialTranslations,                       // fetched on the server
-    initialTranslationsLocale: 'es-es',
+    initialTranslationsLocale: 'es-ES',
     ssrTokenStrategy: 'client',                // 'client' | 'server' | 'auto'
 });
 ```
@@ -187,7 +187,7 @@ const locale = LangsysApp.detectPreferredLocale();
 // SSR — parse Accept-Language header
 const locale = LangsysApp.detectPreferredLocale(req.headers['accept-language']);
 
-// Match against your app's supported locales, falling back to language-only matches
+// Match against your app's supported locales (script-aware CLDR matching)
 const supported = (await LangsysApp.getLocalesFlat()).map((l) => l.code);
 const locale = LangsysApp.detectPreferredLocale(
     req.headers['accept-language'],
@@ -195,7 +195,7 @@ const locale = LangsysApp.detectPreferredLocale(
 );
 ```
 
-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.
+The matcher tries an exact match first (`en-US`), then falls back to same-language-and-script matching using CLDR likely-subtags data (`es-MX` matches `es-ES`; `zh-TW` matches `zh-Hant` but never `zh-Hans` — cross-script fallbacks are deliberately refused). All results come back in BCP 47 canonical form (`en-US`, `zh-Hant-TW`). When you pass `supported` and none match, it falls back to the user's top preference (canonicalized); it returns `false` only when no preference can be determined at all.
 
 ## Localized country / currency / locale lists
 
@@ -204,7 +204,7 @@ const countries    = await LangsysApp.getCountries();    // [{ code, label }, ..
 const dialCodes    = await LangsysApp.getDialCodes();    // [{ country_code, dial_code, name }, ...]
 const currencies   = await LangsysApp.getCurrencies();   // [{ code, name, symbol, ... }, ...]
 const locales      = await LangsysApp.getLocales();      // { LanguageName: [{ code, name }] }
-const localeName   = await LangsysApp.getLocaleNameWithLookup('es-es', true, 'fr-fr'); // 'espagnol'
+const localeName   = await LangsysApp.getLocaleNameWithLookup('es-ES', true, 'fr-FR'); // 'espagnol'
 ```
 
 ## The `Signal<T>` primitive

package/dist/index.d.mts

@@ -358,8 +358,12 @@ declare class LangsysAppClass {
     private getUserLanguagePreferences;
     private parseAcceptLanguageHeader;
     private findBestLocaleMatch;
-    private normalizeLocale;
-    private getLanguageCode;
+    /**
+     * Resolve the effective locale for a data-fetching helper: explicit
+     * argument, else the user's current locale, else the base locale —
+     * always in BCP 47 canonical form so cache keys and API routes agree.
+     */
+    private resolveLocale;
 }
 declare const LangsysApp: LangsysAppClass;
 
@@ -371,6 +375,8 @@ interface TranslateOptions {
     custom_id?: string;
     /** Optional human-readable label shown in the Translation Manager. */
     label?: string;
+    /** Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax as `t()`. */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * Wrap a DOM element and manage translation for its contents.
@@ -395,6 +401,8 @@ declare class Translate {
     private custom_id;
     private unsubscribeLocale;
     constructor(element: HTMLElement, options?: TranslateOptions);
+    /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
+    setParams(params: Record<string, ParamPrimitive> | undefined): void;
     /** Stop reacting to locale changes. Safe to call multiple times. */
     destroy(): void;
     private translateUpdate;
@@ -402,6 +410,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Interpolate `{name}`-style params into a resolved text, matching `t()`:
+     * unknown keys fall through untouched, and the untranslated fallback is
+     * interpolated too. No-op when no params were supplied.
+     */
+    private applyParams;
     private translateAttributes;
     private translateAttribute;
 }
@@ -648,6 +662,8 @@ declare function md5(inputString: string): string;
  *
  *   - Matches `{var, plural, …}`, `{var, select, …}`, `{var, selectordinal, …}`,
  *     `{var, number, …}`, `{var, date, …}`, `{var, time, …}`.
+ *   - Also matches the style-less forms `{var, number}`, `{var, date}`,
+ *     `{var, time}` — valid ICU with the locale-default style.
  *   - Doesn't match plain interpolation slots like `{name}` or `{count}`.
  *
  * Exported because the Translation Manager UI needs the same detection logic
@@ -664,7 +680,11 @@ declare function isICU(template: string): boolean;
  *     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.
+ *     developer rather than silently rendering empty strings. Number and
+ *     Date values are formatted per the target locale's CLDR rules
+ *     (`Intl.NumberFormat` / `Intl.DateTimeFormat`) — pass numbers as
+ *     strings to opt out (e.g. IDs and codes that must not get grouping
+ *     separators).
  *
  * Malformed ICU falls through to simple interpolation rather than throwing,
  * so the developer sees a broken-but-visible string instead of a runtime crash.
@@ -676,6 +696,28 @@ declare function isICU(template: string): boolean;
  */
 declare function interpolate(template: string, params: Record<string, unknown>, locale?: string): string;
 
+/**
+ * Locale-identifier handling, CLDR/BCP 47 flavored. Everything here rides on
+ * the platform's native `Intl` — no bundled locale data.
+ *
+ * The SDK's convention: canonicalize once at every input boundary (init
+ * config, user-locale store emissions, detectPreferredLocale, API routes) and
+ * treat the canonical string as the identity everywhere downstream — cache
+ * keys, equality checks, and the wire format all use it.
+ */
+/**
+ * Canonicalize a locale identifier to BCP 47 canonical form (the form CLDR
+ * data is keyed by): language lowercase, script Titlecase, region uppercase —
+ * `en-us` → `en-US`, `zh-hant-tw` → `zh-Hant-TW`. Underscores are accepted
+ * and converted (`en_US` → `en-US`). Legacy aliases are resolved (`iw` → `he`,
+ * `in` → `id`).
+ *
+ * Structurally invalid tags fall back to best-effort manual casing rather
+ * than throwing, so a bad config value degrades to a failed catalog lookup
+ * instead of a crash.
+ */
+declare function canonicalizeLocale(locale: string): string;
+
 interface iProject {
     id: string;
     owner_id: string;
@@ -696,4 +738,4 @@ interface iProject {
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
 
-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 };
+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, canonicalizeLocale, 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 };

package/dist/index.d.ts

@@ -358,8 +358,12 @@ declare class LangsysAppClass {
     private getUserLanguagePreferences;
     private parseAcceptLanguageHeader;
     private findBestLocaleMatch;
-    private normalizeLocale;
-    private getLanguageCode;
+    /**
+     * Resolve the effective locale for a data-fetching helper: explicit
+     * argument, else the user's current locale, else the base locale —
+     * always in BCP 47 canonical form so cache keys and API routes agree.
+     */
+    private resolveLocale;
 }
 declare const LangsysApp: LangsysAppClass;
 
@@ -371,6 +375,8 @@ interface TranslateOptions {
     custom_id?: string;
     /** Optional human-readable label shown in the Translation Manager. */
     label?: string;
+    /** Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax as `t()`. */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * Wrap a DOM element and manage translation for its contents.
@@ -395,6 +401,8 @@ declare class Translate {
     private custom_id;
     private unsubscribeLocale;
     constructor(element: HTMLElement, options?: TranslateOptions);
+    /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
+    setParams(params: Record<string, ParamPrimitive> | undefined): void;
     /** Stop reacting to locale changes. Safe to call multiple times. */
     destroy(): void;
     private translateUpdate;
@@ -402,6 +410,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Interpolate `{name}`-style params into a resolved text, matching `t()`:
+     * unknown keys fall through untouched, and the untranslated fallback is
+     * interpolated too. No-op when no params were supplied.
+     */
+    private applyParams;
     private translateAttributes;
     private translateAttribute;
 }
@@ -648,6 +662,8 @@ declare function md5(inputString: string): string;
  *
  *   - Matches `{var, plural, …}`, `{var, select, …}`, `{var, selectordinal, …}`,
  *     `{var, number, …}`, `{var, date, …}`, `{var, time, …}`.
+ *   - Also matches the style-less forms `{var, number}`, `{var, date}`,
+ *     `{var, time}` — valid ICU with the locale-default style.
  *   - Doesn't match plain interpolation slots like `{name}` or `{count}`.
  *
  * Exported because the Translation Manager UI needs the same detection logic
@@ -664,7 +680,11 @@ declare function isICU(template: string): boolean;
  *     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.
+ *     developer rather than silently rendering empty strings. Number and
+ *     Date values are formatted per the target locale's CLDR rules
+ *     (`Intl.NumberFormat` / `Intl.DateTimeFormat`) — pass numbers as
+ *     strings to opt out (e.g. IDs and codes that must not get grouping
+ *     separators).
  *
  * Malformed ICU falls through to simple interpolation rather than throwing,
  * so the developer sees a broken-but-visible string instead of a runtime crash.
@@ -676,6 +696,28 @@ declare function isICU(template: string): boolean;
  */
 declare function interpolate(template: string, params: Record<string, unknown>, locale?: string): string;
 
+/**
+ * Locale-identifier handling, CLDR/BCP 47 flavored. Everything here rides on
+ * the platform's native `Intl` — no bundled locale data.
+ *
+ * The SDK's convention: canonicalize once at every input boundary (init
+ * config, user-locale store emissions, detectPreferredLocale, API routes) and
+ * treat the canonical string as the identity everywhere downstream — cache
+ * keys, equality checks, and the wire format all use it.
+ */
+/**
+ * Canonicalize a locale identifier to BCP 47 canonical form (the form CLDR
+ * data is keyed by): language lowercase, script Titlecase, region uppercase —
+ * `en-us` → `en-US`, `zh-hant-tw` → `zh-Hant-TW`. Underscores are accepted
+ * and converted (`en_US` → `en-US`). Legacy aliases are resolved (`iw` → `he`,
+ * `in` → `id`).
+ *
+ * Structurally invalid tags fall back to best-effort manual casing rather
+ * than throwing, so a bad config value degrades to a failed catalog lookup
+ * instead of a crash.
+ */
+declare function canonicalizeLocale(locale: string): string;
+
 interface iProject {
     id: string;
     owner_id: string;
@@ -696,4 +738,4 @@ interface iProject {
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
 
-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 };
+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, canonicalizeLocale, 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 };