@webmobix/i18next-plugins 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# @leo-translate/i18next-plugins
+
+i18next backend and post-processor plugins for Leo Translate.
+
+## Installation
+
+```bash
+pnpm add @leo-translate/i18next-plugins
+```
+
+## Plugins
+
+### LeoBackend
+
+A custom i18next backend that fetches translation JSON files from a remote URL (e.g. Cloudflare R2).
+
+Translation files are resolved using the pattern:
+
+```
+{remoteUrl}/{appId}/{language}/{namespace}.json
+```
+
+#### Options
+
+| Option                  | Type                  | Default                     | Description                                               |
+| ----------------------- | --------------------- | --------------------------- | --------------------------------------------------------- |
+| `appId`                 | `string \| undefined` | `undefined`                 | The ID of the application. Required for fetching to work. |
+| `remoteUrl`             | `string`              | Leo Translate R2 public URL | Base URL for fetching translation files.                  |
+| `localStorageKeyPrefix` | `string`              | `'leo-translate'`           | Key prefix used by the Chrome extension for overrides.    |
+
+---
+
+### LeoPostProcessor
+
+A pass-through i18next post-processor stub. Register it with i18next and opt in per translation call or globally.
+
+---
+
+## Usage
+
+### Option 1 — Root import
+
+Import both plugins from the package root:
+
+```ts
+import { LeoBackend, LeoPostProcessor } from '@leo-translate/i18next-plugins';
+import i18n from 'i18next';
+
+i18n
+  .use(LeoBackend)
+  .use(LeoPostProcessor)
+  .init({
+    backend: {
+      appId: 'my-app',
+      remoteUrl: 'https://translations.example.com',
+    },
+  });
+```
+
+### Option 2 — Sub-path imports
+
+Import each plugin individually from its own sub-path:
+
+```ts
+import { LeoBackend } from '@leo-translate/i18next-plugins/backend';
+import { LeoPostProcessor } from '@leo-translate/i18next-plugins/post-processor';
+import i18n from 'i18next';
+
+i18n
+  .use(LeoBackend)
+  .use(LeoPostProcessor)
+  .init({
+    backend: {
+      appId: 'my-app',
+      remoteUrl: 'https://translations.example.com',
+    },
+  });
+```
+
+Sub-path imports are useful when you only need one plugin and want to avoid pulling in the other.
+
+---
+
+## CLI — `leo-translate`
+
+The package ships a `leo-translate` binary for managing translation bundles from the command line.
+
+### Installation
+
+Install the package globally or as a dev dependency to make the binary available:
+
+```bash
+# global
+pnpm add -g @leo-translate/i18next-plugins
+
+# dev dependency (run via pnpm exec or package.json scripts)
+pnpm add -D @leo-translate/i18next-plugins
+```
+
+### Commands
+
+#### `leo-translate import <folder>`
+
+Discovers all i18next namespace JSON files under a locale folder and uploads them to the Leo Translate backend.
+
+**Folder structure expected:**
+
+```
+locales/
+  en/
+    common.json
+    dashboard.json
+  de/
+    common.json
+    dashboard.json
+```
+
+**Usage:**
+
+```bash
+leo-translate import ./locales --app-id my-app
+```
+
+**Options:**
+
+| Flag          | Type      | Default                             | Description                                                                 |
+| ------------- | --------- | ----------------------------------- | --------------------------------------------------------------------------- |
+| `--app-id`    | `string`  | —                                   | **Required.** Leo Translate app ID (slug).                                  |
+| `--url`       | `string`  | `https://leo-translate.webmobix.io` | Backend URL to upload to.                                                   |
+| `--overwrite` | `boolean` | `false`                             | Overwrite existing published values. By default, existing keys are skipped. |
+| `--dry-run`   | `boolean` | `false`                             | Print the full import plan without making any changes.                      |
+| `--language`  | `string`  | all languages                       | Import only the specified language subfolder (e.g. `en`).                   |
+
+**Examples:**
+
+```bash
+# Preview what would be imported
+leo-translate import ./locales --app-id my-app --dry-run
+
+# Import only English, overwriting existing keys
+leo-translate import ./locales --app-id my-app --language en --overwrite
+
+# Import to a self-hosted backend
+leo-translate import ./locales --app-id my-app --url https://translate.example.com
+```
+
+**Authentication:**
+
+The first time a live import is run, the CLI opens a browser window to complete an OAuth 2.0 PKCE login flow. After a successful login the token is cached in `~/.leo-translate/credentials.json` (mode `0600`) and reused on subsequent runs until it expires.
+
+**Import results:**
+
+After each upload the CLI prints a per-namespace summary of created, updated, and skipped keys. If any errors are returned by the API the CLI exits with code `1`.
+
+---
+
+#### `leo-translate logout`
+
+Clears the locally cached authentication token. The next command that requires auth will re-trigger the browser login flow.
+
+```bash
+leo-translate logout
+```

package/dist/backend/index.d.ts

@@ -0,0 +1,55 @@
+import type { BackendModule, Services, InitOptions, ReadCallback } from 'i18next';
+export interface LeoBackendOptions {
+    /**
+     * Base URL for fetching translation files from the remote (e.g. Cloudflare R2).
+     * Example: 'https://translations.example.com'
+     */
+    remoteUrl?: string;
+    /**
+     * The ID of the application
+     */
+    appId: string | undefined;
+    /**
+     * The localStorage key prefix used by the Leo Translate Chrome extension
+     * to store translation overrides.
+     * Defaults to 'leo-translate'.
+     */
+    localStorageKeyPrefix?: string;
+    /**
+     * Base URL of the Leo Translate API used to report missing keys.
+     * Example: 'https://leo-translate.webmobix.io'
+     *
+     * Requires `saveMissingSecret` to also be set.
+     * When absent, `create()` is a no-op.
+     */
+    saveMissingApiUrl?: string;
+    /**
+     * Per-app secret for the save-missing-keys endpoint (generated via the dashboard
+     * or `POST /api/backend/apps/:appId/secrets/generate`).
+     *
+     * Keep this out of production builds — set it via an environment variable in
+     * local/staging only. When absent, `create()` is a no-op.
+     */
+    saveMissingSecret?: string;
+    /**
+     * Debounce interval in milliseconds for batching missing keys before sending
+     * them to the API. Individual calls to `create()` are accumulated and flushed
+     * in a single POST after this delay.
+     * Defaults to 2000 ms.
+     */
+    saveMissingDebounceMs?: number;
+}
+export declare class LeoBackend implements BackendModule<LeoBackendOptions> {
+    static readonly type: "backend";
+    readonly type: "backend";
+    private services;
+    private options;
+    private i18nextOptions;
+    private pendingMissingKeys;
+    private flushTimer;
+    constructor(services: Services, options: LeoBackendOptions, i18nextOptions?: InitOptions);
+    init(services: Services, options: LeoBackendOptions, i18nextOptions: InitOptions): void;
+    create(languages: readonly string[], namespace: string, key: string, fallbackValue: string): void;
+    private flushMissingKeys;
+    read(language: string, namespace: string, callback: ReadCallback): void;
+}

package/dist/backend.js

@@ -0,0 +1,89 @@
+const u = {
+  remoteUrl: "https://leo-translate-cdn.webmobix.io",
+  appId: void 0,
+  localStorageKeyPrefix: "leo-translate",
+  saveMissingApiUrl: "https://leo-translate.webmobix.io",
+  saveMissingSecret: "",
+  saveMissingDebounceMs: 2e3
+};
+class a extends Error {
+  constructor(s, t = !1) {
+    super(s), this.retry = t;
+  }
+}
+const c = class c {
+  constructor(s, t, i) {
+    this.type = "backend", this.pendingMissingKeys = [], this.flushTimer = null, s && this.init(s, t, i ?? {});
+  }
+  init(s, t, i) {
+    this.services = s, this.i18nextOptions = i, this.options = {
+      ...u,
+      ...t
+    };
+  }
+  create(s, t, i, n) {
+    const { saveMissingApiUrl: o, saveMissingSecret: r, appId: e, saveMissingDebounceMs: h } = this.options;
+    if (console.debug(`[leo-translate:backend] Missing key: ${t}:${i}`, {
+      languages: s,
+      namespace: t,
+      key: i,
+      fallbackValue: n,
+      appId: e
+    }), !(!o || !r || !e)) {
+      for (const l of s)
+        this.pendingMissingKeys.push({ namespace: t, key: i, language: l, fallbackValue: n });
+      this.flushTimer !== null && clearTimeout(this.flushTimer), this.flushTimer = setTimeout(() => {
+        this.flushMissingKeys();
+      }, h);
+    }
+  }
+  flushMissingKeys() {
+    const s = this.pendingMissingKeys.splice(0);
+    if (this.flushTimer = null, s.length === 0) return;
+    const { saveMissingApiUrl: t, saveMissingSecret: i, appId: n } = this.options, o = `${t}/api/backend/apps/${n}/missing-keys`;
+    console.debug(`[leo-translate:backend] Flushing ${s.length} missing key(s) to ${o}`), fetch(o, {
+      method: "POST",
+      credentials: "omit",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Leo-Save-Missing-Key": i
+      },
+      body: JSON.stringify({ keys: s })
+    }).catch(() => {
+    });
+  }
+  read(s, t, i) {
+    const { remoteUrl: n, appId: o } = this.options;
+    if (!n || !o) {
+      i(null, {});
+      return;
+    }
+    const r = `${n}/${o}/latest/${s}/${t}.json`;
+    fetch(r).then(
+      (e) => {
+        const { ok: h, status: l } = e;
+        if (!h) {
+          const g = l >= 500 && l < 600;
+          throw new a(`failed loading ${r}`, g);
+        }
+        return e.text();
+      },
+      () => {
+        throw new a(`failed loading ${r}`);
+      }
+    ).then((e) => {
+      try {
+        i(null, JSON.parse(e));
+      } catch {
+        throw new a(`failed parsing ${r} to json`, !1);
+      }
+    }).catch((e) => {
+      e instanceof a && i(e.message, e.retry);
+    });
+  }
+};
+c.type = "backend";
+let p = c;
+export {
+  p as LeoBackend
+};

package/dist/cli/auth.d.ts

@@ -0,0 +1,24 @@
+export interface AuthResult {
+    token: string;
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+    };
+}
+/**
+ * Returns a valid session token for the given backend URL.
+ *
+ * If a cached non-expired token exists it is returned immediately.
+ * Otherwise the user is sent through an OAuth 2.0 PKCE flow:
+ *   1. A temporary HTTP server is started on a random local port.
+ *   2. The browser is opened to /oauth/authorize.
+ *   3. After login/consent the server captures the auth code.
+ *   4. The code is exchanged for a session token.
+ *   5. The token is cached to ~/.leo-translate/credentials.json.
+ */
+export declare function getToken(backendUrl: string): Promise<AuthResult>;
+/**
+ * Remove the cached credentials for the given backend URL.
+ */
+export declare function clearCredentials(): void;

package/dist/cli/flatten.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Recursively flattens a nested object into dot-notation key/value pairs.
+ *
+ * Example:
+ *   { header: { title: "Hello" }, footer: "Bye" }
+ *   → { "header.title": "Hello", "footer": "Bye" }
+ */
+export declare function flattenKeys(obj: unknown, prefix?: string): Record<string, string>;

package/dist/cli/import.d.ts

@@ -0,0 +1,20 @@
+export interface ImportOptions {
+    folder: string;
+    appId: string;
+    appSecret: string;
+    backendUrl: string;
+    overwrite: boolean;
+    dryRun: boolean;
+    /** If set, only import this language (subfolder name). Otherwise import all. */
+    language?: string;
+}
+/**
+ * Discovers all language/namespace pairs under `options.folder`, then uploads
+ * them to the Leo Translate backend via the bulk import API.
+ *
+ * Expected directory structure:
+ *   <folder>/
+ *     <language>/          ← BCP-47 language tag (e.g. "en", "de", "pt-BR")
+ *       <namespace>.json   ← flat or nested i18next bundle
+ */
+export declare function runImport(options: ImportOptions): Promise<void>;

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+import { defineCommand as k, runMain as P } from "citty";
+import { readdirSync as v, statSync as D, readFileSync as S, mkdirSync as I, writeFileSync as N } from "node:fs";
+import { resolve as _, join as y, basename as U, extname as R } from "node:path";
+import { randomBytes as O, createHash as F } from "node:crypto";
+import { createServer as J } from "node:http";
+import { homedir as q } from "node:os";
+import K from "open";
+function T(e, n = "") {
+  if (e === null || typeof e != "object" || Array.isArray(e))
+    return {};
+  const o = {};
+  for (const [l, a] of Object.entries(e)) {
+    const i = n ? `${n}.${l}` : l;
+    a !== null && typeof a == "object" && !Array.isArray(a) ? Object.assign(o, T(a, i)) : typeof a == "string" ? o[i] = a : a != null && (o[i] = String(a));
+  }
+  return o;
+}
+function B(e) {
+  return v(e).filter((n) => {
+    try {
+      return D(y(e, n)).isDirectory();
+    } catch {
+      return !1;
+    }
+  });
+}
+function M(e) {
+  return v(e).filter((n) => R(n) === ".json");
+}
+function H(e) {
+  const n = S(e, "utf8");
+  try {
+    return JSON.parse(n);
+  } catch (o) {
+    const l = o instanceof Error ? o.message : String(o);
+    throw new Error(`Failed to parse ${e}: ${l}`);
+  }
+}
+async function Y(e, n, o, l, a, i, p) {
+  const g = `${n}/api/backend/apps/${encodeURIComponent(o)}/import`, s = await fetch(g, {
+    method: "POST",
+    headers: {
+      "X-Leo-Save-Missing-Key": e,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ language: l, namespace: a, keys: i, overwrite: p })
+  });
+  if (!s.ok) {
+    const u = await s.json().catch(() => ({ error: s.statusText }));
+    throw new Error(`API error (${s.status}): ${u.error ?? s.statusText}`);
+  }
+  return s.json();
+}
+async function z(e) {
+  const { appId: n, overwrite: o, dryRun: l } = e, a = e.backendUrl.replace(/\/+$/, ""), i = _(e.folder), p = B(i);
+  p.length === 0 && (console.error(
+    `[leo-translate] No language subdirectories found in ${i}.
+Expected structure: <folder>/<language>/<namespace>.json`
+  ), process.exit(1));
+  const g = e.language ? p.filter((t) => t === e.language) : p;
+  g.length === 0 && (console.error(
+    `[leo-translate] Language '${e.language}' not found in ${i}.
+Available: ${p.join(", ")}`
+  ), process.exit(1));
+  const s = [];
+  for (const t of g) {
+    const r = y(i, t), d = M(r);
+    if (d.length === 0) {
+      console.warn(`[leo-translate] No JSON files found in ${r}, skipping.`);
+      continue;
+    }
+    for (const m of d) {
+      const h = U(m, ".json");
+      let w;
+      try {
+        w = H(y(r, m));
+      } catch (b) {
+        const E = b instanceof Error ? b.message : String(b);
+        console.error(`[leo-translate] Error reading ${m}: ${E}`);
+        continue;
+      }
+      const A = T(w);
+      if (Object.keys(A).length === 0) {
+        console.warn(`[leo-translate] ${t}/${m} is empty or has no string values, skipping.`);
+        continue;
+      }
+      s.push({ language: t, namespace: h, keys: A });
+    }
+  }
+  if (s.length === 0) {
+    console.log("[leo-translate] Nothing to import.");
+    return;
+  }
+  if (l) {
+    console.log(
+      `[leo-translate] Dry run — would import into app '${n}' at ${a} (overwrite: ${o ? "yes" : "no"})
+`
+    );
+    let t = 0;
+    for (const r of s) {
+      const d = Object.keys(r.keys).length;
+      t += d, console.log(`  ${r.language}/${r.namespace}  (${d} keys)`);
+      for (const [m, h] of Object.entries(r.keys)) {
+        const w = h.length > 80 ? `${h.slice(0, 77)}…` : h;
+        console.log(`    ${m}: ${w}`);
+      }
+    }
+    console.log(
+      `
+[leo-translate] Dry run complete — ${s.length} namespace(s), ${t} key(s) total. No changes were made.`
+    );
+    return;
+  }
+  e.appSecret || (console.error(
+    `[leo-translate] Error: --app-secret is required for import.
+Generate a secret in the Leo Translate dashboard under App Settings → Secrets.`
+  ), process.exit(1)), console.log(
+    `[leo-translate] Importing ${s.length} namespace(s) into app '${n}' (overwrite: ${o ? "yes" : "no"})…
+`
+  );
+  const u = [];
+  let c = !1;
+  for (const t of s) {
+    process.stdout.write(
+      `  ${t.language}/${t.namespace} (${Object.keys(t.keys).length} keys)… `
+    );
+    try {
+      const r = await Y(
+        e.appSecret,
+        a,
+        n,
+        t.language,
+        t.namespace,
+        t.keys,
+        o
+      );
+      u.push({
+        language: t.language,
+        namespace: t.namespace,
+        ...r
+      });
+      const d = [];
+      if (r.created > 0 && d.push(`${r.created} created`), r.updated > 0 && d.push(`${r.updated} updated`), r.skipped > 0 && d.push(`${r.skipped} skipped`), console.log(d.length > 0 ? d.join(", ") : "no changes"), r.errors.length > 0) {
+        c = !0;
+        for (const m of r.errors)
+          console.error(`    ! ${m}`);
+      }
+    } catch (r) {
+      c = !0;
+      const d = r instanceof Error ? r.message : String(r);
+      console.error(`FAILED
+    ! ${d}`), u.push({
+        language: t.language,
+        namespace: t.namespace,
+        created: 0,
+        updated: 0,
+        skipped: 0,
+        errors: [d]
+      });
+    }
+  }
+  const f = u.reduce(
+    (t, r) => ({
+      created: t.created + r.created,
+      updated: t.updated + r.updated,
+      skipped: t.skipped + r.skipped,
+      errors: t.errors + r.errors.length
+    }),
+    { created: 0, updated: 0, skipped: 0, errors: 0 }
+  );
+  console.log(
+    `
+[leo-translate] Done — ${f.created} created, ${f.updated} updated, ${f.skipped} skipped, ${f.errors} error(s)`
+  ), c && process.exit(1), process.exit(0);
+}
+const j = y(q(), ".leo-translate"), C = y(j, "credentials.json"), x = 49152, X = 65535;
+function G(e) {
+  try {
+    const n = S(C, "utf8"), o = JSON.parse(n);
+    return o.backendUrl !== e || new Date(o.expiresAt) <= /* @__PURE__ */ new Date() ? null : o;
+  } catch {
+    return null;
+  }
+}
+function L(e) {
+  I(j, { recursive: !0 }), N(C, JSON.stringify(e, null, 2), { mode: 384 });
+}
+function V() {
+  return O(32).toString("base64url");
+}
+function Q(e) {
+  return F("sha256").update(e).digest("base64url");
+}
+function W() {
+  return new Promise((e, n) => {
+    const o = Math.floor(Math.random() * (X - x + 1)) + x;
+    let l, a;
+    const i = new Promise((s, u) => {
+      l = s, a = u;
+    }), p = /* @__PURE__ */ new Set(), g = J((s, u) => {
+      const c = new URL(s.url ?? "/", `http://127.0.0.1:${o}`);
+      if (c.pathname !== "/callback") {
+        u.writeHead(404), u.end();
+        return;
+      }
+      const f = c.searchParams.get("code"), t = c.searchParams.get("state") ?? "", r = c.searchParams.get("error");
+      u.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }), f ? (u.end(
+        '<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:60px"><h2>Authentication successful</h2><p>You can close this tab and return to the terminal.</p></body></html>'
+      ), l({ code: f, state: t })) : (u.end(
+        `<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:60px"><h2>Authentication failed</h2><p>${r ?? "Unknown error"}</p></body></html>`
+      ), a(new Error(`OAuth error: ${r ?? "unknown"}`)));
+    });
+    g.on("connection", (s) => {
+      p.add(s), s.once("close", () => p.delete(s));
+    }), g.on("error", n), g.listen(o, "127.0.0.1", () => {
+      e({
+        port: o,
+        waitForCode: () => i,
+        close: () => {
+          for (const s of p) s.destroy();
+          g.close();
+        }
+      });
+    });
+  });
+}
+async function Z(e, n, o, l) {
+  const a = await fetch(`${e}/api/ext/auth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code: n, code_verifier: o, redirect_uri: l })
+  });
+  if (!a.ok) {
+    const i = await a.json().catch(() => ({ error: a.statusText }));
+    throw new Error(`Token exchange failed (${a.status}): ${i.error ?? a.statusText}`);
+  }
+  return a.json();
+}
+async function ee(e) {
+  const n = e.replace(/\/+$/, ""), o = G(n);
+  if (o)
+    return { token: o.token, user: o.user };
+  console.log("[leo-translate] No cached credentials found. Opening browser for authentication…");
+  const l = V(), a = Q(l), i = O(8).toString("hex"), { port: p, waitForCode: g, close: s } = await W(), u = `http://127.0.0.1:${p}/callback`, c = new URL(`${n}/oauth/authorize`);
+  c.searchParams.set("response_type", "code"), c.searchParams.set("client_id", "leo-translate-cli"), c.searchParams.set("redirect_uri", u), c.searchParams.set("code_challenge", a), c.searchParams.set("code_challenge_method", "S256"), c.searchParams.set("state", i), console.log(`[leo-translate] Opening: ${c.toString()}`), await K(c.toString());
+  let f;
+  try {
+    f = await Promise.race([
+      g(),
+      new Promise(
+        (r, d) => setTimeout(() => d(new Error("Authentication timed out (5 minutes)")), 5 * 60 * 1e3)
+      )
+    ]);
+  } finally {
+    s();
+  }
+  if (f.state !== i)
+    throw new Error("OAuth state mismatch — possible CSRF attack. Authentication aborted.");
+  const t = await Z(n, f.code, l, u);
+  return L({
+    token: t.token,
+    expiresAt: t.expiresAt,
+    backendUrl: n,
+    user: t.user
+  }), console.log(`[leo-translate] Authenticated as ${t.user.email}`), { token: t.token, user: t.user };
+}
+function te() {
+  try {
+    const e = S(C, "utf8"), n = JSON.parse(e);
+    L({ ...n, expiresAt: (/* @__PURE__ */ new Date(0)).toISOString() });
+  } catch {
+  }
+}
+const $ = "https://leo-translate.webmobix.io", re = k({
+  meta: {
+    name: "import",
+    description: "Import i18next namespace bundles into Leo Translate"
+  },
+  args: {
+    folder: {
+      type: "positional",
+      description: "Path to locale folder with <language>/<namespace>.json structure",
+      required: !0
+    },
+    "app-id": {
+      type: "string",
+      description: "Leo Translate app ID",
+      required: !0
+    },
+    "app-secret": {
+      type: "string",
+      description: "App secret for backend API authentication (from App Settings → Secrets)",
+      required: !0
+    },
+    url: {
+      type: "string",
+      description: `Backend URL (default: ${$})`,
+      required: !1
+    },
+    overwrite: {
+      type: "boolean",
+      description: "Overwrite existing published values (default: skip existing)",
+      default: !1
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Preview what would be imported without making any changes",
+      default: !1
+    },
+    language: {
+      type: "string",
+      description: "Import only this language subfolder (default: all)",
+      required: !1
+    }
+  },
+  async run({ args: e }) {
+    await z({
+      folder: e.folder,
+      appId: e["app-id"],
+      appSecret: e["app-secret"],
+      backendUrl: e.url ?? $,
+      overwrite: e.overwrite,
+      dryRun: e["dry-run"],
+      language: e.language
+    });
+  }
+}), ne = k({
+  meta: {
+    name: "login",
+    description: "Authenticate with the Leo Translate backend"
+  },
+  args: {
+    url: {
+      type: "string",
+      description: `Backend URL (default: ${$})`,
+      required: !1
+    }
+  },
+  async run({ args: e }) {
+    const n = e.url ?? $;
+    console.log(`[leo-translate] Logging in to ${n}…`);
+    const { user: o } = await ee(n);
+    console.log(`[leo-translate] Authenticated as ${o.email}.`), process.exit(0);
+  }
+}), oe = k({
+  meta: {
+    name: "logout",
+    description: "Clear cached authentication credentials"
+  },
+  args: {},
+  run() {
+    te(), console.log("[leo-translate] Credentials cleared.");
+  }
+}), ae = k({
+  meta: {
+    name: "leo-translate",
+    version: "0.1.0",
+    description: "Leo Translate CLI — manage translation bundles"
+  },
+  subCommands: {
+    import: re,
+    login: ne,
+    logout: oe
+  }
+});
+P(ae);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { LeoBackend } from './backend/index';
+export type { LeoBackendOptions } from './backend/index';
+export { LeoPostProcessor } from './post-processor/index';
+export type { LeoPostProcessorOptions } from './post-processor/index';
+export { leoTranslatorSupport } from './translator-support/index';
+export type { LeoTranslatorSupport } from './translator-support/index';

package/dist/index.js

@@ -0,0 +1,8 @@
+import { LeoBackend as e } from "./backend.js";
+import { LeoPostProcessor as p } from "./post-processor.js";
+import { leoTranslatorSupport as a } from "./translator-support.js";
+export {
+  e as LeoBackend,
+  p as LeoPostProcessor,
+  a as leoTranslatorSupport
+};

package/dist/post-processor/index.d.ts

@@ -0,0 +1,30 @@
+import type { i18n, PostProcessorModule } from 'i18next';
+/**
+ * Extracts and decodes an invisible key marker from a text node string.
+ * Returns the decoded `namespace:key` string, or `null` if no marker found.
+ */
+export declare function decodeMarker(text: string): string | null;
+/** Enable or disable key marker embedding. Called by LeoTranslatorSupport. */
+export declare function setDiscoveryActive(active: boolean): void;
+/** Returns the current discovery mode state. */
+export declare function isDiscoveryActive(): boolean;
+export interface LeoPostProcessorOptions {
+    [key: string]: unknown;
+}
+interface ExtendedPostProcessor extends PostProcessorModule {
+    init?: (instance: i18n) => void;
+    instance?: i18n;
+}
+/**
+ * Leo Translate postProcessor plugin for i18next.
+ *
+ * Register with i18next:
+ *   import { LeoPostProcessor } from '@leo-translate/i18next-plugins/post-processor';
+ *   i18n.use(LeoPostProcessor).init({ postProcess: ['leoPostProcessor'] });
+ *
+ * Zero-cost passthrough when discovery mode is off.  When on (toggled by the
+ * Chrome extension sidebar), each translated string is prefixed with an
+ * invisible encoded marker so the content script can locate keys in the DOM.
+ */
+export declare const LeoPostProcessor: ExtendedPostProcessor;
+export {};

package/dist/post-processor.js

@@ -0,0 +1,61 @@
+const h = ["​", "‌", "‎", "‏"], y = {
+  "​": 0,
+  "‌": 1,
+  "‎": 2,
+  "‏": 3
+}, P = "⁠", g = "⁡";
+function C(t) {
+  let o = P;
+  for (let n = 0; n < t.length; n++) {
+    const s = t.charCodeAt(n);
+    for (let e = 7; e >= 0; e--)
+      o += h[s >> e * 2 & 3];
+  }
+  return o + g;
+}
+function N(t) {
+  const o = t.match(/\u2060([\u200B\u200C\u200E\u200F]+)\u2061/);
+  if (!o) return null;
+  const n = o[1];
+  if (n.length % 8 !== 0) return null;
+  let s = "";
+  for (let e = 0; e < n.length; e += 8) {
+    let r = 0;
+    for (let i = 0; i < 8; i++) {
+      const c = y[n[e + i]];
+      if (c === void 0) return null;
+      r = r << 2 | c;
+    }
+    s += String.fromCharCode(r);
+  }
+  return s;
+}
+let a = !1;
+function v(t) {
+  a = t;
+}
+function m() {
+  return a;
+}
+const M = {
+  type: "postProcessor",
+  name: "leoPostProcessor",
+  init(t) {
+    this.instance = t;
+  },
+  process(t, o, n, s) {
+    var u, d, f;
+    if (!a || typeof t != "string") return t;
+    const e = ((d = (u = this.instance) == null ? void 0 : u.options) == null ? void 0 : d.nsSeparator) || ":";
+    console.debug("[leo-translate:postProcessor] Pre mrking key:", { key: o });
+    const r = Array.isArray(o) ? o[0] : o, c = (f = s.options) == null ? void 0 : f.defaultNS, p = Array.isArray(c) ? c[0] : c, A = n.ns || p || "translation";
+    let l = r;
+    return r.includes(e) || (l = `${A}${e}${r}`), console.debug("[leo-translate:postProcessor] Marking key:", l), C(l) + t;
+  }
+};
+export {
+  M as LeoPostProcessor,
+  N as decodeMarker,
+  m as isDiscoveryActive,
+  v as setDiscoveryActive
+};

package/dist/translator-support/index.d.ts

@@ -0,0 +1,99 @@
+import type { i18n, Module } from 'i18next';
+export declare class LeoTranslatorSupport implements Module {
+    type: "3rdParty";
+    private i18n;
+    /**
+     * All translation keys loaded from i18n resource bundles, keyed by their
+     * composite `namespace:key` identifier.
+     *
+     * Built by {@link registerBundle} as it recursively flattens every bundle
+     * that i18next commits to its store (via the `loaded` event).  Each entry
+     * stores the namespace and the translated string value so the sidebar can
+     * display current values and detect overrides.
+     *
+     * A key is present here as soon as its bundle is loaded — regardless of
+     * whether the key is actually rendered anywhere on the page.  Compare with
+     * `keyPositions` in the sidebar (and the content script's scan results),
+     * which only contain keys whose invisible DOM markers are currently visible.
+     */
+    private discoveredKeys;
+    /**
+     * Translation keys that i18next could not resolve, keyed by their composite
+     * `namespace:key` identifier.
+     *
+     * Populated via i18next's `missingKey` event.  Entries carry the languages
+     * for which the key was missing so the sidebar can surface them as actionable
+     * items needing a translation.
+     */
+    private missingKeys;
+    private isBrowser;
+    /**
+     * Set to `true` immediately before emitting a synthetic `languageChanged`
+     * event (i.e. one triggered by an override apply or discovery toggle, not
+     * by a real locale switch).  The `languageChanged` handler checks this flag
+     * and skips `syncWithExtension()` when it is set, breaking the feedback loop:
+     *
+     *   applyLocalOverride → i18n.emit('languageChanged') → languageChanged handler
+     *   → syncWithExtension → KEYS_DISCOVERED → service worker re-applies overrides
+     *   → UPDATE_REQUEST → applyLocalOverride → … (infinite loop)
+     */
+    private isSyntheticLanguageChange;
+    /**
+     * Set to `true` while {@link applyLocalOverride} is executing.  Guards both
+     * the `loaded` and `languageChanged` event handlers from calling
+     * `syncWithExtension()` — `addResourceBundle()` can internally fire the
+     * `loaded` event which was previously unguarded, creating an infinite loop:
+     *
+     *   applyLocalOverride → addResourceBundle → 'loaded' event
+     *   → syncWithExtension → KEYS_DISCOVERED → service worker re-applies overrides
+     *   → UPDATE_REQUEST → applyLocalOverride → … (infinite loop)
+     */
+    private isApplyingOverride;
+    /**
+     * Pending sync timer id.  Used by {@link scheduleSyncWithExtension} to
+     * coalesce multiple rapid sync requests (e.g. several `loaded` or
+     * `missingKey` events firing in quick succession) into a single
+     * `window.postMessage` call, preventing message flooding.
+     */
+    private pendingSyncTimer;
+    /** i18next namespace separator — read from options on init, defaults to ':'. */
+    private nsSeparator;
+    /** i18next key separator for nested keys — read from options on init, defaults to '.'. */
+    private keySeparator;
+    constructor();
+    init(i18nInstance: i18n): void;
+    /**
+     * Recursively flatten a (possibly nested) resource bundle into the
+     * discoveredKeys map.  Keys are joined with the configured keySeparator
+     * and prefixed with `ns<nsSeparator>` so identifiers match what the app
+     * passes to `t()`.
+     *
+     * Example:  bundle = { header: { title: "Hi" } }
+     *           → identifier = "common:header.title"  (with default separators)
+     */
+    private registerBundle;
+    private setupListeners;
+    /**
+     * Schedule a debounced sync with the extension.  Coalesces multiple rapid
+     * sync requests (e.g. several `loaded` or `missingKey` events firing in
+     * quick succession) into a single `window.postMessage` call.  Uses
+     * `setTimeout(0)` so the sync fires after the current call stack completes
+     * but before the next browser paint.
+     */
+    private scheduleSyncWithExtension;
+    private syncWithExtension;
+    /**
+     * Build a nested object from a dot-separated key path and a leaf value.
+     *
+     * Example: key = "header.faq", value = "LOL"
+     *   → { header: { faq: "LOL" } }
+     *
+     * This is required because i18next's addResourceBundle does NOT interpret
+     * dot-separated key strings as nested paths — it treats them as literal
+     * property names.  We must supply the correctly nested structure so the
+     * deep-merge preserves all sibling keys and the lookup via t() succeeds.
+     */
+    private buildNestedObject;
+    private applyLocalOverride;
+}
+export declare const leoTranslatorSupport: LeoTranslatorSupport;

package/dist/translator-support.js

@@ -0,0 +1,185 @@
+import { setDiscoveryActive as h } from "./post-processor.js";
+class c {
+  constructor() {
+    this.type = "3rdParty", this.i18n = null, this.discoveredKeys = /* @__PURE__ */ new Map(), this.missingKeys = /* @__PURE__ */ new Map(), this.isBrowser = typeof window < "u" && typeof document < "u", this.isSyntheticLanguageChange = !1, this.isApplyingOverride = !1, this.pendingSyncTimer = null, this.nsSeparator = ":", this.keySeparator = ".", this.isBrowser && this.setupListeners();
+  }
+  init(e) {
+    this.i18n = e;
+    const t = e.options;
+    typeof t.nsSeparator == "string" && (this.nsSeparator = t.nsSeparator), typeof t.keySeparator == "string" && (this.keySeparator = t.keySeparator), console.debug(
+      "[leo-translate:support] Initializing (nsSeparator=%s, keySeparator=%s)",
+      this.nsSeparator,
+      this.keySeparator
+    ), this.i18n.on("loaded", (s) => {
+      this.isApplyingOverride || (console.debug("[leo-translate:support] i18n loaded event:", s), Object.entries(s).forEach(([i, n]) => {
+        Object.keys(n).forEach((r) => {
+          var a;
+          const o = (a = this.i18n) == null ? void 0 : a.getResourceBundle(i, r);
+          console.debug(
+            `[leo-translate:support] loaded event — getResourceBundle(${i}, ${r}):`,
+            o,
+            "keys:",
+            o ? Object.keys(o) : "N/A"
+          ), o && typeof o == "object" && this.registerBundle(r, o);
+        });
+      }), this.scheduleSyncWithExtension());
+    }), this.i18n.on("languageChanged", (s) => {
+      var n, r;
+      if (this.isSyntheticLanguageChange || this.isApplyingOverride) return;
+      console.debug("[leo-translate:support] languageChanged event:", s), this.discoveredKeys.clear();
+      const i = (r = (n = this.i18n) == null ? void 0 : n.store) == null ? void 0 : r.data;
+      if (i && typeof i == "object") {
+        const o = i[s];
+        if (o)
+          for (const [a, l] of Object.entries(o))
+            l && typeof l == "object" && this.registerBundle(a, l);
+      }
+      this.scheduleSyncWithExtension();
+    }), this.i18n.on("missingKey", (s, i, n) => {
+      const r = `${i}${this.nsSeparator}${n}`;
+      console.debug(`[leo-translate:support] missingKey: ${r}`, s), this.missingKeys.set(r, {
+        ns: i,
+        key: n,
+        languages: [...s]
+      }), this.isApplyingOverride || this.scheduleSyncWithExtension();
+    });
+  }
+  /**
+   * Recursively flatten a (possibly nested) resource bundle into the
+   * discoveredKeys map.  Keys are joined with the configured keySeparator
+   * and prefixed with `ns<nsSeparator>` so identifiers match what the app
+   * passes to `t()`.
+   *
+   * Example:  bundle = { header: { title: "Hi" } }
+   *           → identifier = "common:header.title"  (with default separators)
+   */
+  registerBundle(e, t, s = "") {
+    console.debug(`[leo-translate:support] Registering bundle: ${e}`, t);
+    for (const [i, n] of Object.entries(t)) {
+      const r = s ? `${s}${this.keySeparator}${i}` : i;
+      if (typeof n == "string") {
+        const o = `${e}${this.nsSeparator}${r}`;
+        this.discoveredKeys.set(o, { ns: e, value: n });
+      } else n !== null && typeof n == "object" && !Array.isArray(n) && this.registerBundle(e, n, r);
+    }
+  }
+  setupListeners() {
+    window.addEventListener("message", (e) => {
+      var s;
+      if (((s = e.data) == null ? void 0 : s.source) !== "LEO_TRANSLATOR_EXTENSION") return;
+      console.debug("[leo-translate:support] Received message from extension:", e.data);
+      const t = e.data;
+      switch (t.type) {
+        case "LEO_TRANSLATOR_PING":
+          console.debug("[leo-translate:support] Received PING — responding with sync"), this.syncWithExtension();
+          break;
+        case "LEO_TRANSLATOR_UPDATE_REQUEST":
+          console.debug("[leo-translate:support] Received update request:", t.payload), t.payload && typeof t.payload.ns == "string" && typeof t.payload.key == "string" && typeof t.payload.value == "string" && this.applyLocalOverride(t.payload);
+          break;
+        case "LEO_TRANSLATOR_READY":
+          this.syncWithExtension();
+          break;
+        case "LEO_TRANSLATOR_TOGGLE_DISCOVERY": {
+          const i = !!t.active;
+          if (console.debug("[leo-translate:support] Received TOGGLE_DISCOVERY — active:", i), h(i), this.i18n) {
+            this.isSyntheticLanguageChange = !0;
+            try {
+              this.i18n.emit("languageChanged", this.i18n.language);
+            } finally {
+              this.isSyntheticLanguageChange = !1;
+            }
+          }
+          i && requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+              console.debug("[leo-translate:support] Re-render settled, posting SCAN_READY"), window.postMessage(
+                { source: "LEO_TRANSLATOR_SUPPORT", type: "LEO_TRANSLATOR_SCAN_READY" },
+                "*"
+              );
+            });
+          });
+          break;
+        }
+      }
+    });
+  }
+  /**
+   * Schedule a debounced sync with the extension.  Coalesces multiple rapid
+   * sync requests (e.g. several `loaded` or `missingKey` events firing in
+   * quick succession) into a single `window.postMessage` call.  Uses
+   * `setTimeout(0)` so the sync fires after the current call stack completes
+   * but before the next browser paint.
+   */
+  scheduleSyncWithExtension() {
+    this.pendingSyncTimer === null && (this.pendingSyncTimer = setTimeout(() => {
+      this.pendingSyncTimer = null, this.syncWithExtension();
+    }, 0));
+  }
+  syncWithExtension() {
+    var i;
+    if (!this.isBrowser) return;
+    const e = Array.from(this.discoveredKeys.entries()).map(([n, r]) => ({
+      id: n,
+      ...r
+    })), t = Array.from(this.missingKeys.entries()).map(([n, r]) => ({
+      id: n,
+      ...r
+    })), s = ((i = this.i18n) == null ? void 0 : i.language) ?? "";
+    console.debug(
+      `[leo-translate:support] Syncing ${e.length} discovered keys and ${t.length} missing keys with extension (language: ${s})`
+    ), window.postMessage(
+      {
+        source: "LEO_TRANSLATOR_SUPPORT",
+        type: "LEO_TRANSLATOR_KEYS_DISCOVERED",
+        payload: e,
+        missingKeys: t,
+        language: s
+      },
+      "*"
+    );
+  }
+  /**
+   * Build a nested object from a dot-separated key path and a leaf value.
+   *
+   * Example: key = "header.faq", value = "LOL"
+   *   → { header: { faq: "LOL" } }
+   *
+   * This is required because i18next's addResourceBundle does NOT interpret
+   * dot-separated key strings as nested paths — it treats them as literal
+   * property names.  We must supply the correctly nested structure so the
+   * deep-merge preserves all sibling keys and the lookup via t() succeeds.
+   */
+  buildNestedObject(e, t) {
+    const s = e.split(this.keySeparator), i = {};
+    let n = i;
+    for (let r = 0; r < s.length - 1; r++) {
+      const o = {};
+      n[s[r]] = o, n = o;
+    }
+    return n[s[s.length - 1]] = t, i;
+  }
+  applyLocalOverride(e) {
+    if (console.debug("[leo-translate:support] Applying local override:", e), !this.i18n) return;
+    this.isApplyingOverride = !0, this.isSyntheticLanguageChange = !0;
+    try {
+      this.i18n.addResourceBundle(
+        this.i18n.language,
+        e.ns,
+        this.buildNestedObject(e.key, e.value),
+        !0,
+        !0
+      ), this.i18n.emit("languageChanged", this.i18n.language);
+    } finally {
+      this.isSyntheticLanguageChange = !1, this.isApplyingOverride = !1;
+    }
+    const t = `${e.ns}${this.nsSeparator}${e.key}`;
+    this.discoveredKeys.set(t, {
+      ns: e.ns,
+      value: e.value
+    });
+  }
+}
+const g = new c();
+export {
+  c as LeoTranslatorSupport,
+  g as leoTranslatorSupport
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@webmobix/i18next-plugins",
+  "version": "0.0.1",
+  "description": "i18next backend and postProcessor plugins for Leo Translate",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "leo-translate": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./backend": {
+      "import": "./dist/backend.js",
+      "types": "./dist/backend/index.d.ts"
+    },
+    "./post-processor": {
+      "import": "./dist/post-processor.js",
+      "types": "./dist/post-processor/index.d.ts"
+    },
+    "./translator-support": {
+      "import": "./dist/translator-support.js",
+      "types": "./dist/translator-support/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "i18next": ">=23.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "i18next": "^24.0.0",
+    "typescript": "^5.4.5",
+    "vite": "^5.4.19",
+    "vite-plugin-dts": "^4.0.0"
+  },
+  "keywords": [
+    "i18next",
+    "react-i18next",
+    "backend",
+    "post-processor",
+    "leo-translate"
+  ],
+  "dependencies": {
+    "citty": "^0.2.1",
+    "open": "^11.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}