@sonenta/react-i18next 2.1.0 → 2.3.0

package/README.md

@@ -497,6 +497,84 @@ 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).
+
+## Available languages (runtime switcher)
+
+List the languages **published for the active version** at runtime — so adding
+a language in Sonenta makes it appear in your switcher **without recompiling
+the app**. The set comes from a per-version CDN manifest (public, cacheable,
+no auth); each code is enriched from the language catalog (`native_name`,
+`rtl`, …).
+
+```tsx
+import { useTranslation, useAvailableLanguages } from "@sonenta/react-i18next";
+
+function LanguageSwitcher() {
+  const { i18n } = useTranslation();
+  const languages = useAvailableLanguages(); // [{ code, native_name, rtl, is_default, published_at? }]
+  return (
+    <select value={i18n.language} onChange={(e) => i18n.setLocale(e.target.value)}>
+      {languages.map((l) => (
+        <option key={l.code} value={l.code}>
+          {l.native_name ?? l.code}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+- A newly-published language appears on the **next load** (the manifest is
+  CDN-served), or immediately after `i18n.reload()` — no rebuild, no redeploy
+  of your app.
+- `is_default` marks the project's default locale; `published_at` (when the
+  manifest provides it) lets you flag recently-added languages.
+- Falls back to `defaultLocale` + `fallbackLng` when no manifest is available
+  (or `env: "dev"`, which is CDN-only). Opt out with `disableLanguageManifest`.
+- Also imperative: `i18n.availableLanguages`.
+
 ## 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,
@@ -31,6 +32,7 @@ __export(index_exports, {
   logTransport: () => logTransport,
   surfaceForWidth: () => surfaceForWidth,
   t: () => t,
+  useAvailableLanguages: () => useAvailableLanguages,
   useTranslation: () => useTranslation
 });
 module.exports = __toCommonJS(index_exports);
@@ -236,7 +238,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;
@@ -428,6 +430,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
@@ -442,6 +452,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
@@ -467,8 +485,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;
@@ -566,6 +588,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
@@ -653,9 +676,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
     };
   }
@@ -717,7 +747,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;
@@ -741,6 +773,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));
@@ -831,12 +928,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();
   };
   /**
@@ -894,9 +993,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 +1233,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 +1421,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 +1510,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);
@@ -1268,6 +1526,9 @@ function useTranslation(defaultNamespace) {
   }, []);
   return { t: t2, i18n: snapshot };
 }
+function useAvailableLanguages() {
+  return useI18nSnapshot().availableLanguages;
+}
 
 // src/trans.tsx
 var import_react3 = require("react");
@@ -1310,6 +1571,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,
@@ -1321,6 +1583,7 @@ function splitOnComponents(text, components) {
   logTransport,
   surfaceForWidth,
   t,
+  useAvailableLanguages,
   useTranslation
 });
 //# sourceMappingURL=index.cjs.map