@sonenta/react-i18next 2.1.0 → 2.2.0

package/README.md

@@ -497,6 +497,49 @@ Plurals work the same in overlays (single key + CLDR plural forms); an overlay
 plural set fully replaces the base key's. Surface overlays are served from the
 CDN; `env: "dev"` is base-only for now.
 
+## Accessibility surfaces
+
+A11y variants attach SEMANTIC accessibility text to a key — `aria_label`,
+`alt_text`, `screen_reader`, `plain_language` — delivered through the same
+sparse-overlay engine as device surfaces, but applied **orthogonally** to the
+visible text (an element has both its visible label AND an accessible name).
+Opt in per surface; they load alongside the base bundles.
+
+```tsx
+<SonentaProvider {...config} a11ySurfaces={["aria_label", "alt_text"]}>
+  <App />
+</SonentaProvider>
+
+function SaveButton() {
+  const { t } = useTranslation("common");
+  return (
+    <button aria-label={t.aria("save")}>{t("save")}</button>
+  );
+  // t("save")      → visible text  ("Save")
+  // t.aria("save") → aria_label overlay, or the visible text if no override
+}
+
+function Hero() {
+  const { i18n } = useTranslation();
+  return <img src={i18n.a11yAsset("hero")?.ref} alt={i18n.alt("hero")} />;
+}
+```
+
+- `t.aria(key)` / `t.alt(key)` — overlay value, **falling back to the visible
+  text** when no a11y override exists. Also on the instance: `i18n.aria()` /
+  `i18n.alt()`.
+- `t.a11y(key, surface)` / `i18n.a11y(key, surface)` — the raw resolver:
+  returns `undefined` when there's no override (use for `screen_reader` /
+  `plain_language`, which should be **omitted** rather than fall back).
+- `i18n.a11yAsset(key)` — the `alt_text` overlay's localized-image `$asset`.
+- **Plain language (cognitive) toggle:** include `plain_language` (or pass
+  `plainLanguage`) and call `i18n.setPlainLanguage(true)` — `t()` then returns
+  the `plain_language` overlay for keys that have one (else the base text).
+
+Resolution is locale-outer / surface-inner (same chain as `t()`): `(fr-CA,
+aria_label) > (fr-CA, base) > (fr, aria_label) > (fr, base)`. Overlays are
+CDN-only (`env: "dev"` is base-only).
+
 ## Recipes
 
 ### Next.js (App Router)

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  A11Y_SURFACES: () => A11Y_SURFACES,
   DEFAULT_SURFACE_BREAKPOINTS: () => DEFAULT_SURFACE_BREAKPOINTS,
   SonentaProvider: () => SonentaProvider,
   Trans: () => Trans,
@@ -236,7 +237,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.2.0" : "0.0.0-dev";
 function defaultTransport(opts) {
   return async (batch) => {
     if (!batch.length) return;
@@ -442,6 +443,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
@@ -469,6 +478,9 @@ var SonentaI18n = class {
     this.locale = 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;
@@ -653,6 +665,12 @@ 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,
@@ -894,9 +912,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;
@@ -1047,6 +1152,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
@@ -1174,6 +1340,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
@@ -1257,7 +1429,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]);
   (0, import_react2.useEffect)(() => {
     keyRegistry._set(tokenRef.current, renderedRef.current);
@@ -1310,6 +1487,7 @@ function splitOnComponents(text, components) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  A11Y_SURFACES,
   DEFAULT_SURFACE_BREAKPOINTS,
   SonentaProvider,
   Trans,