efficient-shell 4.175.0 → 4.179.0

package/dist/i18n/index.d.ts

@@ -0,0 +1,79 @@
+import { ResourceLanguage, i18n, TFunction } from 'i18next';
+import { S as ShellStringsOverride } from '../strings-ZbotP_I6.js';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * efficient-shell/i18n — a host's own copy, in the language the shell is in.
+ *
+ * The shell's strings live in its typed catalog (`strings.tsx`) and the shell
+ * decides which language is active (`language.tsx`). Neither holds a HOST's
+ * copy: its column headings, its page titles, its toasts. That copy goes
+ * through i18next, and this entry is the one place it is set up, so every
+ * portal initialises it the same way and one language drives both halves.
+ *
+ * `i18next` and `react-i18next` are optional peers of this entry alone. A host
+ * that offers one language never installs them, and nothing reachable from
+ * `efficient-shell` or `efficient-shell/ui` imports them
+ * (`scripts/verify-dist.mjs`).
+ *
+ * ── The order a host boots in ──
+ * A language is fixed for the life of a page (see `language.tsx`), so:
+ *
+ *   1. `createShellI18n({ copy, load })` at module scope. It initialises
+ *      SYNCHRONOUSLY with the source-language copy, so `t` already answers in
+ *      English: a unit test that imports a column set gets English with no
+ *      setup at all.
+ *   2. Before the app is imported, `await activate(resolveShellLanguage(…))`.
+ *      It loads that language's copy and the shell's catalog for it together
+ *      and switches `t` over.
+ *   3. Only then import the app, and hand `activation.strings` to
+ *      `ShellLanguageProvider`.
+ *
+ * The order matters because a host's column sets, navigation and status
+ * buckets are module-level constants: they call `t` when they are IMPORTED and
+ * keep what it said. Copy read before step 2 stays in the source language for
+ * the life of the page, silently. `activate` says so out loud when it happens.
+ */
+
+interface CreateShellI18nOptions {
+    /** The source language's copy, bundled with the app: namespace → messages. */
+    copy: ResourceLanguage;
+    /** Another language's copy, in the same shape. Usually a dynamic import per
+     *  language, so a reader downloads only their own. */
+    load: (language: string) => Promise<ResourceLanguage>;
+    /** The shell's own catalog for a language — `efficient-shell/locales/<tag>`.
+     *  Omitted, the shell loads the catalogue it ships for that language, if it
+     *  ships one. Resolving to `undefined`, the shell's own words stay in the
+     *  source language. */
+    loadShellStrings?: (language: string) => Promise<ShellStringsOverride | undefined>;
+    /** The language `copy` is written in. Defaults to `en`. */
+    source?: string;
+    /** The namespace `t('key')` reads when it names none. Defaults to `common`. */
+    defaultNamespace?: string;
+}
+interface ShellI18nActivation {
+    /** The language actually in force: the one asked for, or the source
+     *  language when its copy could not be loaded. */
+    language: string;
+    /** The shell's catalog for it, for `ShellLanguageProvider`'s `strings`. */
+    strings?: ShellStringsOverride;
+    /** The requested language's copy could not be loaded, and the page is in the
+     *  source language instead. */
+    failed: boolean;
+}
+interface ShellI18n {
+    /** The i18next instance, for anything this entry does not wrap. It is also
+     *  the instance `react-i18next`'s `useTranslation` reads. */
+    i18n: i18n;
+    /** Read copy by key, anywhere: a module-level constant, a utility, a
+     *  component. Typed by the host's `CustomTypeOptions`, like i18next's own. */
+    t: TFunction;
+    /** Load a language's copy and switch to it. Call once, before the app is
+     *  imported. Never rejects: a language that cannot be loaded leaves the
+     *  page in the source language, with `failed` set. */
+    activate: (language: string) => Promise<ShellI18nActivation>;
+}
+declare function createShellI18n({ copy, load, loadShellStrings, source, defaultNamespace, }: CreateShellI18nOptions): ShellI18n;
+
+export { type CreateShellI18nOptions, type ShellI18n, type ShellI18nActivation, createShellI18n };

package/dist/i18n/index.js

@@ -0,0 +1,2 @@
+"use client";
+import e from"i18next";import{initReactI18next as a}from"react-i18next";var t=/* @__PURE__ */new Map([["zh-Hans",()=>import("../locales/zh-Hans.js").then(e=>e.zhHansStrings())]]),n=async e=>t.get(e)?.();function r({copy:t,load:r,loadShellStrings:o=n,source:s="en",defaultNamespace:i="common"}){const l=e.createInstance();l.use(a).init({lng:s,fallbackLng:s,resources:{[s]:t},ns:Object.keys(t),defaultNS:i,initAsync:!1,interpolation:{escapeValue:!1}});let c=!1,f=!1;return{i18n:l,t:(...e)=>(f||(c=!0),l.t(...e)),activate:async e=>{if(f=!0,e===s)return{language:s,failed:!1};c&&console.error(`[efficient-shell/i18n] copy was read before activate("${e}") ran, so those strings stay in "${s}" for the life of this page. Import the app only after activate() resolves.`);try{const[a,t]=await Promise.all([r(e),o(e)]);for(const[t,n]of Object.entries(a))l.addResourceBundle(e,t,n,!0,!0);return await l.changeLanguage(e),{language:e,strings:t,failed:!1}}catch(a){return console.error(`[efficient-shell/i18n] could not load "${e}"; staying in "${s}".`,a),{language:s,failed:!0}}}}}export{r as createShellI18n};