@embedpdf/plugin-i18n 2.15.0 → 3.0.0-next.0

package/dist/index.js

@@ -1,398 +1,263 @@
-import { BasePlugin, createEmitter, createScopedEmitter, arePropsEqual } from "@embedpdf/core";
-const enUS = {
-  code: "en",
-  name: "English",
-  translations: {
-    commands: {
-      zoom: {
-        in: "Zoom In",
-        out: "Zoom Out",
-        fitWidth: "Fit to Width",
-        fitPage: "Fit to Page",
-        automatic: "Automatic",
-        level: "Zoom Level ({level}%)",
-        inArea: "Zoom In Area"
-      },
-      fullscreen: {
-        enter: "Enter Full Screen",
-        exit: "Exit Full Screen"
-      },
-      rotate: {
-        clockwise: "Rotate Clockwise",
-        counterclockwise: "Rotate Counter-Clockwise"
-      },
-      menu: "Menu",
-      sidebar: "Sidebar",
-      search: "Search",
-      comment: "Comment",
-      download: "Download",
-      print: "Print",
-      openFile: "Open PDF",
-      save: "Save",
-      settings: "Settings",
-      view: "View",
-      annotate: "Annotate",
-      shapes: "Shapes",
-      redact: "Redact",
-      fillAndSign: "Fill and Sign",
-      form: "Form",
-      pan: "Pan",
-      pointer: "Pointer",
-      undo: "Undo",
-      redo: "Redo",
-      copy: "Copy",
-      screenshot: "Screenshot",
-      nextPage: "Next Page",
-      previousPage: "Previous Page"
-    }
-  }
-};
-const esES = {
-  code: "es",
-  name: "Español",
-  translations: {
-    commands: {
-      zoom: {
-        in: "Acercar",
-        out: "Alejar",
-        fitWidth: "Ajustar al ancho",
-        fitPage: "Ajustar a la página",
-        automatic: "Automático",
-        level: "Nivel de zoom ({level}%)",
-        inArea: "Acercar área"
-      },
-      fullscreen: {
-        enter: "Pantalla completa",
-        exit: "Salir de pantalla completa"
-      },
-      rotate: {
-        clockwise: "Girar a la derecha",
-        counterclockwise: "Girar a la izquierda"
-      },
-      menu: "Menú",
-      sidebar: "Barra lateral",
-      search: "Buscar",
-      comment: "Comentario",
-      download: "Descargar",
-      print: "Imprimir",
-      openFile: "Abrir PDF",
-      save: "Guardar",
-      settings: "Configuración",
-      view: "Ver",
-      annotate: "Anotar",
-      shapes: "Formas",
-      redact: "Redactar",
-      fillAndSign: "Rellenar y firmar",
-      form: "Formulario",
-      pan: "Desplazar",
-      pointer: "Puntero",
-      undo: "Deshacer",
-      redo: "Rehacer",
-      copy: "Copiar",
-      screenshot: "Captura de pantalla",
-      nextPage: "Página siguiente",
-      previousPage: "Página anterior"
-    }
-  }
-};
-const I18N_PLUGIN_ID = "i18n";
-const manifest = {
-  id: I18N_PLUGIN_ID,
-  name: "I18n Plugin",
-  version: "1.0.0",
-  provides: ["i18n"],
-  requires: [],
-  optional: [],
-  defaultConfig: {
-    defaultLocale: "en",
-    locales: [enUS, esES]
-  }
-};
-const SET_LOCALE = "I18N/SET_LOCALE";
-const REGISTER_LOCALE = "I18N/REGISTER_LOCALE";
-const setLocale = (locale) => ({
-  type: SET_LOCALE,
-  payload: locale
+import { createCapabilityToken, definePlugin } from "@embedpdf/core";
+//#region src/translate.ts
+/**
+* The pure lookup core — state in, string out. No platform access anywhere
+* (`Intl.PluralRules` is core ECMAScript, not DOM); this is the part that
+* ports to Rust verbatim.
+*/
+/** Walk a dotted path ('commands.zoom.in') through a dictionary tree. */
+function lookup(dict, key) {
+	if (!dict) return void 0;
+	let node = dict;
+	for (const part of key.split(".")) {
+		if (node === void 0 || typeof node === "string") return void 0;
+		node = node[part];
+	}
+	return node;
+}
+/** CLDR plural category for a count, with a safe fallback when the runtime
+*  lacks ICU data for the locale. */
+function pluralCategory(locale, count) {
+	try {
+		return new Intl.PluralRules(locale).select(count);
+	} catch {
+		return count === 1 ? "one" : "other";
+	}
+}
+/** A leaf hit is a string; a branch object needs a plural pick via `count`. */
+function resolveNode(node, locale, params) {
+	if (typeof node === "string") return node;
+	if (node !== void 0 && typeof params?.count === "number") {
+		const branch = node[pluralCategory(locale, params.count)] ?? node["other"];
+		if (typeof branch === "string") return branch;
+	}
+}
+/** Replace `{slot}` markers; unknown slots stay verbatim (visible in QA). */
+function interpolate(text, params) {
+	if (!params) return text;
+	return text.replace(/\{(\w+)\}/g, (match, slot) => params[slot] !== void 0 ? String(params[slot]) : match);
+}
+/**
+* Resolve a key against the state: current locale → fallback locale →
+* `options.fallback` (interpolated too) → the key itself.
+*/
+function translate(state, key, options) {
+	const { locale, fallbackLocale, locales } = state;
+	const text = resolveNode(lookup(locales[locale]?.translations, key), locale, options?.params) ?? resolveNode(lookup(locales[fallbackLocale]?.translations, key), fallbackLocale, options?.params);
+	if (text !== void 0) return {
+		text: interpolate(text, options?.params),
+		found: true
+	};
+	if (options?.fallback !== void 0) return {
+		text: interpolate(options.fallback, options.params),
+		found: false
+	};
+	return {
+		text: key,
+		found: false
+	};
+}
+//#endregion
+//#region src/capability.ts
+/**
+* The i18n capability — selectors (pure reads over state) + intents (the only
+* writers). Built synchronously in `createKernel()`, so `t()` works before the
+* engine exists — including inside the viewer shell's loading UI.
+*/
+function createI18nCapability(ctx, config) {
+	const warned = /* @__PURE__ */ new Set();
+	const warnOnce = (id, message) => {
+		if (warned.has(id)) return;
+		warned.add(id);
+		console.warn(message);
+	};
+	return {
+		t: (key, options) => {
+			const result = translate(ctx.getState(), key, options);
+			if (!result.found && options?.fallback === void 0) warnOnce(`key:${key}`, `[i18n] missing translation "${key}" (locale: ${ctx.getState().locale})`);
+			return result.text;
+		},
+		locale: () => ctx.getState().locale,
+		dir: () => {
+			const { locales, locale } = ctx.getState();
+			return locales[locale]?.dir ?? "ltr";
+		},
+		locales: () => {
+			const { locales } = ctx.getState();
+			const known = Object.values(locales).map((locale) => ({
+				code: locale.code,
+				name: locale.name,
+				dir: locale.dir ?? "ltr",
+				loaded: true
+			}));
+			for (const code of Object.keys(config.loaders ?? {})) if (!locales[code]) known.push({
+				code,
+				name: code,
+				dir: "ltr",
+				loaded: false
+			});
+			return known;
+		},
+		loading: () => ctx.getState().loading,
+		setLocale: (code) => {
+			if (ctx.getState().locales[code]) ctx.dispatch({
+				type: "I18N/SET_LOCALE",
+				locale: code
+			});
+			else if (config.loaders?.[code]) ctx.dispatch({
+				type: "I18N/LOAD_STARTED",
+				locale: code
+			});
+			else warnOnce(`locale:${code}`, `[i18n] unknown locale "${code}" — not registered and no loader configured`);
+		},
+		registerLocale: (locale) => ctx.dispatch({
+			type: "I18N/REGISTER_LOCALE",
+			locale
+		})
+	};
+}
+//#endregion
+//#region src/effects.ts
+/**
+* The plugin's ONE side-effect: fetching lazy locale packs. State-driven — a
+* load is `state.loading`, set by the capability (a switch to a lazy pack) or
+* by the initial state (a lazy startup locale), so a load requested before
+* effects ran is picked up here and nothing is lost to boot ordering.
+*/
+function registerI18nEffects(config) {
+	return (ctx) => {
+		const load = (code) => {
+			const loader = config.loaders?.[code];
+			if (!loader) return;
+			loader().then((locale) => {
+				ctx.dispatch({
+					type: "I18N/REGISTER_LOCALE",
+					locale
+				});
+				if (ctx.getState().loading === code) ctx.dispatch({
+					type: "I18N/SET_LOCALE",
+					locale: locale.code
+				});
+			}, () => ctx.dispatch({
+				type: "I18N/LOAD_FAILED",
+				locale: code
+			}));
+		};
+		const pending = ctx.getState().loading;
+		if (pending) load(pending);
+		ctx.watch(() => ctx.getState().loading, (code) => {
+			if (code) load(code);
+		});
+	};
+}
+//#endregion
+//#region src/reducer.ts
+/**
+* Pure and serializable — locale packs are data, so they live HERE, not in a
+* side-table. One source of truth: `t()` is a pure function of this state and
+* reactivity rides the kernel's one change stream (no emitters).
+*/
+function initialI18nState(config) {
+	const fallbackLocale = config.fallbackLocale ?? "en";
+	const locales = {};
+	for (const locale of config.locales ?? []) locales[locale.code] = locale;
+	const locale = config.locale ?? fallbackLocale;
+	return {
+		locale,
+		fallbackLocale,
+		locales,
+		loading: !locales[locale] && config.loaders?.[locale] !== void 0 ? locale : null
+	};
+}
+function i18nReducer(state, action) {
+	switch (action.type) {
+		case "I18N/SET_LOCALE":
+			if (!state.locales[action.locale]) return state;
+			if (state.locale === action.locale && state.loading === null) return state;
+			return {
+				...state,
+				locale: action.locale,
+				loading: null
+			};
+		case "I18N/REGISTER_LOCALE": return {
+			...state,
+			locales: {
+				...state.locales,
+				[action.locale.code]: action.locale
+			}
+		};
+		case "I18N/LOAD_STARTED": return state.loading === action.locale ? state : {
+			...state,
+			loading: action.locale
+		};
+		case "I18N/LOAD_FAILED": return state.loading === action.locale ? {
+			...state,
+			loading: null
+		} : state;
+		default: return state;
+	}
+}
+//#endregion
+//#region src/types.ts
+const I18nToken = createCapabilityToken("i18n");
+//#endregion
+//#region src/i18n.plugin.ts
+/**
+* The i18n plugin: workspace-scoped (locale is a workspace concern) with NO
+* dependencies — engine-free, DOM-free. Its capability is built synchronously
+* in `createKernel()`, so the shell translates from the first frame, while
+* the engine is still booting.
+*/
+const i18nPlugin = (config = {}) => definePlugin({
+	id: "i18n",
+	scope: "workspace",
+	token: I18nToken,
+	initialState: () => initialI18nState(config),
+	reduce: i18nReducer,
+	capability: (ctx) => createI18nCapability(ctx, config),
+	effects: registerI18nEffects(config)
 });
-const registerLocale = (locale) => ({
-  type: REGISTER_LOCALE,
-  payload: locale
-});
-const _I18nPlugin = class _I18nPlugin extends BasePlugin {
-  constructor(id, registry, config) {
-    super(id, registry);
-    this.locales = /* @__PURE__ */ new Map();
-    this.paramResolvers = /* @__PURE__ */ new Map();
-    this.paramsCache = /* @__PURE__ */ new Map();
-    this.localeChange$ = createEmitter();
-    this.paramsChanged$ = createScopedEmitter((documentId, data) => ({ documentId, ...data }), { cache: false });
-    this.config = config;
-    config.locales.forEach((locale) => {
-      this.locales.set(locale.code, locale);
-      this.dispatch(registerLocale(locale.code));
-    });
-    if (config.paramResolvers) {
-      Object.entries(config.paramResolvers).forEach(([key, resolver]) => {
-        this.paramResolvers.set(key, resolver);
-      });
-    }
-    this.dispatch(setLocale(config.defaultLocale));
-    this.registry.getStore().subscribe((_action, newState) => {
-      this.detectParamChanges(newState);
-    });
-  }
-  async initialize() {
-    this.logger.info("I18nPlugin", "Initialize", "I18n plugin initialized");
-  }
-  async destroy() {
-    this.localeChange$.clear();
-    this.paramsChanged$.clear();
-    this.paramResolvers.clear();
-    this.paramsCache.clear();
-    super.destroy();
-  }
-  onDocumentClosed(documentId) {
-    this.paramsCache.delete(documentId);
-    this.paramsChanged$.clearScope(documentId);
-    this.logger.debug(
-      "I18nPlugin",
-      "DocumentClosed",
-      `Cleaned up params cache for document: ${documentId}`
-    );
-  }
-  buildCapability() {
-    return {
-      t: (key, options) => this.translate(key, options),
-      forDocument: (documentId) => this.createI18nScope(documentId),
-      registerParamResolver: (key, resolver) => this.registerParamResolver(key, resolver),
-      unregisterParamResolver: (key) => this.unregisterParamResolver(key),
-      setLocale: (locale) => this.setLocale(locale),
-      getLocale: () => this.state.currentLocale,
-      getAvailableLocales: () => [...this.state.availableLocales],
-      getLocaleInfo: (code) => this.locales.get(code) ?? null,
-      registerLocale: (locale) => this.registerLocale(locale),
-      hasLocale: (code) => this.locales.has(code),
-      onLocaleChange: this.localeChange$.on,
-      onParamsChanged: this.paramsChanged$.onGlobal
-    };
-  }
-  // ─────────────────────────────────────────────────────────
-  // Document Scoping
-  // ─────────────────────────────────────────────────────────
-  createI18nScope(documentId) {
-    return {
-      t: (key, options) => this.translate(key, { documentId, ...options }),
-      onParamsChanged: this.paramsChanged$.forScope(documentId)
-    };
-  }
-  // ─────────────────────────────────────────────────────────
-  // Translation Logic
-  // ─────────────────────────────────────────────────────────
-  translate(key, options) {
-    const locale = this.locales.get(this.state.currentLocale);
-    const fallbackLocale = this.config.fallbackLocale ? this.locales.get(this.config.fallbackLocale) : null;
-    let value = this.getNestedValue(locale == null ? void 0 : locale.translations, key);
-    if (!value && fallbackLocale) {
-      value = this.getNestedValue(fallbackLocale.translations, key);
-    }
-    if (!value) {
-      if (options == null ? void 0 : options.fallback) {
-        value = options.fallback;
-      } else {
-        this.logger.warn(
-          "I18nPlugin",
-          "MissingTranslation",
-          `Translation not found for key: ${key}`
-        );
-        return key;
-      }
-    }
-    let params = options == null ? void 0 : options.params;
-    if (!params && this.paramResolvers.has(key)) {
-      params = this.resolveParams(key, options == null ? void 0 : options.documentId);
-    }
-    return this.interpolate(value, params);
-  }
-  resolveParams(key, documentId) {
-    const resolver = this.paramResolvers.get(key);
-    if (!resolver) return void 0;
-    const state = this.registry.getStore().getState();
-    try {
-      return resolver({ state, documentId });
-    } catch (error) {
-      this.logger.error(
-        "I18nPlugin",
-        "ParamResolverError",
-        `Error resolving params for key "${key}":`,
-        error
-      );
-      return void 0;
-    }
-  }
-  getNestedValue(obj, path) {
-    if (!obj) return void 0;
-    const parts = path.split(".");
-    let current = obj;
-    for (const part of parts) {
-      if (current === void 0 || current === null) return void 0;
-      current = current[part];
-    }
-    return typeof current === "string" ? current : void 0;
-  }
-  interpolate(str, params) {
-    if (!params) return str;
-    return str.replace(/\{(\w+)\}/g, (match, key) => {
-      const value = params[key];
-      return value !== void 0 ? String(value) : match;
-    });
-  }
-  // ─────────────────────────────────────────────────────────
-  // Smart Param Change Detection
-  // ─────────────────────────────────────────────────────────
-  detectParamChanges(newState) {
-    const documentIds = Object.keys(newState.core.documents);
-    documentIds.forEach((documentId) => {
-      this.detectDocumentParamChanges(documentId, newState);
-    });
-  }
-  detectDocumentParamChanges(documentId, newState) {
-    const previousCache = this.paramsCache.get(documentId);
-    const changedKeys = [];
-    this.paramResolvers.forEach((resolver, key) => {
-      try {
-        const newParams = resolver({ state: newState, documentId });
-        const prevParams = previousCache == null ? void 0 : previousCache.get(key);
-        if (!arePropsEqual(prevParams, newParams)) {
-          changedKeys.push(key);
-          if (!this.paramsCache.has(documentId)) {
-            this.paramsCache.set(documentId, /* @__PURE__ */ new Map());
-          }
-          this.paramsCache.get(documentId).set(key, newParams);
-        }
-      } catch (error) {
-        this.logger.error(
-          "I18nPlugin",
-          "ParamDetectionError",
-          `Error detecting param changes for key "${key}":`,
-          error
-        );
-      }
-    });
-    if (changedKeys.length > 0) {
-      this.paramsChanged$.emit(documentId, { changedKeys });
-      this.logger.debug(
-        "I18nPlugin",
-        "ParamsChanged",
-        `Translation params changed for document ${documentId}:`,
-        changedKeys
-      );
-    }
-  }
-  // ─────────────────────────────────────────────────────────
-  // Param Resolver Management
-  // ─────────────────────────────────────────────────────────
-  registerParamResolver(key, resolver) {
-    if (this.paramResolvers.has(key)) {
-      this.logger.warn(
-        "I18nPlugin",
-        "ResolverOverwrite",
-        `Param resolver for "${key}" already exists and will be overwritten`
-      );
-    }
-    this.paramResolvers.set(key, resolver);
-    this.paramsCache.forEach((docCache) => {
-      docCache.delete(key);
-    });
-    this.logger.debug("I18nPlugin", "ResolverRegistered", `Param resolver registered for: ${key}`);
-  }
-  unregisterParamResolver(key) {
-    if (this.paramResolvers.delete(key)) {
-      this.paramsCache.forEach((docCache) => {
-        docCache.delete(key);
-      });
-      this.logger.debug(
-        "I18nPlugin",
-        "ResolverUnregistered",
-        `Param resolver unregistered for: ${key}`
-      );
-    }
-  }
-  // ─────────────────────────────────────────────────────────
-  // Locale Management
-  // ─────────────────────────────────────────────────────────
-  setLocale(locale) {
-    if (!this.locales.has(locale)) {
-      this.logger.warn("I18nPlugin", "LocaleNotFound", `Locale '${locale}' is not registered`);
-      return;
-    }
-    const previousLocale = this.state.currentLocale;
-    if (previousLocale === locale) return;
-    this.dispatch(setLocale(locale));
-    this.localeChange$.emit({
-      previousLocale,
-      currentLocale: locale
-    });
-    this.logger.info("I18nPlugin", "LocaleChanged", `Locale changed to: ${locale}`);
-  }
-  registerLocale(locale) {
-    if (this.locales.has(locale.code)) {
-      this.logger.warn(
-        "I18nPlugin",
-        "LocaleAlreadyRegistered",
-        `Locale '${locale.code}' is already registered`
-      );
-      return;
-    }
-    this.locales.set(locale.code, locale);
-    this.dispatch(registerLocale(locale.code));
-    this.logger.info("I18nPlugin", "LocaleRegistered", `Locale registered: ${locale.code}`);
-  }
-};
-_I18nPlugin.id = "i18n";
-let I18nPlugin = _I18nPlugin;
-const initialState = {
-  currentLocale: "en",
-  availableLocales: []
-};
-const i18nReducer = (state = initialState, action) => {
-  switch (action.type) {
-    case SET_LOCALE: {
-      const locale = action.payload;
-      if (!state.availableLocales.includes(locale)) {
-        console.warn(`I18nPlugin: Locale '${locale}' not available`);
-        return state;
-      }
-      return {
-        ...state,
-        currentLocale: locale
-      };
-    }
-    case REGISTER_LOCALE: {
-      const locale = action.payload;
-      if (state.availableLocales.includes(locale)) {
-        return state;
-      }
-      return {
-        ...state,
-        availableLocales: [...state.availableLocales, locale]
-      };
-    }
-    default:
-      return state;
-  }
-};
-const I18nPluginPackage = {
-  manifest,
-  create: (registry, config) => new I18nPlugin(I18N_PLUGIN_ID, registry, config),
-  reducer: i18nReducer,
-  initialState
-};
-export {
-  I18N_PLUGIN_ID,
-  I18nPlugin,
-  I18nPluginPackage,
-  enUS,
-  esES,
-  manifest
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+//#region src/negotiate.ts
+/**
+* Pure BCP-47 locale negotiation — strings in, string out. The plugin never
+* reads the platform; the EMBEDDER feeds it whatever request list its
+* environment offers:
+*
+* ```ts
+* // browser shell:  negotiateLocale(['en', 'es', 'ar'], navigator.languages)
+* // server render:  negotiateLocale(codes, parseAcceptLanguage(header))
+* ```
+*
+* Matching, per requested code in preference order:
+*   1. exact match (case-insensitive):        'es-MX' → 'es-MX'
+*   2. request narrowed to its language:      'en-GB' → 'en'
+*   3. any available dialect of the language: 'zh'    → 'zh-Hans'
+*
+* Returns the matched code exactly as it appears in `available`, or null.
+*/
+function negotiateLocale(available, requested) {
+	const byCanon = /* @__PURE__ */ new Map();
+	for (const code of available) {
+		const canon = code.toLowerCase();
+		if (!byCanon.has(canon)) byCanon.set(canon, code);
+	}
+	const languageOf = (code) => code.toLowerCase().split("-")[0];
+	for (const want of requested) {
+		const exact = byCanon.get(want.toLowerCase());
+		if (exact !== void 0) return exact;
+	}
+	for (const want of requested) {
+		const narrowed = byCanon.get(languageOf(want));
+		if (narrowed !== void 0) return narrowed;
+	}
+	for (const want of requested) {
+		const language = languageOf(want);
+		for (const [canon, original] of byCanon) if (languageOf(canon) === language) return original;
+	}
+	return null;
+}
+//#endregion
+export { I18nToken, i18nPlugin, interpolate, negotiateLocale, translate };
+
+//# sourceMappingURL=index.js.map