@sonenta/react-i18next 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -83,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;
@@ -162,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
@@ -434,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
@@ -490,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`). */
@@ -625,4 +675,4 @@ declare class KeyRegistry {
 /** Process-wide singleton — there is exactly one on-screen registry. */
 declare const keyRegistry: KeyRegistry;
 
-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 };
+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

@@ -83,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;
@@ -162,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
@@ -434,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
@@ -490,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`). */
@@ -625,4 +675,4 @@ declare class KeyRegistry {
 /** Process-wide singleton — there is exactly one on-screen registry. */
 declare const keyRegistry: KeyRegistry;
 
-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 };
+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.js

@@ -210,7 +210,7 @@ function flattenPlurals(tree, locale) {
 
 // src/transport.ts
 var SDK_LIB = "@sonenta/react-i18next";
-var SDK_VER = true ? "2.2.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
@@ -449,6 +457,7 @@ 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);
@@ -551,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
@@ -647,6 +657,7 @@ var SonentaI18n = class {
       dir: this.dir,
       nativeName: this.nativeName,
       languageMeta: this.languageMeta,
+      availableLanguages: this.availableLanguages,
       i18next: this._i18next
     };
   }
@@ -708,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;
@@ -732,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));
@@ -822,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();
   };
   /**
@@ -1418,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";
@@ -1471,6 +1554,7 @@ export {
   logTransport,
   surfaceForWidth,
   t,
+  useAvailableLanguages,
   useTranslation
 };
 //# sourceMappingURL=index.js.map