@forgeax/interface 0.4.1

package/dist/package/node/i18n/index.js

@@ -0,0 +1,207 @@
+/**
+ * Lightweight i18n core for the Studio interface.
+ *
+ * Design principles:
+ *   - English is the SOURCE OF TRUTH. `locales/en.json` holds the English UI
+ *     copy; reading it ≈ reading the English UI. Keys are English semantic
+ *     identifiers. AI / developers read English everywhere; other languages are
+ *     a user-facing overlay only.
+ *   - Zero external deps. The public API is deliberately shaped like
+ *     `react-i18next` (`useTranslation() → { t }`, `t(key, vars)`,
+ *     `changeLanguage`, `{{var}}` interpolation) so it feels familiar and could
+ *     be swapped for the real library later with near-zero churn.
+ *   - Module-level store + `useSyncExternalStore`, matching this repo's
+ *     hand-rolled store style (see StatusBar/store.ts, SettingsPanel/store.ts).
+ *
+ * Lookup order for any key: current locale → English → the key string itself.
+ */
+import { useSyncExternalStore } from 'react';
+import { installCustomEventObservation, installStorageObservation, } from '@forgeax/app-shell/react';
+import en from './locales/en.json' with { type: 'json' };
+import zh from './locales/zh.json' with { type: 'json' };
+import { STORAGE_KEYS } from '../lib/storageKeys.js';
+import { flushBrowserPrefs } from '../lib/browser-prefs-sync.js';
+/** Same-FRAME broadcast event. Injected editor panels (@forgeax/editor-panels)
+ *  render in THIS frame but read their copy from @forgeax/editor-core/i18n — a
+ *  SEPARATE store instance. It listens for this window event to re-read the
+ *  locale, so a switch here live-updates the editor panels too. Must match
+ *  editor-core's LOCALE_CHANGED_EVENT. (`storage` never fires in the document
+ *  that wrote it, and the extension postMessage only reaches iframes, so this
+ *  window event is the only same-frame channel.) */
+const LOCALE_CHANGED_EVENT = 'forgeax:locale-changed';
+/** Adding a language = append here + drop a sibling JSON in ./locales. */
+export const SUPPORTED_LOCALES = [
+    { code: 'en', label: 'English', nativeLabel: 'English' },
+    { code: 'zh', label: 'Chinese', nativeLabel: '简体中文' },
+];
+export const DEFAULT_LOCALE = 'en';
+const CATALOGS = { en: en, zh: zh };
+// ── store ──────────────────────────────────────────────────────────────────
+let current = DEFAULT_LOCALE;
+const listeners = new Set();
+function broadcastLocaleToExtensions(locale) {
+    if (typeof window === 'undefined')
+        return;
+    const msg = { type: 'forgeax:locale-changed', locale };
+    for (const iframe of document.querySelectorAll('iframe')) {
+        try {
+            iframe.contentWindow?.postMessage(msg, '*');
+        }
+        catch {
+            /* cross-origin or detached */
+        }
+    }
+}
+function emit() {
+    broadcastLocaleToExtensions(current);
+    for (const fn of listeners)
+        fn();
+}
+function isLocale(v) {
+    return typeof v === 'string' && SUPPORTED_LOCALES.some((l) => l.code === v);
+}
+/** Read the persisted locale (no side effects). Falls back to the configured
+ *  product default on first run (no stored value). English is the source UI;
+ *  an explicit user selection is persisted and continues to win. */
+function readPersisted() {
+    if (typeof window === 'undefined')
+        return DEFAULT_LOCALE;
+    try {
+        const raw = window.localStorage.getItem(STORAGE_KEYS.locale);
+        if (isLocale(raw))
+            return raw;
+    }
+    catch {
+        /* private mode */
+    }
+    return DEFAULT_LOCALE;
+}
+/**
+ * Initialize locale from persisted prefs. Call once, early, in main.tsx.
+ * Safe to call again (idempotent) — restored prefs sync may re-trigger it.
+ */
+let storageWired = false;
+export function initI18n() {
+    setLocale(readPersisted(), { persist: false });
+    // Cross-document/tab sync: the `storage` event fires in OTHER same-origin
+    // documents when localStorage changes. The editor runs same-origin (proxied
+    // at /editor/), so switching language in the host live-updates the editor
+    // shell (and vice-versa), plus multi-tab stays in sync. Apply with
+    // persist:false to avoid a write-loop.
+    if (!storageWired && typeof window !== 'undefined') {
+        storageWired = true;
+        const onLocaleStorage = (e) => {
+            if (!e.key || e.key === STORAGE_KEYS.locale)
+                setLocale(readPersisted(), { persist: false });
+        };
+        void installStorageObservation({ target: window, onStorage: onLocaleStorage });
+        // Symmetric same-frame sync: if the editor-core store initiates a switch it
+        // dispatches this window event; pick it up so the shell follows. persist:false
+        // + readPersisted() makes our own re-broadcast a no-op (no change → no
+        // re-emit), so there is no feedback loop.
+        const onLocaleChanged = (event) => {
+            const detail = event.detail;
+            setLocale(isLocale(detail) ? detail : readPersisted(), { persist: false });
+        };
+        void installCustomEventObservation({
+            target: window,
+            eventType: LOCALE_CHANGED_EVENT,
+            onEvent: onLocaleChanged,
+        });
+    }
+}
+export function getLocale() {
+    return current;
+}
+/** Subscribe to host locale changes (same-tab; storage events don't fire locally). */
+export function subscribeLocale(listener) {
+    const wrapped = () => listener(current);
+    listeners.add(wrapped);
+    return () => listeners.delete(wrapped);
+}
+export function setLocale(next, opts = {}) {
+    const persist = opts.persist ?? true;
+    if (!isLocale(next))
+        return;
+    const changed = next !== current;
+    current = next;
+    if (typeof document !== 'undefined') {
+        document.documentElement.lang = next;
+    }
+    if (persist && typeof window !== 'undefined') {
+        try {
+            window.localStorage.setItem(STORAGE_KEYS.locale, next);
+            // Same-tab localStorage writes don't fire the `storage` event the prefs
+            // sync listens to, so push immediately — otherwise a quick reload would
+            // restore a stale server snapshot and revert the language.
+            if (changed)
+                void flushBrowserPrefs();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (changed) {
+        emit();
+        // Notify the same-frame editor-core i18n store (see LOCALE_CHANGED_EVENT).
+        // Runs AFTER the localStorage write so the listener's readPersisted() sees
+        // the new value.
+        if (typeof window !== 'undefined') {
+            try {
+                window.dispatchEvent(new CustomEvent(LOCALE_CHANGED_EVENT, { detail: next }));
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** react-i18next-compatible alias. */
+export function changeLanguage(next) {
+    setLocale(next);
+}
+export function subscribe(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+// ── lookup ───────────────────────────────────────────────────────────────────
+function resolve(catalog, key) {
+    // Support both flat keys ("settings.title" as a literal property) and nested
+    // objects ({ settings: { title } }). Try flat first, then walk the path.
+    const flat = catalog[key];
+    if (typeof flat === 'string')
+        return flat;
+    let node = catalog;
+    for (const part of key.split('.')) {
+        if (node && typeof node === 'object' && part in node) {
+            node = node[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return typeof node === 'string' ? node : undefined;
+}
+function interpolate(tpl, vars) {
+    if (!vars)
+        return tpl;
+    // Supports {{name}} (i18next style) and {name} (terse).
+    return tpl.replace(/\{\{?\s*(\w+)\s*\}?\}/g, (m, name) => name in vars ? String(vars[name]) : m);
+}
+/** Locale-agnostic translate. Falls back current → en → key. */
+export function t(key, vars) {
+    const hit = resolve(CATALOGS[current], key) ??
+        (current !== 'en' ? resolve(CATALOGS.en, key) : undefined) ??
+        key;
+    return interpolate(hit, vars);
+}
+// ── React binding ────────────────────────────────────────────────────────────
+const getSnapshot = () => current;
+/** react-i18next-compatible hook. Re-renders the caller on language change. */
+export function useTranslation() {
+    const language = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    // Return the module-level `t` (stable identity). It already reads `current`
+    // at call time, so a new closure per render is unnecessary and breaks any
+    // useEffect/useMemo that lists `t` as a dependency (infinite re-render loops).
+    return { t, i18n: { language, changeLanguage } };
+}