@sonenta/react-i18next 2.1.0 → 2.3.0

package/dist/index.js

@@ -210,7 +210,7 @@ function flattenPlurals(tree, locale) {
 
 // src/transport.ts
 var SDK_LIB = "@sonenta/react-i18next";
-var SDK_VER = true ? "2.1.0" : "0.0.0-dev";
+var SDK_VER = true ? "2.3.0" : "0.0.0-dev";
 function defaultTransport(opts) {
   return async (batch) => {
     if (!batch.length) return;
@@ -402,6 +402,14 @@ var SonentaI18n = class {
   // config.languageCatalog and/or the public GET /v1/languages in start().
   _catalog = new LanguageCatalog();
   _catalogDisabled = false;
+  // Published-languages manifest (available-languages feature). Per-version,
+  // public CDN, no auth: the SET of locales published for the active version.
+  // Codes are enriched from `_catalog` (#803) for native_name/rtl/etc.
+  _manifestDisabled = false;
+  _manifest = null;
+  // The configured default locale (the initial `this.locale`, which is mutable
+  // via setLocale) — used as the available-languages fallback + default marker.
+  _defaultLocale;
   _config;
   // Surface variant (#911). When set, each loaded (locale,ns) is composed as
   // base ⊕ sparse `{ns}.{surface}.json` overlay (overlay wins per key). We
@@ -416,6 +424,14 @@ var SonentaI18n = class {
   // Resolved asset refs (#911 minimal v1), keyed `${locale}/${ns}/${keyPath}`
   // for the CURRENT composition (base assets, then overlay assets override).
   _assets = /* @__PURE__ */ new Map();
+  // A11y surfaces (#989 / task 994). Each configured a11y surface S is loaded
+  // as its OWN i18next namespace `${ns}__${S}` (sparse `{ns}.{S}.json`), so the
+  // accessors resolve through i18next's native locale-fallback + nested-key
+  // logic without touching the visible-text bundle. `_a11yAssets` carries the
+  // `alt_text` `$asset` refs, keyed `${locale}/${ns}/${keyPath}#${surface}`.
+  _a11ySurfaces = /* @__PURE__ */ new Set();
+  _plainLanguage = false;
+  _a11yAssets = /* @__PURE__ */ new Map();
   _missing;
   _listeners = /* @__PURE__ */ new Set();
   // Stable snapshot reference for useSyncExternalStore. Rebuilt ONLY in _notify
@@ -441,8 +457,12 @@ var SonentaI18n = class {
       );
     }
     this.locale = config.defaultLocale;
+    this._defaultLocale = config.defaultLocale;
     this.fallbackLng = config.fallbackLng;
     this._surface = config.surface;
+    for (const s of config.a11ySurfaces ?? []) this._a11ySurfaces.add(s);
+    this._plainLanguage = config.plainLanguage === true;
+    if (this._plainLanguage) this._a11ySurfaces.add("plain_language");
     let keySeparator = ".";
     if (config.keySeparator !== void 0) {
       keySeparator = config.keySeparator;
@@ -540,6 +560,7 @@ var SonentaI18n = class {
     this._rebindFormat();
     this._catalogDisabled = config.disableLanguageCatalog === true;
     this._catalog.merge(config.languageCatalog);
+    this._manifestDisabled = config.disableLanguageManifest === true;
     const active = config.initialBundles?.[this.locale];
     if (active && this._config.namespaces.every(
       (n) => active[n] && Object.keys(active[n]).length > 0
@@ -627,9 +648,16 @@ var SonentaI18n = class {
       surface: this._surface,
       setSurface: this.setSurface,
       asset: this.asset,
+      aria: this.aria,
+      alt: this.alt,
+      a11y: this.a11y,
+      a11yAsset: this.a11yAsset,
+      plainLanguage: this._plainLanguage,
+      setPlainLanguage: this.setPlainLanguage,
       dir: this.dir,
       nativeName: this.nativeName,
       languageMeta: this.languageMeta,
+      availableLanguages: this.availableLanguages,
       i18next: this._i18next
     };
   }
@@ -691,7 +719,9 @@ var SonentaI18n = class {
       // Best-effort: align the key separator with the version's key_style (#754).
       this._loadKeyStyle(fetchImpl),
       // Best-effort: load the public language catalog for dir()/nativeName().
-      this._loadCatalog(fetchImpl)
+      this._loadCatalog(fetchImpl),
+      // Best-effort: load the per-version published-languages manifest.
+      this._loadManifest(fetchImpl)
     ]);
     await this._syncLanguage();
     this.ready = true;
@@ -715,6 +745,71 @@ var SonentaI18n = class {
   }
   /** Best-effort: fetch the PUBLIC language catalog and merge it in (#803).
    *  Skipped when disabled; a failure keeps any embedded catalog. */
+  /**
+   * Best-effort: fetch the per-version published-languages manifest
+   * (`{cdnBase}/p/{project}/{version}/latest/languages.json`, public, no auth,
+   * CDN-cached) — the SET of locales published for the active version. Codes
+   * only; enriched from the catalog. A 404/offline keeps any prior manifest
+   * (`availableLanguages` then falls back to default + fallback). CDN-only:
+   * `env: "dev"` skips it (the dev runtime has no manifest yet).
+   */
+  async _loadManifest(fetchImpl, opts = {}) {
+    if (this._manifestDisabled) return;
+    if (this._config.env === "dev") return;
+    const url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.version}/latest/languages.json`;
+    const init = { method: "GET", credentials: "omit" };
+    if (opts.bust) init.cache = "reload";
+    try {
+      const r = await fetchImpl(url, init);
+      if (!r.ok) return;
+      const data = await r.json();
+      const raw = Array.isArray(data.languages) ? data.languages : [];
+      const languages = [];
+      for (const e of raw) {
+        if (typeof e === "string") {
+          languages.push({ code: e });
+        } else if (e && typeof e === "object" && typeof e.code === "string") {
+          const obj = e;
+          languages.push({
+            code: obj.code,
+            published_at: typeof obj.published_at === "string" ? obj.published_at : void 0
+          });
+        }
+      }
+      this._manifest = {
+        default_locale: typeof data.default_locale === "string" ? data.default_locale : void 0,
+        languages
+      };
+    } catch {
+    }
+  }
+  /** Languages PUBLISHED for the active version (available-languages feature):
+   *  the manifest's codes enriched with catalog metadata, marked with the
+   *  default locale + any `published_at`. Falls back to the configured
+   *  `defaultLocale` + `fallbackLng` when no manifest is available. */
+  get availableLanguages() {
+    const def = this._manifest?.default_locale ?? this._defaultLocale;
+    let entries = this._manifest?.languages;
+    if (!entries || entries.length === 0) {
+      const seen = /* @__PURE__ */ new Set();
+      entries = [];
+      for (const c of [this._defaultLocale, ...asArray(this.fallbackLng)]) {
+        if (c && !seen.has(c)) {
+          seen.add(c);
+          entries.push({ code: c });
+        }
+      }
+    }
+    return entries.map(({ code, published_at }) => {
+      const meta = this.languageMeta(code);
+      return {
+        ...meta ?? {},
+        code,
+        ...published_at ? { published_at } : {},
+        is_default: code === def
+      };
+    });
+  }
   async _loadCatalog(fetchImpl) {
     if (this._catalogDisabled) return;
     this._catalog.merge(await loadCatalog(this._config.apiBase, fetchImpl));
@@ -805,12 +900,14 @@ var SonentaI18n = class {
       if (opts.namespace && opts.namespace !== ns) continue;
       targets.push({ locale, ns });
     }
-    if (targets.length === 0) return;
-    await Promise.all(
-      targets.map(
+    if (targets.length === 0 && (opts.locale || opts.namespace)) return;
+    const manifest = this._loadManifest(fetch, { bust: true });
+    await Promise.all([
+      manifest,
+      ...targets.map(
         (t2) => this._loadBundle(t2.locale, t2.ns, fetch, { bust: true })
       )
-    );
+    ]);
     this._notify();
   };
   /**
@@ -868,9 +965,96 @@ var SonentaI18n = class {
     }
     return void 0;
   };
+  // ---- A11y (#989 / task 994) ----
+  /** Split a possibly-`ns:key` string into `{ ns, bareKey }`, honoring the
+   *  configured nsSeparator (mirrors {@link asset}). */
+  _splitKey(key, namespace) {
+    let ns = namespace ?? this.defaultNamespace;
+    let bareKey = key;
+    if (typeof this._nsSeparator === "string" && this._nsSeparator) {
+      const idx = key.indexOf(this._nsSeparator);
+      if (idx > 0) {
+        ns = key.slice(0, idx);
+        bareKey = key.slice(idx + this._nsSeparator.length);
+      }
+    }
+    return { ns, bareKey };
+  }
+  /** Resolve an a11y `surface` override for `key`, or `undefined` when none
+   *  exists (the namespace is sparse). Goes through i18next so the locale
+   *  fallback chain + nested keys + plurals apply. */
+  a11y = (key, surface, namespace) => {
+    if (!this._a11ySurfaces.has(surface)) return void 0;
+    const { ns, bareKey } = this._splitKey(key, namespace);
+    const a11yNs = this._a11yNs(ns, surface);
+    if (!this._i18next.exists(bareKey, { ns: a11yNs })) return void 0;
+    return this._i18next.t(bareKey, { ns: a11yNs });
+  };
+  /** Accessible name for `key` (`aria_label` overlay) — falls back to the
+   *  visible `t(key)` text when no override exists. Spread as `aria-label`. */
+  aria = (key, namespace) => {
+    const v = this.a11y(key, "aria_label", namespace);
+    if (v !== void 0) return v;
+    const { ns, bareKey } = this._splitKey(key, namespace);
+    return this._i18next.t(bareKey, { ns });
+  };
+  /** Image alt text for `key` (`alt_text` overlay) — falls back to the visible
+   *  `t(key)` text. Pair with {@link a11yAsset} for a localized image. */
+  alt = (key, namespace) => {
+    const v = this.a11y(key, "alt_text", namespace);
+    if (v !== void 0) return v;
+    const { ns, bareKey } = this._splitKey(key, namespace);
+    return this._i18next.t(bareKey, { ns });
+  };
+  /** Localized-image `$asset` ref from a key's `alt_text` overlay, or
+   *  `undefined`. Walks the locale fallback chain like `t()` would. */
+  a11yAsset = (key, namespace) => {
+    const { ns, bareKey } = this._splitKey(key, namespace);
+    for (const loc of this._resolutionChain(this.locale)) {
+      const ref = this._a11yAssets.get(`${loc}/${ns}/${bareKey}#alt_text`);
+      if (ref) return ref;
+    }
+    return void 0;
+  };
+  get plainLanguage() {
+    return this._plainLanguage;
+  }
+  /** Toggle simplified-language ("plain language" / FALC) mode (#989). When
+   *  on, `t()` returns the `plain_language` overlay value for keys that have
+   *  one. Loads the `plain_language` overlays on first enable if they were not
+   *  configured, then re-renders. No-op when unchanged. */
+  setPlainLanguage = async (on) => {
+    if (on === this._plainLanguage) return;
+    this._plainLanguage = on;
+    if (on && !this._a11ySurfaces.has("plain_language")) {
+      this._a11ySurfaces.add("plain_language");
+      const targets = [];
+      for (const k of this._attempted) {
+        const parts = k.split("/");
+        const locale = parts[1];
+        const ns = parts[2];
+        if (locale && ns) targets.push({ locale, ns });
+      }
+      await Promise.all(
+        targets.map((t2) => this._loadA11yOverlays(t2.locale, t2.ns))
+      );
+    }
+    this._notify();
+    this._signalLoaded();
+  };
   // ---- Translation ----
   t = (key, optionsOrDefault, maybeOptions) => {
     const options = typeof optionsOrDefault === "string" ? { ...maybeOptions ?? {}, defaultValue: optionsOrDefault } : optionsOrDefault;
+    if (this._plainLanguage && this._a11ySurfaces.has("plain_language")) {
+      const { ns, bareKey } = this._splitKey(key);
+      const plainNs = this._a11yNs(ns, "plain_language");
+      if (this._i18next.exists(bareKey, { ...options ?? {}, ns: plainNs })) {
+        return this._i18next.t(bareKey, {
+          ...options ?? {},
+          ns: plainNs
+        });
+      }
+    }
     const literal = this._probeLiteral(key);
     if (literal !== void 0) {
       const interpolator = this._i18next.services?.interpolator;
@@ -1021,6 +1205,67 @@ var SonentaI18n = class {
       this._attempted.add(cacheKey);
     }
     await this._composeBundle(locale, ns, fetchImpl, opts.bust);
+    await this._loadA11yOverlays(locale, ns, fetchImpl, opts.bust);
+  }
+  /**
+   * Load every configured a11y surface overlay (#989 / task 994) for
+   * (locale, ns) into a DEDICATED i18next namespace `${ns}__${surface}`, so
+   * `aria()` / `alt()` / `a11y()` resolve them through i18next (locale
+   * fallback + nested keys + plurals) WITHOUT polluting the visible-text
+   * bundle. Sparse + best-effort: an absent overlay registers `{}` and the
+   * accessor reports "no override".
+   */
+  async _loadA11yOverlays(locale, ns, fetchImpl = fetch, bust = false) {
+    if (this._a11ySurfaces.size === 0) return;
+    await Promise.all(
+      [...this._a11ySurfaces].map(async (surface) => {
+        const overlay = await this._loadOverlay(
+          locale,
+          ns,
+          surface,
+          fetchImpl,
+          bust
+        );
+        const tree = this._unwrapA11y(overlay, locale, ns, surface);
+        this._i18next.addResourceBundle(
+          locale,
+          this._a11yNs(ns, surface),
+          flattenPlurals(tree, locale),
+          false,
+          true
+        );
+      })
+    );
+  }
+  /** i18next namespace that backs an a11y surface overlay for `ns`. */
+  _a11yNs(ns, surface) {
+    return `${ns}__${surface}`;
+  }
+  /** Like {@link _unwrapAssets} but records `$asset` refs into `_a11yAssets`
+   *  (keyed with the `#${surface}` suffix) instead of the visible-text
+   *  `_assets`, so `alt_text` images don't collide with device-surface assets. */
+  _unwrapA11y(tree, locale, ns, surface) {
+    const sep = typeof this._i18next.options.keySeparator === "string" ? this._i18next.options.keySeparator : ".";
+    const walk = (node, path) => {
+      if (!node || typeof node !== "object") return node;
+      const obj = node;
+      if (Object.prototype.hasOwnProperty.call(obj, "$value")) {
+        const a = obj.$asset;
+        if (a && typeof a.kind === "string" && typeof a.ref === "string") {
+          this._a11yAssets.set(
+            `${locale}/${ns}/${path.join(sep)}#${surface}`,
+            { kind: a.kind, ref: a.ref }
+          );
+        }
+        return obj.$value;
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = walk(v, [...path, k]);
+      }
+      return out;
+    };
+    return walk(tree, []);
   }
   /**
    * Compose the i18next bundle for (locale, ns) as base ⊕ surface overlay
@@ -1148,6 +1393,12 @@ function t(key, optionsOrDefault, maybeOptions) {
 }
 
 // src/surface.ts
+var A11Y_SURFACES = [
+  "aria_label",
+  "alt_text",
+  "screen_reader",
+  "plain_language"
+];
 var DEFAULT_SURFACE_BREAKPOINTS = {
   mobile: 640,
   tablet: 1024
@@ -1231,7 +1482,12 @@ function useTranslation(defaultNamespace) {
       );
       return i18n.t(fullKey, optionsOrDefault, maybeOptions);
     };
-    return fn;
+    const withNs = (key) => defaultNamespace && !key.includes(":") ? `${defaultNamespace}:${key}` : key;
+    const aug = fn;
+    aug.aria = (key, namespace) => i18n.aria(withNs(key), namespace);
+    aug.alt = (key, namespace) => i18n.alt(withNs(key), namespace);
+    aug.a11y = (key, surface, namespace) => i18n.a11y(withNs(key), surface, namespace);
+    return aug;
   }, [i18n, defaultNamespace]);
   useEffect2(() => {
     keyRegistry._set(tokenRef.current, renderedRef.current);
@@ -1242,6 +1498,9 @@ function useTranslation(defaultNamespace) {
   }, []);
   return { t: t2, i18n: snapshot };
 }
+function useAvailableLanguages() {
+  return useI18nSnapshot().availableLanguages;
+}
 
 // src/trans.tsx
 import { Children, cloneElement, isValidElement } from "react";
@@ -1283,6 +1542,7 @@ function splitOnComponents(text, components) {
   return out;
 }
 export {
+  A11Y_SURFACES,
   DEFAULT_SURFACE_BREAKPOINTS,
   SonentaProvider,
   Trans,
@@ -1294,6 +1554,7 @@ export {
   logTransport,
   surfaceForWidth,
   t,
+  useAvailableLanguages,
   useTranslation
 };
 //# sourceMappingURL=index.js.map