@sonenta/react-i18next 2.1.0 → 2.2.0

package/dist/index.d.cts

@@ -13,6 +13,24 @@ import { i18n } from 'i18next';
  * the reactive viewport listener (web) — see `provider.tsx`.
  */
 type Surface = "desktop" | "mobile" | "tablet";
+/**
+ * A11y surfaces (#989 / task 994) — SEMANTIC accessibility variants of a key,
+ * delivered through the SAME sparse-overlay engine as device surfaces but
+ * applied ORTHOGONALLY to the visible text:
+ *   - `aria_label`    → an element's `aria-label` attribute
+ *   - `alt_text`      → an `<img alt>` (+ optional localized image via `$asset`)
+ *   - `screen_reader` → verbose screen-reader-only (sr-only) text
+ *   - `plain_language`→ simplified/clear-language (FALC) alternative rendering
+ *
+ * Unlike a device {@link Surface} (which replaces the visible `t()` value),
+ * a11y surfaces are read per-key via `i18n.aria()` / `alt()` / `a11y()` —
+ * EXCEPT `plain_language`, which the cognitive `plainLanguage` toggle layers
+ * over the visible `t()` output when enabled.
+ */
+type A11ySurface = "aria_label" | "alt_text" | "screen_reader" | "plain_language";
+/** The fixed V1 a11y surface taxonomy (matches the backend `surfaceKinds`
+ *  `a11y` set). Used to validate config + drive eager overlay loading. */
+declare const A11Y_SURFACES: readonly A11ySurface[];
 /** Min-width (px) thresholds that map a viewport width to a surface. A width
  *  `< mobile` → `mobile`; `< tablet` → `tablet`; otherwise `desktop`. Mirrors
  *  the common mobile-first breakpoint ladder. */
@@ -227,6 +245,23 @@ interface SonentaConfig {
      * own `useWindowDimensions`. Ignored when `surface` is unset.
      */
     surfaceBreakpoints?: SurfaceBreakpoints | boolean;
+    /**
+     * A11y surfaces (#989 / task 994) to eagerly load alongside the base
+     * bundles, so `i18n.aria()` / `alt()` / `a11y()` resolve synchronously in
+     * render. Each is a sparse `{ns}.{surface}.json` overlay applied
+     * ORTHOGONALLY to the visible text (NOT a `t()` replacement). Omit to
+     * disable a11y resolution. Include `"plain_language"` to power the
+     * {@link SonentaConfig.plainLanguage} toggle.
+     */
+    a11ySurfaces?: A11ySurface[];
+    /**
+     * Start with the cognitive simplified-language ("plain language" / FALC)
+     * mode ON — when enabled, `t()` returns the `plain_language` overlay value
+     * for keys that have one (else the base text). Toggle at runtime via
+     * `i18n.setPlainLanguage(on)`. No effect unless `plain_language` is loaded
+     * (it is auto-included when this is `true`, or list it in `a11ySurfaces`).
+     */
+    plainLanguage?: boolean;
     /**
      * Deployment environment. Drives where the SDK fetches translations from:
      *
@@ -342,6 +377,43 @@ interface I18nInstance {
      * asset (e.g. an icon/image ref) for the host to render.
      */
     asset: (key: string, namespace?: Namespace) => AssetRef | undefined;
+    /**
+     * A11y (#989 / task 994) — the accessible NAME for a key (`aria_label`
+     * overlay), falling back to the visible `t(key)` text when no a11y override
+     * exists. Spread onto an element as `aria-label`. Requires `aria_label` in
+     * {@link SonentaConfig.a11ySurfaces}.
+     */
+    aria: (key: string, namespace?: Namespace) => string;
+    /**
+     * A11y — the image alternative text for a key (`alt_text` overlay), falling
+     * back to the visible `t(key)` text. Pair with {@link I18nInstance.a11yAsset}
+     * for a localized image. Requires `alt_text` in `a11ySurfaces`.
+     */
+    alt: (key: string, namespace?: Namespace) => string;
+    /**
+     * A11y — resolve an arbitrary a11y `surface` overlay for a key, or
+     * `undefined` when no override exists (use for `screen_reader` /
+     * `plain_language`, which should be OMITTED rather than fall back to the
+     * visible text). `aria` / `alt` are convenience wrappers that fall back.
+     */
+    a11y: (key: string, surface: A11ySurface, namespace?: Namespace) => string | undefined;
+    /**
+     * A11y — the localized-image `$asset` ref carried by a key's `alt_text`
+     * overlay, or `undefined`. Lets the host swap the IMAGE per locale, not just
+     * its alt text.
+     */
+    a11yAsset: (key: string, namespace?: Namespace) => AssetRef | undefined;
+    /**
+     * A11y — whether the cognitive simplified-language ("plain language") mode is
+     * ON. When `true`, `t()` returns the `plain_language` overlay value for keys
+     * that have one (else the base text).
+     */
+    plainLanguage: boolean;
+    /**
+     * A11y — toggle simplified-language mode and re-render. Loads the
+     * `plain_language` overlays on first enable if not already configured.
+     */
+    setPlainLanguage: (on: boolean) => Promise<void>;
     /**
      * Text direction of a locale (defaults to the active locale) — i18next
      * parity. Sourced from the language catalog's `rtl` (variant → base
@@ -383,6 +455,22 @@ interface TranslationFunction {
     /** Native form: `t('key', { defaultValue, ...interpolation })`. */
     (key: string, options?: TranslationOptions): string;
 }
+/**
+ * The `t` returned by {@link useTranslation} — a {@link TranslationFunction}
+ * augmented with a11y accessors (#989 / task 994) so a host can write
+ * `t.aria(key)` / `t.alt(key)` / `t.a11y(key, surface)` right next to `t(key)`.
+ * They honor the hook's `defaultNamespace` and delegate to the engine.
+ */
+interface A11yTranslationFunction extends TranslationFunction {
+    /** Accessible name for `key` (`aria_label`), falling back to the visible
+     *  text. Spread onto an element as `aria-label`. */
+    aria: (key: string, namespace?: Namespace) => string;
+    /** Image alt text for `key` (`alt_text`), falling back to the visible text. */
+    alt: (key: string, namespace?: Namespace) => string;
+    /** Resolve an arbitrary a11y `surface` overlay for `key`, or `undefined`
+     *  when no override exists (e.g. `screen_reader` / `plain_language`). */
+    a11y: (key: string, surface: A11ySurface, namespace?: Namespace) => string | undefined;
+}
 
 interface SonentaProviderProps extends SonentaConfig {
     children: ReactNode;
@@ -390,7 +478,7 @@ interface SonentaProviderProps extends SonentaConfig {
 declare function SonentaProvider({ children, ...config }: SonentaProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseTranslationResult {
-    t: TranslationFunction;
+    t: A11yTranslationFunction;
     i18n: I18nInstance;
 }
 /** React hook — returns `{ t, i18n }`. Optional `defaultNamespace` lets you
@@ -537,4 +625,4 @@ declare class KeyRegistry {
 /** Process-wide singleton — there is exactly one on-screen registry. */
 declare const keyRegistry: KeyRegistry;
 
-export { type AssetRef, DEFAULT_SURFACE_BREAKPOINTS, type DeclaredKey, type I18nInstance, type LanguageMeta, type Locale, type MissingHandlerMode, type MissingKeyEvent, type Namespace, type SonentaConfig, type SonentaPlugin, type SonentaPluginContext, SonentaProvider, type Surface, type SurfaceBreakpoints, Trans, type TranslationFunction, type TranslationOptions, type Transport, type SonentaConfig as VerbumiaConfig, type SonentaPlugin as VerbumiaPlugin, type SonentaPluginContext as VerbumiaPluginContext, SonentaProvider as VerbumiaProvider, defaultTransport, getI18n, getI18nSafe, keyRegistry, logTransport, surfaceForWidth, t, useTranslation };
+export { A11Y_SURFACES, type A11ySurface, type AssetRef, DEFAULT_SURFACE_BREAKPOINTS, type DeclaredKey, type I18nInstance, type LanguageMeta, type Locale, type MissingHandlerMode, type MissingKeyEvent, type Namespace, type SonentaConfig, type SonentaPlugin, type SonentaPluginContext, SonentaProvider, type Surface, type SurfaceBreakpoints, Trans, type TranslationFunction, type TranslationOptions, type Transport, type SonentaConfig as VerbumiaConfig, type SonentaPlugin as VerbumiaPlugin, type SonentaPluginContext as VerbumiaPluginContext, SonentaProvider as VerbumiaProvider, defaultTransport, getI18n, getI18nSafe, keyRegistry, logTransport, surfaceForWidth, t, useTranslation };

package/dist/index.d.ts

@@ -13,6 +13,24 @@ import { i18n } from 'i18next';
  * the reactive viewport listener (web) — see `provider.tsx`.
  */
 type Surface = "desktop" | "mobile" | "tablet";
+/**
+ * A11y surfaces (#989 / task 994) — SEMANTIC accessibility variants of a key,
+ * delivered through the SAME sparse-overlay engine as device surfaces but
+ * applied ORTHOGONALLY to the visible text:
+ *   - `aria_label`    → an element's `aria-label` attribute
+ *   - `alt_text`      → an `<img alt>` (+ optional localized image via `$asset`)
+ *   - `screen_reader` → verbose screen-reader-only (sr-only) text
+ *   - `plain_language`→ simplified/clear-language (FALC) alternative rendering
+ *
+ * Unlike a device {@link Surface} (which replaces the visible `t()` value),
+ * a11y surfaces are read per-key via `i18n.aria()` / `alt()` / `a11y()` —
+ * EXCEPT `plain_language`, which the cognitive `plainLanguage` toggle layers
+ * over the visible `t()` output when enabled.
+ */
+type A11ySurface = "aria_label" | "alt_text" | "screen_reader" | "plain_language";
+/** The fixed V1 a11y surface taxonomy (matches the backend `surfaceKinds`
+ *  `a11y` set). Used to validate config + drive eager overlay loading. */
+declare const A11Y_SURFACES: readonly A11ySurface[];
 /** Min-width (px) thresholds that map a viewport width to a surface. A width
  *  `< mobile` → `mobile`; `< tablet` → `tablet`; otherwise `desktop`. Mirrors
  *  the common mobile-first breakpoint ladder. */
@@ -227,6 +245,23 @@ interface SonentaConfig {
      * own `useWindowDimensions`. Ignored when `surface` is unset.
      */
     surfaceBreakpoints?: SurfaceBreakpoints | boolean;
+    /**
+     * A11y surfaces (#989 / task 994) to eagerly load alongside the base
+     * bundles, so `i18n.aria()` / `alt()` / `a11y()` resolve synchronously in
+     * render. Each is a sparse `{ns}.{surface}.json` overlay applied
+     * ORTHOGONALLY to the visible text (NOT a `t()` replacement). Omit to
+     * disable a11y resolution. Include `"plain_language"` to power the
+     * {@link SonentaConfig.plainLanguage} toggle.
+     */
+    a11ySurfaces?: A11ySurface[];
+    /**
+     * Start with the cognitive simplified-language ("plain language" / FALC)
+     * mode ON — when enabled, `t()` returns the `plain_language` overlay value
+     * for keys that have one (else the base text). Toggle at runtime via
+     * `i18n.setPlainLanguage(on)`. No effect unless `plain_language` is loaded
+     * (it is auto-included when this is `true`, or list it in `a11ySurfaces`).
+     */
+    plainLanguage?: boolean;
     /**
      * Deployment environment. Drives where the SDK fetches translations from:
      *
@@ -342,6 +377,43 @@ interface I18nInstance {
      * asset (e.g. an icon/image ref) for the host to render.
      */
     asset: (key: string, namespace?: Namespace) => AssetRef | undefined;
+    /**
+     * A11y (#989 / task 994) — the accessible NAME for a key (`aria_label`
+     * overlay), falling back to the visible `t(key)` text when no a11y override
+     * exists. Spread onto an element as `aria-label`. Requires `aria_label` in
+     * {@link SonentaConfig.a11ySurfaces}.
+     */
+    aria: (key: string, namespace?: Namespace) => string;
+    /**
+     * A11y — the image alternative text for a key (`alt_text` overlay), falling
+     * back to the visible `t(key)` text. Pair with {@link I18nInstance.a11yAsset}
+     * for a localized image. Requires `alt_text` in `a11ySurfaces`.
+     */
+    alt: (key: string, namespace?: Namespace) => string;
+    /**
+     * A11y — resolve an arbitrary a11y `surface` overlay for a key, or
+     * `undefined` when no override exists (use for `screen_reader` /
+     * `plain_language`, which should be OMITTED rather than fall back to the
+     * visible text). `aria` / `alt` are convenience wrappers that fall back.
+     */
+    a11y: (key: string, surface: A11ySurface, namespace?: Namespace) => string | undefined;
+    /**
+     * A11y — the localized-image `$asset` ref carried by a key's `alt_text`
+     * overlay, or `undefined`. Lets the host swap the IMAGE per locale, not just
+     * its alt text.
+     */
+    a11yAsset: (key: string, namespace?: Namespace) => AssetRef | undefined;
+    /**
+     * A11y — whether the cognitive simplified-language ("plain language") mode is
+     * ON. When `true`, `t()` returns the `plain_language` overlay value for keys
+     * that have one (else the base text).
+     */
+    plainLanguage: boolean;
+    /**
+     * A11y — toggle simplified-language mode and re-render. Loads the
+     * `plain_language` overlays on first enable if not already configured.
+     */
+    setPlainLanguage: (on: boolean) => Promise<void>;
     /**
      * Text direction of a locale (defaults to the active locale) — i18next
      * parity. Sourced from the language catalog's `rtl` (variant → base
@@ -383,6 +455,22 @@ interface TranslationFunction {
     /** Native form: `t('key', { defaultValue, ...interpolation })`. */
     (key: string, options?: TranslationOptions): string;
 }
+/**
+ * The `t` returned by {@link useTranslation} — a {@link TranslationFunction}
+ * augmented with a11y accessors (#989 / task 994) so a host can write
+ * `t.aria(key)` / `t.alt(key)` / `t.a11y(key, surface)` right next to `t(key)`.
+ * They honor the hook's `defaultNamespace` and delegate to the engine.
+ */
+interface A11yTranslationFunction extends TranslationFunction {
+    /** Accessible name for `key` (`aria_label`), falling back to the visible
+     *  text. Spread onto an element as `aria-label`. */
+    aria: (key: string, namespace?: Namespace) => string;
+    /** Image alt text for `key` (`alt_text`), falling back to the visible text. */
+    alt: (key: string, namespace?: Namespace) => string;
+    /** Resolve an arbitrary a11y `surface` overlay for `key`, or `undefined`
+     *  when no override exists (e.g. `screen_reader` / `plain_language`). */
+    a11y: (key: string, surface: A11ySurface, namespace?: Namespace) => string | undefined;
+}
 
 interface SonentaProviderProps extends SonentaConfig {
     children: ReactNode;
@@ -390,7 +478,7 @@ interface SonentaProviderProps extends SonentaConfig {
 declare function SonentaProvider({ children, ...config }: SonentaProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseTranslationResult {
-    t: TranslationFunction;
+    t: A11yTranslationFunction;
     i18n: I18nInstance;
 }
 /** React hook — returns `{ t, i18n }`. Optional `defaultNamespace` lets you
@@ -537,4 +625,4 @@ declare class KeyRegistry {
 /** Process-wide singleton — there is exactly one on-screen registry. */
 declare const keyRegistry: KeyRegistry;
 
-export { type AssetRef, DEFAULT_SURFACE_BREAKPOINTS, type DeclaredKey, type I18nInstance, type LanguageMeta, type Locale, type MissingHandlerMode, type MissingKeyEvent, type Namespace, type SonentaConfig, type SonentaPlugin, type SonentaPluginContext, SonentaProvider, type Surface, type SurfaceBreakpoints, Trans, type TranslationFunction, type TranslationOptions, type Transport, type SonentaConfig as VerbumiaConfig, type SonentaPlugin as VerbumiaPlugin, type SonentaPluginContext as VerbumiaPluginContext, SonentaProvider as VerbumiaProvider, defaultTransport, getI18n, getI18nSafe, keyRegistry, logTransport, surfaceForWidth, t, useTranslation };
+export { A11Y_SURFACES, type A11ySurface, type AssetRef, DEFAULT_SURFACE_BREAKPOINTS, type DeclaredKey, type I18nInstance, type LanguageMeta, type Locale, type MissingHandlerMode, type MissingKeyEvent, type Namespace, type SonentaConfig, type SonentaPlugin, type SonentaPluginContext, SonentaProvider, type Surface, type SurfaceBreakpoints, Trans, type TranslationFunction, type TranslationOptions, type Transport, type SonentaConfig as VerbumiaConfig, type SonentaPlugin as VerbumiaPlugin, type SonentaPluginContext as VerbumiaPluginContext, SonentaProvider as VerbumiaProvider, defaultTransport, getI18n, getI18nSafe, keyRegistry, logTransport, surfaceForWidth, t, useTranslation };

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.2.0" : "0.0.0-dev";
 function defaultTransport(opts) {
   return async (batch) => {
     if (!batch.length) return;
@@ -416,6 +416,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
@@ -443,6 +451,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;
@@ -627,6 +638,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,
@@ -868,9 +885,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 +1125,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 +1313,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 +1402,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);
@@ -1283,6 +1459,7 @@ function splitOnComponents(text, components) {
   return out;
 }
 export {
+  A11Y_SURFACES,
   DEFAULT_SURFACE_BREAKPOINTS,
   SonentaProvider,
   Trans,