langsys-js-typescript 0.2.2 → 0.3.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;
 
@@ -648,6 +652,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 +670,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 +686,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 +728,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;
 
@@ -648,6 +652,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 +670,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 +686,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 +728,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.js

@@ -2,6 +2,31 @@
 
 var intlMessageformat = require('intl-messageformat');
 
+// src/locale.ts
+function canonicalizeLocale(locale) {
+  if (!locale || typeof locale !== "string") return locale;
+  const cleaned = locale.trim().replace(/_/g, "-");
+  try {
+    const [canonical] = Intl.getCanonicalLocales(cleaned);
+    return canonical ?? cleaned;
+  } catch {
+    return cleaned.split("-").map((part, i) => {
+      if (i === 0) return part.toLowerCase();
+      if (part.length === 4) return part[0].toUpperCase() + part.slice(1).toLowerCase();
+      if (part.length === 2 || /^\d{3}$/.test(part)) return part.toUpperCase();
+      return part.toLowerCase();
+    }).join("-");
+  }
+}
+function maximizedLangScript(locale) {
+  try {
+    const max = new Intl.Locale(canonicalizeLocale(locale)).maximize();
+    return `${max.language}-${max.script ?? ""}`;
+  } catch {
+    return null;
+  }
+}
+
 // src/signal.ts
 function createSignal(initial) {
   let value = initial;
@@ -93,7 +118,7 @@ var LangsysAppAPIClass = class {
     return await this.get("authorize-project/[projectid]");
   }
   async getTranslations(locale) {
-    return await this.get("translations", { project_id: this.config.projectid, locale });
+    return await this.get("translations", { project_id: this.config.projectid, locale: canonicalizeLocale(locale) });
   }
   /**
    * Register phrases and/or content blocks via the current unified endpoint.
@@ -239,24 +264,37 @@ var config = {
 function isICU(template) {
   return ICU_PATTERN.test(template);
 }
-var ICU_PATTERN = /\{[^{}]+,\s*(plural|select|selectordinal|number|date|time)\s*,/;
+var ICU_PATTERN = /\{[^{}]+,\s*(plural|select|selectordinal|number|date|time)\s*[,}]/;
 function interpolate(template, params, locale) {
   if (isICU(template)) {
     try {
-      return new intlMessageformat.IntlMessageFormat(template, locale ?? "en").format(params);
+      return new intlMessageformat.IntlMessageFormat(template, locale || "en").format(params);
     } catch {
-      return simpleInterpolate(template, params);
+      return simpleInterpolate(template, params, locale);
     }
   }
-  return simpleInterpolate(template, params);
+  return simpleInterpolate(template, params, locale);
 }
-function simpleInterpolate(template, params) {
+function simpleInterpolate(template, params, locale) {
   return template.replace(/\{([^{},]+)\}/g, (match, rawKey) => {
     const key = rawKey.trim();
     if (!(key in params)) return match;
     const value = params[key];
     if (value === void 0 || value === null) return match;
-    if (value instanceof Date) return value.toISOString();
+    if (value instanceof Date) {
+      try {
+        return new Intl.DateTimeFormat(locale || "en", { dateStyle: "medium" }).format(value);
+      } catch {
+        return value.toISOString();
+      }
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      try {
+        return new Intl.NumberFormat(locale || "en").format(value);
+      } catch {
+        return String(value);
+      }
+    }
     return String(value);
   });
 }
@@ -282,7 +320,7 @@ var Translations = class {
     });
     this.config = config2;
     this.debug = new Logger(!!config2.debug);
-    this.locale = config2.baseLocale || "";
+    this.locale = canonicalizeLocale(config2.baseLocale || "");
     this.tSignal = createSignal(this.buildTFn());
     sTranslations.subscribe(() => this.tSignal.set(this.buildTFn()));
     currentlyLoadedLocale.subscribe(() => this.tSignal.set(this.buildTFn()));
@@ -423,7 +461,7 @@ var Translations = class {
     this.config = config2;
     if (!this.config.projectid || !this.config.key) return;
     if (this.config.debug) this.debug.debugEnabled = this.config.debug;
-    if (config2.baseLocale) this.locale = config2.baseLocale;
+    if (config2.baseLocale) this.locale = canonicalizeLocale(config2.baseLocale);
     this.debug.log("TRANSLATION SETUP INITIATED", this.config);
     if (typeof window !== "undefined") {
       if (this.isFirstClientRun && this.missingTokens.length > 0) {
@@ -451,8 +489,10 @@ var Translations = class {
    */
   markLoaded(locale) {
     if (!locale) return;
+    locale = canonicalizeLocale(locale);
     this.locale = locale;
     this.lastLoaded[locale] = (/* @__PURE__ */ new Date()).getTime() / 1e3;
+    this.readyResolve();
   }
   /**
    * React to a user-locale change. Fetches translations if we haven't
@@ -461,10 +501,12 @@ var Translations = class {
   async change(locale, force = false, skipFetch = false) {
     if (!locale) return false;
     if (!this.config.projectid || !this.config.key) return false;
+    locale = canonicalizeLocale(locale);
     if (skipFetch) {
       this.debug.log("Using pre-fetched translations for locale", locale);
       this.locale = locale;
       this.lastLoaded[locale] = (/* @__PURE__ */ new Date()).getTime() / 1e3;
+      this.readyResolve();
       return true;
     }
     const now = (/* @__PURE__ */ new Date()).getTime() / 1e3;
@@ -628,11 +670,11 @@ var LangsysAppClass = class {
     }
     if (!UserLocaleStore?.subscribe || typeof UserLocaleStore.get !== "function") {
       this.debug.error(
-        "LangsysApp.init missing UserLocaleStore \u2014 pass any object satisfying LocaleSource (get + subscribe). createSignal('en-us') works if you have nothing of your own."
+        "LangsysApp.init missing UserLocaleStore \u2014 pass any object satisfying LocaleSource (get + subscribe). createSignal('en-US') works if you have nothing of your own."
       );
       return { status: false, errors: ["Missing UserLocaleStore"] };
     }
-    baseLocale = baseLocale.toLowerCase();
+    baseLocale = canonicalizeLocale(baseLocale);
     if (!emulateFailureToLoad) {
       this.config = {
         projectid,
@@ -671,8 +713,9 @@ var LangsysAppClass = class {
     if (initialTranslations2 && initialTranslationsLocale) {
       this.Translations.markLoaded(initialTranslationsLocale);
     }
-    this.config.sUserLocale.subscribe((locale) => {
+    this.config.sUserLocale.subscribe((rawLocale) => {
       if (!validateResponse.status) return;
+      const locale = canonicalizeLocale(rawLocale);
       this.getLocalesData(locale);
       this.debug.log("SUBSCRIBING TO USER LOCALE STORE");
       this.translationsLoadingPromise = this.Translations.change(locale, false);
@@ -680,7 +723,7 @@ var LangsysAppClass = class {
     return validateResponse;
   }
   async getDialCodes(inLocale) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (this.dialCodes.length && this.dialCodesLocale === locale) return this.dialCodes;
     const route = `countries/dial-codes/${locale}`;
     const response = await LangsysAppAPI.get(route);
@@ -693,7 +736,7 @@ var LangsysAppClass = class {
     return this.dialCodes;
   }
   async getCurrencies(inLocale) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (this.currencies.length && this.currenciesLocale === locale) return this.currencies;
     const route = `currencies/${locale}`;
     const response = await LangsysAppAPI.get(route);
@@ -706,7 +749,7 @@ var LangsysAppClass = class {
     return this.currencies;
   }
   async getCountries(inLocale) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (this.countries.length && this.countriesLocale === locale) return this.countries;
     const route = `countries/${locale}`;
     const response = await LangsysAppAPI.get(route);
@@ -720,7 +763,7 @@ var LangsysAppClass = class {
   }
   async getCountryName(forCountryCode, inLocale) {
     if (!forCountryCode) return "";
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (!this.countries.length || this.countriesLocale !== locale) await this.getCountries(inLocale);
     const country = this.countries.find((c) => c.code.toLowerCase() === forCountryCode.toLowerCase())?.label;
     if (!country) this.debug.warn("getCountryName failed to match", forCountryCode);
@@ -728,14 +771,14 @@ var LangsysAppClass = class {
   }
   async getCurrencyName(forCurrencyCode, inLocale) {
     if (!forCurrencyCode) return "";
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (!this.currencies.length || this.currenciesLocale !== locale) await this.getCurrencies(inLocale);
     const currency = this.currencies.find((c) => c.code?.toLowerCase() === forCurrencyCode.toLowerCase())?.name;
     if (!currency) this.debug.warn("getCurrencyName failed to match", forCurrencyCode);
     return currency || forCurrencyCode;
   }
   async getLocalesFormat(format = "", inLocale) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     const route = `locales/${locale}` + (format ? `/${format}` : "");
     const response = await LangsysAppAPI.get(route);
     if (response.errors || !response.status) {
@@ -756,7 +799,7 @@ var LangsysAppClass = class {
     return await this.getLocalesFormat("flat", inLocale);
   }
   async getLocalesData(inLocale, forceRefresh = false) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     if (this.locales?.[locale]?.length && !forceRefresh) return this.locales[locale];
     this.locales[locale] = await this.getLocalesFormat("data", inLocale);
     return this.locales[locale];
@@ -766,15 +809,16 @@ var LangsysAppClass = class {
   }
   async getLocaleNameWithLookup(forLocale, shortName = false, inLocale) {
     if (!forLocale) return "";
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
     await this.getLocalesData(locale);
     return this.getLocaleName(forLocale, shortName, locale);
   }
   getLocaleName(forLocale, shortName = false, inLocale) {
-    const locale = inLocale || this.config.sUserLocale.get() || this.config.baseLocale;
+    const locale = this.resolveLocale(inLocale);
+    const target = canonicalizeLocale(forLocale).toLowerCase();
     let name = "";
     this.locales[locale]?.every((loc) => {
-      if (loc.code === forLocale) {
+      if (loc.code.toLowerCase() === target) {
         name = shortName ? loc.lang_name : loc.locale_name;
         return false;
       }
@@ -800,7 +844,7 @@ var LangsysAppClass = class {
       const bestMatch = this.findBestLocaleMatch(userLocales, supportedLocales);
       if (bestMatch) return bestMatch;
     }
-    return this.normalizeLocale(userLocales[0]);
+    return canonicalizeLocale(userLocales[0]);
   }
   getUserLanguagePreferences(acceptLanguageHeader) {
     if (acceptLanguageHeader) {
@@ -837,30 +881,26 @@ var LangsysAppClass = class {
   }
   findBestLocaleMatch(userLocales, supportedLocales) {
     if (!userLocales.length || !supportedLocales.length) return null;
-    const normalizedSupported = supportedLocales.map((l) => this.normalizeLocale(l));
+    const supported = supportedLocales.map((l) => canonicalizeLocale(l));
     for (const userLocale of userLocales) {
-      const normalizedUser = this.normalizeLocale(userLocale);
-      if (normalizedSupported.includes(normalizedUser)) return normalizedUser;
+      const user = canonicalizeLocale(userLocale);
+      if (supported.includes(user)) return user;
     }
     for (const userLocale of userLocales) {
-      const userLang = this.getLanguageCode(userLocale);
-      for (const supported of normalizedSupported) {
-        if (this.getLanguageCode(supported) === userLang) return supported;
-      }
+      const userKey = maximizedLangScript(userLocale);
+      if (!userKey) continue;
+      const match = supported.find((s) => maximizedLangScript(s) === userKey);
+      if (match) return match;
     }
     return null;
   }
-  normalizeLocale(locale) {
-    if (!locale || typeof locale !== "string") return locale;
-    const parts = locale.split(/[-_]/);
-    if (parts.length === 1) return parts[0].toLowerCase();
-    const language = parts[0].toLowerCase();
-    const region = parts[1].toUpperCase();
-    return `${language}-${region}`;
-  }
-  getLanguageCode(locale) {
-    if (!locale || typeof locale !== "string") return "";
-    return locale.split(/[-_]/)[0].toLowerCase();
+  /**
+   * 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.
+   */
+  resolveLocale(inLocale) {
+    return canonicalizeLocale(inLocale || this.config.sUserLocale.get() || this.config.baseLocale);
   }
 };
 var LangsysApp = new LangsysAppClass();
@@ -1493,6 +1533,7 @@ exports.PHRASE_MARKER_ATTR = PHRASE_MARKER_ATTR;
 exports.Phrase = Phrase;
 exports.Translate = Translate;
 exports.Translations = Translations;
+exports.canonicalizeLocale = canonicalizeLocale;
 exports.createSignal = createSignal;
 exports.currentlyLoadedLocale = currentlyLoadedLocale;
 exports.encodeRichText = encodeRichText;