slicejs-web-framework 4.1.0 → 4.2.0

package/Slice/Components/Structural/Translator/Translator.js

@@ -0,0 +1,1111 @@
+import {
+   IntlCache,
+   directionOf,
+   formatMessage,
+   isPlainObject,
+   isPluralMessage,
+   lookup,
+   matchLocale,
+   mergeMessages,
+} from './messages.js';
+import { TranslationListRef, TranslationRef, containsMarker, resolveMarkers } from './markers.js';
+import { localize } from './localized.js';
+import { resolveContent } from './content.js';
+import { translateTree } from './dom.js';
+import { isExternalHref, localeOfUrl, localizePath, normalizeLocalePrefix, splitLocalePath } from './localePath.js';
+
+const STORAGE_KEY = 'slice:locale';
+const WRAPPED = Symbol('slice.translator.wrapped');
+
+/**
+ * @typedef {Object} TranslatorConfig
+ * @property {boolean} [enabled]
+ * @property {string} [defaultLocale]
+ * @property {string|null} [fallbackLocale]
+ * @property {string[]} [locales]
+ * @property {string} [path]
+ * @property {boolean} [saveLocally]
+ * @property {boolean} [useBrowserLocale]
+ * @property {false|'always'|'except-default'} [localePrefix]
+ */
+
+/**
+ * slice.translator — translations and locale formatting as part of the framework.
+ *
+ *   slice.t('orders.count', { count: 3 })            → '3 pedidos'
+ *   <h1 data-t="home.title"></h1>                    → translated, and kept translated
+ *   slice.build('Button', { value: slice.t.ref('orders.save') })
+ *
+ * Texts in the DOM are *marked*, not written: any element with `data-t` (in a template, in
+ * App/index.html, or created later from JS) is translated when it enters the document and
+ * again on every locale change. Changing a `data-t` or `data-t-*` attribute re-translates
+ * that element. Props passed as `key()` markers are resolved before the component sees them
+ * and assigned again on a locale change. `watch()` covers what lives outside the DOM.
+ *
+ * With `enabled: false` nothing is loaded or observed: `t()` returns the key, markers resolve
+ * to their key, `format.*` uses the browser's language.
+ */
+export default class Translator {
+   /**
+    * @param {TranslatorConfig} [config]
+    */
+   constructor(config = {}) {
+      const options = config && typeof config === 'object' ? config : {};
+      const browserLocale = Translator.browserLocales()[0] || 'en';
+      const clean = (value) => (typeof value === 'string' && value.trim() ? value.trim() : '');
+      const wantsEnabled = options.enabled === true;
+      const configuredDefault = clean(options.defaultLocale);
+
+      /** @type {boolean} */
+      this.enabled = wantsEnabled && configuredDefault !== '';
+      if (wantsEnabled && !this.enabled) {
+         // The schema says enabled needs defaultLocale, but the runtime must say so too:
+         // silently booting with keys everywhere is the worst failure mode.
+         console.error('[slice.translator] "enabled": true requires a non-empty "defaultLocale"; the translator stays disabled.');
+      }
+      /** @type {string} */
+      this.defaultLocale = this.enabled ? configuredDefault : browserLocale;
+
+      const declared = Array.isArray(options.locales) ? options.locales.map(clean).filter(Boolean) : [];
+      // Dedupe case-insensitively: "ES" and "es" are the same language, and a duplicate
+      // would fetch a file that does not exist while the real one is fine.
+      const seen = new Map();
+      for (const locale of [this.defaultLocale, ...declared]) {
+         const key = locale.toLowerCase();
+         if (!seen.has(key)) seen.set(key, locale);
+      }
+      /** @type {readonly string[]} */
+      this.locales = Object.freeze([...seen.values()]);
+      const configuredFallback = clean(options.fallbackLocale);
+      /** @type {string|null} */
+      this.fallbackLocale =
+         this.enabled && configuredFallback && configuredFallback.toLowerCase() !== this.defaultLocale.toLowerCase()
+            ? configuredFallback
+            : null;
+      if (this.fallbackLocale && !this.locales.some((locale) => locale.toLowerCase() === this.fallbackLocale.toLowerCase())) {
+         // The fallback is loaded like any locale; listing it keeps setLocale() consistent.
+         this.locales = Object.freeze([...this.locales, this.fallbackLocale]);
+      }
+
+      const rawPath = clean(options.path) || '/locales';
+      const cleanedPath = rawPath.replace(/^\/+|\/+$/g, '');
+      // A relative path would resolve against the current URL (`/en/locales/...`), so the
+      // leading slash is not cosmetic.
+      this.path = cleanedPath ? `/${cleanedPath}` : '/locales';
+      this.saveLocally = options.saveLocally === true;
+      this.useBrowserLocale = options.useBrowserLocale === true;
+      /** @type {false|'always'|'except-default'} the locale in the URL (§7) */
+      this.localePrefix = this.enabled ? normalizeLocalePrefix(options.localePrefix) : false;
+
+      /** @type {string} */
+      this.locale = this.defaultLocale;
+
+      /** @private @type {Map<string, Record<string, any>>} */
+      this._app = new Map();
+      /** @private @type {Map<string, Record<string, any>>} */
+      this._defaults = new Map();
+      /** @private @type {Set<string>} files merged, as `locale` or `locale/namespace` */
+      this._loaded = new Set();
+      /** @private @type {Map<string, Promise<void>>} */
+      this._requests = new Map();
+      /** @private @type {Set<string>} */
+      this._namespaces = new Set();
+      /** @private @type {Map<string, Promise<Record<string, any>|undefined>>} content document → load */
+      this._content = new Map();
+      /** @private @type {Map<string, any>} `${document}|${locale}` → resolved content */
+      this._contentCache = new Map();
+      /** @private */
+      this._version = 0;
+      /** @private texts are not written (nor missing keys reported) before the first load */
+      this._ready = !this.enabled;
+
+      /** @private */
+      this._intl = new IntlCache();
+      /** @private @type {Set<string>} */
+      this._warned = new Set();
+      /** @type {boolean} debugger switch: `t()` returns the key instead of the text */
+      this.showKeys = false;
+
+      // DOM
+      /** @private @type {WeakMap<Element, string>} */
+      this._applied = new WeakMap();
+      /** @private @type {WeakMap<Element, Map<string, Element>>} */
+      this._slots = new WeakMap();
+      /** @private @type {MutationObserver|null} */
+      this._observer = null;
+      /** @private */
+      this._dom = {
+         t: (key, params) => this.t(key, params),
+         signature: () => `${this.locale}#${this._version}#${this.showKeys ? 'keys' : 'text'}`,
+         applied: this._applied,
+         slots: this._slots,
+         warn: (message) => this._warnOnce(message, message),
+      };
+
+      // Props
+      /** @private @type {WeakMap<object, Map<string, any>>} component → prop → raw value with markers */
+      this._markerProps = new WeakMap();
+      /** @private @type {WeakMap<Function, Set<string>>} class → props whose setter resolves markers */
+      this._wrappedProps = new WeakMap();
+      /** @private */
+      this._refreshing = false;
+
+      // watch()
+      /** @private @type {Map<object, Set<(locale: string, previous: string) => void>>} */
+      this._watchers = new Map();
+      /** @private @type {Set<(locale: string, previous: string) => void>} */
+      this._globalWatchers = new Set();
+
+      /** @private */
+      this._refreshScheduled = false;
+      /** @private */
+      this._switchId = 0;
+
+      this.format = this._createFormat();
+   }
+
+   /**
+    * The browser's preferred languages, most preferred first.
+    * @returns {string[]}
+    */
+   static browserLocales() {
+      if (typeof navigator === 'undefined') return [];
+      const list = Array.isArray(navigator.languages) && navigator.languages.length ? navigator.languages : [navigator.language];
+      return list.filter((l) => typeof l === 'string' && l);
+   }
+
+   // ───────────────────────────── Start ─────────────────────────────
+
+   /**
+    * Pick the starting locale, load its dictionaries (and the fallback's), translate the
+    * document and start watching it. A failed load is logged, not thrown: the app boots
+    * showing keys rather than not booting.
+    * @returns {Promise<void>}
+    */
+   async init() {
+      if (!this.enabled) return;
+      this.locale = this.initialLocale();
+      try {
+         await this._loadLocale(this.locale);
+      } catch (error) {
+         this._log('error', `Could not load the dictionary for "${this.locale}"`, error);
+      }
+      this._ready = true;
+      this._applyDocumentLocale();
+      // With "always", `/pricing` becomes `/es/pricing`; with "except-default",
+      // `/es/pricing` (the default locale) becomes `/pricing`. Before the router starts.
+      this.syncUrl();
+      this.apply();
+      this._observe();
+   }
+
+   /**
+    * The locale to start with. With `localePrefix`, the URL decides: its prefix, or — with
+    * "except-default" — the default locale when there is none. Otherwise (and for
+    * "prefix" at an unprefixed URL): the saved choice (`saveLocally`) → the browser's
+    * language (`useBrowserLocale`) → `defaultLocale`.
+    * @returns {string}
+    */
+   initialLocale() {
+      if (!this.enabled) return this.defaultLocale;
+      if (this.localePrefix && typeof location !== 'undefined') {
+         // Only an explicit prefix decides on the first load. Under "except-default" an
+         // unprefixed URL means "no choice yet", so saveLocally/useBrowserLocale still run.
+         const { locale: fromUrl } = splitLocalePath(location.pathname, this.locales);
+         if (fromUrl) return fromUrl;
+      }
+      if (this.saveLocally) {
+         const saved = matchLocale(this._readSaved(), /** @type {string[]} */ ([...this.locales]));
+         if (saved) return saved;
+      }
+      if (this.useBrowserLocale) {
+         for (const candidate of Translator.browserLocales()) {
+            const match = matchLocale(candidate, /** @type {string[]} */ ([...this.locales]));
+            if (match) return match;
+         }
+      }
+      return this.defaultLocale;
+   }
+
+   /**
+    * Stop observing the document. Used by tests and by an app tearing Slice down.
+    * @returns {void}
+    */
+   destroy() {
+      this._observer?.disconnect();
+      this._observer = null;
+      this._watchers.clear();
+      this._globalWatchers.clear();
+   }
+
+   // ───────────────────────────── Messages ─────────────────────────────
+
+   /**
+    * Translate a key. Lookup: the app's dictionaries → the library defaults, for the active
+    * locale and then for `fallbackLocale`; when nothing matches, the key itself.
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @returns {string}
+    */
+   t(key, params) {
+      if (typeof key !== 'string' || key === '') return String(key ?? '');
+      if (!this.enabled) return key;
+      if (this.showKeys) return key;
+
+      for (const locale of this._chain()) {
+         const entry = this._entry(key, locale);
+         if (entry === undefined) continue;
+         const text = formatMessage(entry, params, locale, this._intl, {
+            onMissingParam: (name) => this._warnOnce(`param:${locale}:${key}:${name}`, `"${key}" (${locale}) uses {${name}} but no "${name}" param was given`),
+            onMissingCount: () => this._warnOnce(`count:${locale}:${key}`, `"${key}" (${locale}) is a plural message: pass { count }`),
+         });
+         if (text === null) {
+            this._warnOnce(`group:${key}`, `"${key}" is a group of messages, not a message`);
+            continue;
+         }
+         return text;
+      }
+
+      if (this._ready) {
+         this._warnOnce(`missing:${this.locale}:${key}`, `Missing translation "${key}" for "${this.locale}"${this.fallbackLocale ? ` (and "${this.fallbackLocale}")` : ''}`);
+      }
+      return key;
+   }
+
+   /**
+    * Translate a list value: an array of messages (strings or plurals) or records.
+    * String items are formatted with `params`; objects are returned as-is (content lists
+    * carry their own localized records). A missing entry or a non-array returns `[]` and
+    * warns once. With `showKeys`, string items become `key.<index>`.
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @returns {any[]}
+    */
+   list(key, params) {
+      if (typeof key !== 'string' || key === '') return [];
+      if (!this.enabled) return [];
+
+      for (const locale of this._chain()) {
+         const entry = this._entry(key, locale);
+         if (entry === undefined) continue;
+         if (!Array.isArray(entry)) {
+            this._warnOnce(`list-shape:${key}`, `"${key}" is not a list: slice.t.list() expects an array`);
+            return [];
+         }
+         return entry.map((item, index) => {
+            if (this.showKeys) {
+               return typeof item === 'string' || isPluralMessage(item) ? `${key}.${index}` : item;
+            }
+            if (typeof item === 'string' || isPluralMessage(item)) {
+               const text = formatMessage(item, params, locale, this._intl, {
+                  onMissingParam: (name) => this._warnOnce(`param:${locale}:${key}:${index}:${name}`, `"${key}.${index}" (${locale}) uses {${name}} but no "${name}" param was given`),
+                  onMissingCount: () => this._warnOnce(`count:${locale}:${key}:${index}`, `"${key}.${index}" (${locale}) is a plural message: pass { count }`),
+               });
+               return text === null ? item : text;
+            }
+            return item;
+         });
+      }
+
+      if (this._ready) {
+         this._warnOnce(`list-missing:${this.locale}:${key}`, `Missing list "${key}" for "${this.locale}"`);
+      }
+      return [];
+   }
+
+   /**
+    * Resolve a localized content value (`{ en: …, es: … }`) for the active locale.
+    * Arrays and plain objects are walked recursively; it never looks up dictionary keys.
+    * @param {any} value
+    * @returns {any}
+    */
+   localized(value) {
+      return localize(value, {
+         locale: this.locale,
+         fallbackLocale: this.fallbackLocale,
+         defaultLocale: this.defaultLocale,
+         locales: this.locales,
+      });
+   }
+
+   /**
+    * Load a content document (`<path>/content/<name>.json`) and resolve it for the active
+    * locale: every `copy` becomes its branch, nested nodes are flattened. The document is
+    * fetched once; the resolution is cached per locale. Returns `null` when it cannot load.
+    * @param {string} name
+    * @returns {Promise<any|null>}
+    */
+   async content(name) {
+      const id = String(name ?? '').trim().replace(/^\/+|\/+$/g, '');
+      const valid = id && /^[a-z0-9][a-z0-9/_-]*$/i.test(id) && !id.split('/').some((segment) => !segment || segment === '.' || segment === '..');
+      if (!valid) {
+         this._log('warn', `slice.t.content() needs a document name such as "experience" (got "${name}")`);
+         return null;
+      }
+      if (!this.enabled) {
+         this._warnOnce('content-disabled', 'slice.t.content() needs the translator enabled');
+         return null;
+      }
+
+      const document = await this._loadContent(id);
+      if (document === undefined) return null;
+
+      const locale = this.locale;
+      const cacheKey = `${id}|${locale}`;
+      if (this._contentCache.has(cacheKey)) return this._contentCache.get(cacheKey);
+
+      const options = {
+         locale,
+         fallbackLocale: this.fallbackLocale,
+         defaultLocale: this.defaultLocale,
+         locales: this.locales,
+      };
+      const resolved = resolveContent(document, (value) => localize(value, options), {
+         onMissing: (path) => this._warnOnce(
+            `content-copy:${id}:${locale}:${path}`,
+            `Content "${id}" has a "copy" at "${path}" without "${locale}" (or its fallback)`
+         ),
+         onInvalid: (path) => this._warnOnce(
+            `content-invalid:${id}:${path}`,
+            `Content "${id}" has a scalar/array "copy" at "${path}" next to structural fields; use an object branch (e.g. { "title": … })`
+         ),
+      });
+      this._contentCache.set(cacheKey, resolved);
+      return resolved;
+   }
+
+   /**
+    * Debugger switch: show keys instead of texts, everywhere, without changing the locale.
+    * Re-translates the document and marker props on both transitions.
+    * @param {boolean} enabled
+    * @returns {boolean} the new state
+    */
+   setShowKeys(enabled) {
+      const next = enabled === true;
+      if (next === this.showKeys) return this.showKeys;
+      this.showKeys = next;
+      this._version++;
+      this._refresh();
+      return this.showKeys;
+   }
+
+   /**
+    * Whether `key` is a message in `locale` (default: the active one), app or defaults layer.
+    * The fallback is not consulted.
+    * @param {string} key
+    * @param {string} [locale]
+    * @returns {boolean}
+    */
+   has(key, locale = this.locale) {
+      const entry = this._entry(key, locale);
+      return typeof entry === 'string' || isPluralMessage(entry);
+   }
+
+   /**
+    * Merge messages at runtime. With `{ defaults: true }` they go to a lower layer that never
+    * overrides the app's dictionaries — how a component library ships its own texts.
+    * @param {string} locale
+    * @param {Record<string, any>} messages
+    * @param {{ defaults?: boolean }} [options]
+    * @returns {void}
+    */
+   add(locale, messages, options = {}) {
+      if (typeof locale !== 'string' || !isPlainObject(messages)) return;
+      const layer = options.defaults ? this._defaults : this._app;
+      if (!layer.has(locale)) layer.set(locale, {});
+      mergeMessages(/** @type {Record<string, any>} */ (layer.get(locale)), messages);
+      this._version++;
+      this._scheduleRefresh();
+   }
+
+   /**
+    * Load a namespace (`/locales/<locale>/<namespace>.json`) for the active locale and the
+    * fallback. It stays loaded: later locale changes load it too. Elements and props that
+    * use its keys update when it arrives.
+    * @param {string} namespace
+    * @returns {Promise<void>}
+    */
+   async load(namespace) {
+      if (typeof namespace !== 'string' || !namespace) return;
+      this._namespaces.add(namespace);
+      if (!this.enabled) return;
+      const switchId = this._switchId;
+      const localeAtStart = this.locale;
+      const [active, fallback] = await Promise.allSettled([
+         this._fetch(this.locale, namespace),
+         this.fallbackLocale ? this._fetch(this.fallbackLocale, namespace) : Promise.resolve(),
+      ]);
+      if (fallback.status === 'rejected') {
+         this._log('warn', `Could not load "${namespace}" for the fallback "${this.fallbackLocale}"`, fallback.reason);
+      }
+      // A locale switch finished while the namespace was in flight: fetch it for the new
+      // locale too, or the screen would keep the previous language until the next switch.
+      if (switchId !== this._switchId && this.locale !== localeAtStart) {
+         await this._fetch(this.locale, namespace).catch((error) =>
+            this._log('warn', `Could not load "${namespace}" for "${this.locale}"`, error)
+         );
+         if (this.fallbackLocale && this.fallbackLocale !== this.locale) {
+            await this._fetch(this.fallbackLocale, namespace).catch(() => {});
+         }
+      }
+      this._refresh();
+      if (active.status === 'rejected') throw active.reason;
+   }
+
+   /**
+    * Change the active locale. Loads what it needs first: on failure the locale does not
+    * change and the promise rejects. Then updates `<html lang|dir>`, saves the choice,
+    * re-translates the document, re-assigns marker props, re-applies the route's metadata,
+    * calls `watch()` callbacks and emits `translator:change`.
+    * @param {string} locale
+    * @returns {Promise<string>} the active locale
+    */
+   async setLocale(locale) {
+      if (!this.enabled) {
+         this._log('warn', 'setLocale() needs "translator": { "enabled": true } in sliceConfig.json');
+         return this.locale;
+      }
+      const next = matchLocale(locale, /** @type {string[]} */ ([...this.locales]));
+      if (!next) {
+         throw new Error(`[slice.translator] "${locale}" is not one of the configured locales (${this.locales.join(', ')})`);
+      }
+      const switchId = ++this._switchId;
+      if (next === this.locale) return this.locale;
+
+      await this._loadLocale(next);
+      // A later setLocale() started while this one was loading: that one wins.
+      if (switchId !== this._switchId) return this.locale;
+
+      const previous = this.locale;
+      this.locale = next;
+      this._version++;
+      this._applyDocumentLocale();
+      if (this.saveLocally) this._save(next);
+      this.syncUrl();
+
+      this._refresh();
+      this._notify(previous);
+      return this.locale;
+   }
+
+   /**
+    * Load what `locale` needs without switching to it, so a navigation can push the new URL
+    * only once the dictionaries are in (setLocale() then switches without waiting).
+    * Rejects for a locale that is not configured, or when its main file fails.
+    * @param {string} locale
+    * @returns {Promise<string>} the configured locale matched
+    */
+   async preload(locale) {
+      const match = matchLocale(locale, /** @type {string[]} */ ([...this.locales]));
+      if (!match) {
+         throw new Error(`[slice.translator] "${locale}" is not one of the configured locales (${this.locales.join(', ')})`);
+      }
+      if (this.enabled) await this._loadLocale(match);
+      return match;
+   }
+
+   // ───────────────────────────── Props ─────────────────────────────
+
+   /**
+    * A reference to a key, for a component prop. The component receives the translated
+    * string, and receives it again when the locale changes. With the translator off it is
+    * the plain key: a marker stored in a prop would leak into comparisons and JSON.
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @returns {TranslationRef|string}
+    */
+   ref(key, params) {
+      if (!this.enabled) return String(key ?? '');
+      return new TranslationRef(key, params, () =>
+         this._warnOnce(`marker:${key}`, `slice.t.ref("${key}") was used as a string; pass it as a prop value, or use slice.t() for text`)
+      );
+   }
+
+   /**
+    * A reference to a *list* of messages, for a component prop. The component receives the
+    * array, and receives a fresh one when the locale changes. With the translator off it is
+    * the plain key, like `ref()`.
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @returns {TranslationListRef|string}
+    */
+   refList(key, params) {
+      if (!this.enabled) return String(key ?? '');
+      return new TranslationListRef(key, params, () =>
+         this._warnOnce(`marker-list:${key}`, `slice.t.ref.list("${key}") was used as a string; pass it as a prop value`)
+      );
+   }
+
+   /**
+    * Whether a value is (or contains) a `key()` marker.
+    * @param {unknown} value
+    * @returns {boolean}
+    */
+   isRef(value) {
+      return containsMarker(value);
+   }
+
+   /**
+    * Resolve every marker in a value (deep, through arrays and plain objects).
+    * @param {any} value
+    * @returns {any}
+    */
+   resolve(value) {
+      return resolveMarkers(
+         value,
+         (key, params) => this.t(key, params),
+         0,
+         (key, params) => this.list(key, params)
+      );
+   }
+
+   /**
+    * Wrap the setters of a component class's `static props` so that a later assignment of a
+    * marker (`this.$count.label = slice.t.ref(…)`) resolves and refreshes too.
+    * Once per class; invisible for any value that is not a marker. Called by the Controller.
+    * @param {Function} ComponentClass
+    * @returns {void}
+    */
+   prepareClass(ComponentClass) {
+      if (!this.enabled || typeof ComponentClass !== 'function' || this._wrappedProps.has(ComponentClass)) return;
+      /** @type {Set<string>} */
+      const wrapped = new Set();
+      this._wrappedProps.set(ComponentClass, wrapped);
+
+      const staticProps = /** @type {any} */ (ComponentClass).props;
+      if (!isPlainObject(staticProps)) return;
+
+      const translator = this;
+      for (const prop of Object.keys(staticProps)) {
+         const found = findAccessor(ComponentClass.prototype, prop);
+         if (!found || typeof found.descriptor.set !== 'function') continue;
+         const { descriptor } = found;
+         if (/** @type {any} */ (descriptor.set)[WRAPPED]) {
+            wrapped.add(prop);
+            continue;
+         }
+         const originalSet = descriptor.set;
+         const set = function (/** @type {any} */ value) {
+            // The runtime has one translator; prefer the live one if it was replaced.
+            const active = globalThis.slice?.translator instanceof Translator ? globalThis.slice.translator : translator;
+            return originalSet.call(this, active._track(this, prop, value));
+         };
+         Object.defineProperty(set, WRAPPED, { value: true });
+         Object.defineProperty(ComponentClass.prototype, prop, {
+            get: descriptor.get,
+            set,
+            enumerable: descriptor.enumerable,
+            configurable: true,
+         });
+         wrapped.add(prop);
+      }
+   }
+
+   /**
+    * The value the Controller assigns for `prop`. A prop whose setter is wrapped gets the raw
+    * value (the setter resolves it); any other prop gets the value resolved here, and its
+    * markers are remembered for the next locale change.
+    * @param {object} component
+    * @param {string} prop
+    * @param {any} value
+    * @returns {any}
+    */
+   propValue(component, prop, value) {
+      if (this._isWrapped(component, prop)) return value;
+      return this._track(component, prop, value);
+   }
+
+   /**
+    * Validation sees what the component will receive: strings, not markers.
+    * @param {Record<string, any>} props
+    * @returns {Record<string, any>}
+    */
+   resolveProps(props) {
+      return containsMarker(props) ? this.resolve(props) : props;
+   }
+
+   // ───────────────────────────── URLs (§7) ─────────────────────────────
+
+   /**
+    * Split a known locale prefix off a URL: `/en/pricing` → `{ locale: 'en', path: '/pricing' }`.
+    * Without `localePrefix`, the URL is returned whole with `locale: null`.
+    * @param {string} url
+    * @returns {{ locale: string|null, path: string }}
+    */
+   splitPath(url) {
+      if (!this.localePrefix) return { locale: null, path: typeof url === 'string' && url ? url : '/' };
+      return splitLocalePath(url, this.locales);
+   }
+
+   /**
+    * The URL of an app path in a locale (default: the active one). Leaves alone what is not
+    * an app path (`https://…`, `mailto:`, `#top`, relative paths) and paths that already
+    * carry a locale.
+    * @param {string} path
+    * @param {string} [locale]
+    * @returns {string}
+    */
+   localizePath(path, locale = this.locale) {
+      if (!this.localePrefix || isExternalHref(path)) return path;
+      if (splitLocalePath(path, this.locales).locale) return path;
+      return localizePath(path, locale, { localePrefix: this.localePrefix, defaultLocale: this.defaultLocale });
+   }
+
+   /**
+    * The locale a URL stands for (see `initialLocale()`); null without `localePrefix`.
+    * @param {string} url
+    * @returns {string|null}
+    */
+   localeOfUrl(url) {
+      return localeOfUrl(url, { localePrefix: this.localePrefix, defaultLocale: this.defaultLocale, locales: this.locales });
+   }
+
+   // ───────────────────────────── DOM ─────────────────────────────
+
+   /**
+    * Translate every `data-t` element under `root` (default: the document) now, instead of
+    * when the observer runs — for code that reads a text right after creating it.
+    * @param {ParentNode} [root]
+    * @returns {number} elements written
+    */
+   apply(root) {
+      if (!this.enabled || !this._ready) return 0;
+      const target = root || (typeof document !== 'undefined' ? document.documentElement : null);
+      if (!target) return 0;
+      return translateTree(target, this._dom);
+   }
+
+   // ───────────────────────────── Outside the DOM ─────────────────────────────
+
+   /**
+    * Run `callback(locale, previous)` after every locale change, for texts that live outside
+    * the DOM (a chart drawn on a canvas, a library that copied a string). With a component,
+    * the subscription ends when the component is destroyed. Returns an unsubscribe function.
+    * @param {object|((locale: string, previous: string) => void)} componentOrCallback
+    * @param {(locale: string, previous: string) => void} [callback]
+    * @returns {() => void}
+    */
+   watch(componentOrCallback, callback) {
+      if (typeof componentOrCallback === 'function') {
+         const fn = componentOrCallback;
+         this._globalWatchers.add(fn);
+         return () => this._globalWatchers.delete(fn);
+      }
+      const component = componentOrCallback;
+      if (!component || typeof callback !== 'function') return () => {};
+      let set = this._watchers.get(component);
+      if (!set) {
+         set = new Set();
+         this._watchers.set(component, set);
+      }
+      set.add(callback);
+      return () => {
+         const current = this._watchers.get(component);
+         current?.delete(callback);
+         if (current && current.size === 0) this._watchers.delete(component);
+      };
+   }
+
+   /**
+    * Drop everything held for a component. Called by the Controller when it is destroyed.
+    * @param {object} component
+    * @returns {void}
+    */
+   forget(component) {
+      this._watchers.delete(component);
+      this._markerProps.delete(component);
+   }
+
+   // ───────────────────────────── Formatting ─────────────────────────────
+
+   /**
+    * @private
+    */
+   _createFormat() {
+      const intl = this._intl;
+      const locale = () => this.locale;
+      const toDate = (/** @type {any} */ value) => (value instanceof Date ? value : new Date(value));
+      // A bad locale, an invalid date or a missing currency must not throw from a formatter:
+      // fall back to a readable value.
+      const safe = (format, fallback) => (...args) => {
+         try {
+            return format(...args);
+         } catch {
+            return fallback(...args);
+         }
+      };
+      return Object.freeze({
+         /** @param {number} value @param {Intl.NumberFormatOptions} [options] */
+         number: safe(
+            (value, options = {}) => intl.get(Intl.NumberFormat, locale(), options).format(value),
+            (value) => String(value)
+         ),
+         /** @param {number} value @param {string} currency @param {Intl.NumberFormatOptions} [options] */
+         currency: safe(
+            (value, currency, options = {}) =>
+               intl.get(Intl.NumberFormat, locale(), { style: 'currency', currency, ...options }).format(value),
+            (value, currency) => `${value} ${currency || ''}`.trim()
+         ),
+         /** @param {number} value 0.25 → 25 % @param {Intl.NumberFormatOptions} [options] */
+         percent: safe(
+            (value, options = {}) => intl.get(Intl.NumberFormat, locale(), { style: 'percent', ...options }).format(value),
+            (value, options = {}) => `${Math.round(Number(value) * 100)}%`
+         ),
+         /** @param {Date|number|string} value @param {Intl.DateTimeFormatOptions} [options] */
+         date: safe(
+            (value, options = { dateStyle: 'medium' }) => intl.get(Intl.DateTimeFormat, locale(), options).format(toDate(value)),
+            (value) => String(value)
+         ),
+         /** @param {Date|number|string} value @param {Intl.DateTimeFormatOptions} [options] */
+         time: safe(
+            (value, options = { timeStyle: 'short' }) => intl.get(Intl.DateTimeFormat, locale(), options).format(toDate(value)),
+            (value) => String(value)
+         ),
+         /** @param {number} value @param {Intl.RelativeTimeFormatUnit} unit @param {Intl.RelativeTimeFormatOptions} [options] */
+         relative: safe(
+            (value, unit, options = { numeric: 'auto' }) => intl.get(Intl.RelativeTimeFormat, locale(), options).format(value, unit),
+            (value, unit) => `${value} ${unit}`
+         ),
+         /** @param {string[]} items @param {Intl.ListFormatOptions} [options] */
+         list: safe(
+            (items, options = { type: 'conjunction' }) => intl.get(Intl.ListFormat, locale(), options).format(items),
+            (items) => (Array.isArray(items) ? items.join(', ') : String(items))
+         ),
+      });
+   }
+
+   // ───────────────────────────── Internals ─────────────────────────────
+
+   /** @private @returns {string[]} */
+   _chain() {
+      return this.fallbackLocale && this.fallbackLocale !== this.locale ? [this.locale, this.fallbackLocale] : [this.locale];
+   }
+
+   /** @private */
+   _entry(key, locale) {
+      const app = lookup(this._app.get(locale), key);
+      if (app !== undefined) return app;
+      return lookup(this._defaults.get(locale), key);
+   }
+
+   /**
+    * Load the main file of `locale` and every namespace in use, plus the fallback's.
+    * Rejects when the locale's main file fails; a failing fallback only warns.
+    * @private
+    * @param {string} locale
+    */
+   async _loadLocale(locale) {
+      const namespaces = [...this._namespaces];
+      // Only the main file is fatal. One broken optional namespace must not block every
+      // future setLocale() (load() adds it to `_namespaces` before the fetch).
+      const main = this._fetch(locale);
+      const activeNamespaces = Promise.allSettled(namespaces.map((ns) => this._fetch(locale, ns)));
+      const fallbackFiles =
+         this.fallbackLocale && this.fallbackLocale !== locale
+            ? [this._fetch(this.fallbackLocale), ...namespaces.map((ns) => this._fetch(this.fallbackLocale, ns))]
+            : [];
+      const [activeResults, fallbackResults] = await Promise.all([
+         activeNamespaces,
+         fallbackFiles.length ? Promise.allSettled(fallbackFiles) : Promise.resolve([])
+      ]);
+      await main;
+      for (const result of /** @type {PromiseSettledResult<void>[]} */ (activeResults)) {
+         if (result.status === 'rejected') this._log('warn', `Namespace dictionary failed (${locale})`, result.reason);
+      }
+      for (const result of /** @type {PromiseSettledResult<void>[]} */ (fallbackResults)) {
+         if (result.status === 'rejected') this._log('warn', `Fallback dictionary failed (${this.fallbackLocale})`, result.reason);
+      }
+   }
+
+   /**
+    * Fetch one content document once (`<path>/content/<name>.json`). A failure warns and
+    * resolves to `undefined`; it is removed from the cache so a later call can retry.
+    * @private
+    * @param {string} name
+    * @returns {Promise<Record<string, any>|undefined>}
+    */
+   _loadContent(name) {
+      const cached = this._content.get(name);
+      if (cached) return cached;
+
+      const url = `${this.path}/content/${name}.json`;
+      const request = (async () => {
+         const response = await fetch(url);
+         if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`);
+         const json = await response.json();
+         if (!isPlainObject(json)) throw new Error(`${url} is not a JSON object`);
+         this._version++;
+         return json;
+      })()
+         .catch((error) => {
+            this._log('warn', `Could not load content "${name}"`, error);
+            this._content.delete(name);
+            return undefined;
+         });
+
+      this._content.set(name, request);
+      return request;
+   }
+
+   /**
+    * Fetch one dictionary file once and merge it into the app layer.
+    * @private
+    * @param {string} locale
+    * @param {string} [namespace]
+    * @returns {Promise<void>}
+    */
+   _fetch(locale, namespace) {
+      const id = namespace ? `${locale}/${namespace}` : locale;
+      if (this._loaded.has(id)) return Promise.resolve();
+      const pending = this._requests.get(id);
+      if (pending) return pending;
+
+      const url = `${this.path}/${id}.json`;
+      const request = (async () => {
+         const response = await fetch(url);
+         if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`);
+         const json = await response.json();
+         if (!isPlainObject(json)) throw new Error(`${url} is not a JSON object`);
+         if (!this._app.has(locale)) this._app.set(locale, {});
+         mergeMessages(/** @type {Record<string, any>} */ (this._app.get(locale)), namespace ? { [namespace]: json } : json);
+         this._loaded.add(id);
+         this._version++;
+      })().finally(() => this._requests.delete(id));
+
+      this._requests.set(id, request);
+      return request;
+   }
+
+   /** @private */
+   _isWrapped(component, prop) {
+      const Class = component?.constructor;
+      return !!Class && !!this._wrappedProps.get(Class)?.has(prop);
+   }
+
+   /**
+    * Remember (or forget) a prop's markers, and return what the component receives.
+    * @private
+    */
+   _track(component, prop, value) {
+      if (containsMarker(value)) {
+         let record = this._markerProps.get(component);
+         if (!record) {
+            record = new Map();
+            this._markerProps.set(component, record);
+         }
+         record.set(prop, value);
+         return this.resolve(value);
+      }
+      // A plain value replaces a marker: stop refreshing that prop.
+      if (!this._refreshing) this._markerProps.get(component)?.delete(prop);
+      return value;
+   }
+
+   /**
+    * Re-translate the document, re-assign marker props and re-apply the route metadata.
+    * @private
+    */
+   _refresh() {
+      if (!this.enabled || !this._ready) return;
+      this.apply();
+      this._refreshProps();
+      this._refreshRouteMetadata();
+   }
+
+   /** @private Coalesce several add() calls in the same tick into one refresh. */
+   _scheduleRefresh() {
+      if (!this._ready || this._refreshScheduled) return;
+      this._refreshScheduled = true;
+      queueMicrotask(() => {
+         this._refreshScheduled = false;
+         this._refresh();
+      });
+   }
+
+   /** @private Parents before children, so a parent that rebuilds its children goes first. */
+   _refreshProps() {
+      const active = /** @type {Map<string, any>|undefined} */ (globalThis.slice?.controller?.activeComponents);
+      if (!active) return;
+      const components = [...active.values()]
+         .filter((component) => this._markerProps.has(component))
+         .sort((a, b) => (a._depth || 0) - (b._depth || 0));
+
+      for (const component of components) {
+         const record = this._markerProps.get(component);
+         if (!record) continue;
+         for (const [prop, raw] of [...record]) {
+            this._refreshing = true;
+            try {
+               component[prop] = this._isWrapped(component, prop) ? raw : this.resolve(raw);
+            } catch (error) {
+               this._log('error', `Could not refresh "${prop}" of ${component.sliceId || component.constructor?.name}`, error);
+            } finally {
+               this._refreshing = false;
+            }
+         }
+      }
+   }
+
+   /** @private */
+   _refreshRouteMetadata() {
+      const s = globalThis.slice;
+      if (!s?.router || s.routerConfig?.updateTitles === false) return;
+      const metadata = s.router.activeMetadata;
+      if (metadata && typeof s.router.applyMetadata === 'function') s.router.applyMetadata(metadata);
+   }
+
+   /**
+    * @private
+    * @param {string} previous
+    */
+   _notify(previous) {
+      const s = globalThis.slice;
+      const alive = (/** @type {any} */ component) =>
+         typeof s?.isComponentAlive === 'function' ? s.isComponentAlive(component) : true;
+
+      const components = [...this._watchers.keys()].sort((a, b) => (a._depth || 0) - (b._depth || 0));
+      for (const component of components) {
+         if (!alive(component)) {
+            this._watchers.delete(component);
+            continue;
+         }
+         for (const callback of [...(this._watchers.get(component) || [])]) {
+            this._safeCall(callback, previous);
+         }
+      }
+      for (const callback of [...this._globalWatchers]) this._safeCall(callback, previous);
+
+      const payload = { locale: this.locale, previous };
+      if (s?.eventsConfig?.enabled && typeof s.events?.emit === 'function') {
+         s.events.emit('translator:change', payload);
+      } else if (typeof window !== 'undefined' && typeof CustomEvent === 'function') {
+         window.dispatchEvent(new CustomEvent('translator:change', { detail: payload }));
+      }
+   }
+
+   /**
+    * @private
+    * @param {(locale: string, previous: string) => void} callback
+    * @param {string} previous
+    */
+   _safeCall(callback, previous) {
+      try {
+         callback(this.locale, previous);
+      } catch (error) {
+         this._log('error', 'A translator.watch() callback failed', error);
+      }
+   }
+
+   /** @private */
+   _observe() {
+      if (this._observer || typeof MutationObserver === 'undefined' || typeof document === 'undefined') return;
+      this._observer = new MutationObserver((records) => {
+         try {
+            for (const record of records) {
+               if (record.type === 'childList') {
+                  for (const node of record.addedNodes) {
+                     if (node.nodeType === 1) translateTree(/** @type {Element} */ (node), this._dom);
+                  }
+               } else if (record.attributeName && (record.attributeName === 'data-t' || record.attributeName.startsWith('data-t-')) && record.target.isConnected) {
+                  translateTree(/** @type {Element} */ (record.target), this._dom);
+               }
+            }
+         } catch (error) {
+            this._log('error', 'Error translating new or changed elements', error);
+         }
+      });
+      // No attributeFilter: params are open-ended (`data-t-count`, `data-t-name`…). The
+      // callback ignores every other attribute with one string check.
+      this._observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true });
+   }
+
+   /**
+    * Make the address bar show the active locale (replaceState: no navigation, no history
+    * entry). A no-op when it already does, so the router can call setLocale() after pushing
+    * the target URL. Called by the router after every route change.
+    * @returns {void}
+    */
+   syncUrl() {
+      if (!this.localePrefix || typeof location === 'undefined' || typeof history === 'undefined') return;
+      const current = `${location.pathname}${location.search}${location.hash}`;
+      // Never rewrite a URL the router cannot resolve: `/fr/x` must stay a 404, not become
+      // `/es/fr/x` (and lose the miss).
+      const router = globalThis.slice?.router;
+      if (typeof router?.matchRoute === 'function') {
+         const match = router.matchRoute(current);
+         if (!match?.route || match.route.path === '/404') return;
+      }
+      const { path } = splitLocalePath(current, this.locales);
+      const target = localizePath(path, this.locale, { localePrefix: this.localePrefix, defaultLocale: this.defaultLocale });
+      if (target !== current) history.replaceState(history.state, '', target);
+   }
+
+   /** @private */
+   _applyDocumentLocale() {
+      if (typeof document === 'undefined') return;
+      const html = document.documentElement;
+      if (html.lang !== this.locale) html.lang = this.locale;
+      const dir = directionOf(this.locale);
+      if (html.dir !== dir) html.dir = dir;
+   }
+
+   /** @private @returns {string|null} */
+   _readSaved() {
+      try {
+         return globalThis.localStorage?.getItem(STORAGE_KEY) ?? null;
+      } catch {
+         return null;
+      }
+   }
+
+   /** @private */
+   _save(locale) {
+      try {
+         globalThis.localStorage?.setItem(STORAGE_KEY, locale);
+      } catch {
+         // storage refused (private mode, quota): the choice lasts for this page only
+      }
+   }
+
+   /**
+    * Development warning, once per id.
+    * @private
+    */
+   _warnOnce(id, message) {
+      const s = globalThis.slice;
+      if (typeof s?.isProduction === 'function' && s.isProduction()) return;
+      if (this._warned.has(id)) return;
+      this._warned.add(id);
+      this._log('warn', message);
+   }
+
+   /** @private */
+   _log(level, message, error) {
+      const logger = globalThis.slice?.logger;
+      if (level === 'error') {
+         if (logger?.logError) logger.logError('Translator', message, error);
+         else console.error(`[slice.translator] ${message}`, error ?? '');
+      } else if (logger?.logWarning) {
+         logger.logWarning('Translator', message, error);
+      } else {
+         console.warn(`[slice.translator] ${message}`, error ?? '');
+      }
+   }
+}
+
+/**
+ * Find an accessor along the prototype chain (stops before HTMLElement and friends).
+ * @param {object} proto
+ * @param {string} prop
+ * @returns {{ owner: object, descriptor: PropertyDescriptor }|null}
+ */
+function findAccessor(proto, prop) {
+   let current = proto;
+   while (current && current !== Object.prototype) {
+      if (typeof HTMLElement !== 'undefined' && current === HTMLElement.prototype) return null;
+      const descriptor = Object.getOwnPropertyDescriptor(current, prop);
+      if (descriptor) return descriptor.get || descriptor.set ? { owner: current, descriptor } : null;
+      current = Object.getPrototypeOf(current);
+   }
+   return null;
+}