@sonenta/react-i18next 2.1.0 → 2.3.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. */
@@ -65,6 +83,20 @@ interface LanguageMeta {
     /** CLDR plural categories present for this language. */
     plural_categories?: string[];
 }
+/**
+ * A language PUBLISHED for the active version (task: available-languages) — a
+ * {@link LanguageMeta} (enriched from the catalog) plus publish info from the
+ * per-version CDN manifest. Returned by `i18n.availableLanguages` /
+ * `useAvailableLanguages()`.
+ */
+interface AvailableLanguage extends LanguageMeta {
+    /** ISO timestamp this language was published for the active version, when
+     *  the manifest provides it (optional / forward-compat). Render a
+     *  "recently added" hint if present; ignore if absent. */
+    published_at?: string;
+    /** True when this is the project's default locale for the active version. */
+    is_default?: boolean;
+}
 interface MissingKeyEvent {
     key: string;
     namespace: Namespace;
@@ -144,6 +176,14 @@ interface SonentaConfig {
      * you supply {@link SonentaConfig.languageCatalog} yourself.
      */
     disableLanguageCatalog?: boolean;
+    /**
+     * Skip the best-effort fetch of the per-version published-languages manifest
+     * (`{cdnBase}/p/{project}/{version}/latest/languages.json`, public, no auth)
+     * that powers `i18n.availableLanguages` / `useAvailableLanguages()`. When
+     * skipped (or on a 404), `availableLanguages` falls back to the configured
+     * `defaultLocale` + `fallbackLng`.
+     */
+    disableLanguageManifest?: boolean;
     /**
      * Interpolation hooks forwarded to i18next. Currently exposes `format`, the
      * value formatter i18next invokes for `{{value, format}}` placeholders — wire
@@ -227,6 +267,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 +399,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
@@ -362,6 +456,15 @@ interface I18nInstance {
      * parent, …), defaulting to the active locale; `undefined` if unknown.
      */
     languageMeta: (lng?: Locale) => LanguageMeta | undefined;
+    /**
+     * The languages PUBLISHED for the active version (from the per-version CDN
+     * manifest, enriched with catalog metadata) — drives a runtime language
+     * switcher that updates when a new language ships WITHOUT recompiling the
+     * app. Falls back to `defaultLocale` + `fallbackLng` when no manifest is
+     * available. Refreshed on `reload()`. Prefer the `useAvailableLanguages()`
+     * hook in React (reactive).
+     */
+    availableLanguages: AvailableLanguage[];
     /**
      * The underlying real `i18next` instance powering this SDK (thin-wrapper,
      * #805). Exposed for react-i18next DROP-IN: pass it to react-i18next's own
@@ -383,6 +486,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 +509,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
@@ -402,6 +521,25 @@ interface UseTranslationResult {
  *  contribution is keyed to THIS hook instance and dropped on unmount, so
  *  navigating away removes its keys automatically. */
 declare function useTranslation(defaultNamespace?: string): UseTranslationResult;
+/**
+ * React hook — the languages PUBLISHED for the active version, enriched with
+ * catalog metadata (native_name / rtl / …). Drives a runtime language switcher
+ * that picks up a newly-published language WITHOUT recompiling the app: the
+ * per-version manifest is CDN-served, so the new language appears on the next
+ * load (or after `i18n.reload()`). Falls back to `defaultLocale` +
+ * `fallbackLng` when no manifest is available.
+ *
+ * ```tsx
+ * const langs = useAvailableLanguages();
+ * const { i18n } = useTranslation();
+ * return langs.map((l) => (
+ *   <button key={l.code} onClick={() => i18n.setLocale(l.code)}>
+ *     {l.native_name ?? l.code}{l.is_default ? " ★" : ""}
+ *   </button>
+ * ));
+ * ```
+ */
+declare function useAvailableLanguages(): AvailableLanguage[];
 
 interface TransProps {
     /** The translation key (optionally `ns:key`). */
@@ -537,4 +675,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 A11yTranslationFunction, type AssetRef, type AvailableLanguage, 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, useAvailableLanguages, 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. */
@@ -65,6 +83,20 @@ interface LanguageMeta {
     /** CLDR plural categories present for this language. */
     plural_categories?: string[];
 }
+/**
+ * A language PUBLISHED for the active version (task: available-languages) — a
+ * {@link LanguageMeta} (enriched from the catalog) plus publish info from the
+ * per-version CDN manifest. Returned by `i18n.availableLanguages` /
+ * `useAvailableLanguages()`.
+ */
+interface AvailableLanguage extends LanguageMeta {
+    /** ISO timestamp this language was published for the active version, when
+     *  the manifest provides it (optional / forward-compat). Render a
+     *  "recently added" hint if present; ignore if absent. */
+    published_at?: string;
+    /** True when this is the project's default locale for the active version. */
+    is_default?: boolean;
+}
 interface MissingKeyEvent {
     key: string;
     namespace: Namespace;
@@ -144,6 +176,14 @@ interface SonentaConfig {
      * you supply {@link SonentaConfig.languageCatalog} yourself.
      */
     disableLanguageCatalog?: boolean;
+    /**
+     * Skip the best-effort fetch of the per-version published-languages manifest
+     * (`{cdnBase}/p/{project}/{version}/latest/languages.json`, public, no auth)
+     * that powers `i18n.availableLanguages` / `useAvailableLanguages()`. When
+     * skipped (or on a 404), `availableLanguages` falls back to the configured
+     * `defaultLocale` + `fallbackLng`.
+     */
+    disableLanguageManifest?: boolean;
     /**
      * Interpolation hooks forwarded to i18next. Currently exposes `format`, the
      * value formatter i18next invokes for `{{value, format}}` placeholders — wire
@@ -227,6 +267,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 +399,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
@@ -362,6 +456,15 @@ interface I18nInstance {
      * parent, …), defaulting to the active locale; `undefined` if unknown.
      */
     languageMeta: (lng?: Locale) => LanguageMeta | undefined;
+    /**
+     * The languages PUBLISHED for the active version (from the per-version CDN
+     * manifest, enriched with catalog metadata) — drives a runtime language
+     * switcher that updates when a new language ships WITHOUT recompiling the
+     * app. Falls back to `defaultLocale` + `fallbackLng` when no manifest is
+     * available. Refreshed on `reload()`. Prefer the `useAvailableLanguages()`
+     * hook in React (reactive).
+     */
+    availableLanguages: AvailableLanguage[];
     /**
      * The underlying real `i18next` instance powering this SDK (thin-wrapper,
      * #805). Exposed for react-i18next DROP-IN: pass it to react-i18next's own
@@ -383,6 +486,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 +509,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
@@ -402,6 +521,25 @@ interface UseTranslationResult {
  *  contribution is keyed to THIS hook instance and dropped on unmount, so
  *  navigating away removes its keys automatically. */
 declare function useTranslation(defaultNamespace?: string): UseTranslationResult;
+/**
+ * React hook — the languages PUBLISHED for the active version, enriched with
+ * catalog metadata (native_name / rtl / …). Drives a runtime language switcher
+ * that picks up a newly-published language WITHOUT recompiling the app: the
+ * per-version manifest is CDN-served, so the new language appears on the next
+ * load (or after `i18n.reload()`). Falls back to `defaultLocale` +
+ * `fallbackLng` when no manifest is available.
+ *
+ * ```tsx
+ * const langs = useAvailableLanguages();
+ * const { i18n } = useTranslation();
+ * return langs.map((l) => (
+ *   <button key={l.code} onClick={() => i18n.setLocale(l.code)}>
+ *     {l.native_name ?? l.code}{l.is_default ? " ★" : ""}
+ *   </button>
+ * ));
+ * ```
+ */
+declare function useAvailableLanguages(): AvailableLanguage[];
 
 interface TransProps {
     /** The translation key (optionally `ns:key`). */
@@ -537,4 +675,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 A11yTranslationFunction, type AssetRef, type AvailableLanguage, 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, useAvailableLanguages, useTranslation };