@zachhandley/ez-i18n 0.1.1 → 0.1.3

package/dist/runtime/react-plugin.js

@@ -0,0 +1,85 @@
+// src/runtime/react-plugin.ts
+import { useStore } from "@nanostores/react";
+
+// src/runtime/store.ts
+import { atom, computed } from "nanostores";
+import { persistentAtom } from "@nanostores/persistent";
+var serverLocale = atom(null);
+var localePreference = persistentAtom("ez-locale", "en", {
+  encode: (value) => value,
+  decode: (value) => value
+});
+var effectiveLocale = computed(
+  [serverLocale, localePreference],
+  (server, client) => server ?? client
+);
+var translations = atom({});
+var localeLoading = atom(false);
+async function setLocale(locale, options = {}) {
+  const opts = typeof options === "string" ? { cookieName: options } : options;
+  const { cookieName = "ez-locale", loadTranslations } = opts;
+  localeLoading.set(true);
+  try {
+    if (loadTranslations) {
+      const mod = await loadTranslations();
+      const trans = "default" in mod ? mod.default : mod;
+      translations.set(trans);
+    }
+    localePreference.set(locale);
+    serverLocale.set(locale);
+    if (typeof document !== "undefined") {
+      document.cookie = `${cookieName}=${locale}; path=/; max-age=31536000; samesite=lax`;
+    }
+    if (typeof document !== "undefined") {
+      document.dispatchEvent(
+        new CustomEvent("ez-i18n:locale-changed", {
+          detail: { locale },
+          bubbles: true
+        })
+      );
+    }
+  } finally {
+    localeLoading.set(false);
+  }
+}
+
+// src/runtime/react-plugin.ts
+function getNestedValue(obj, path) {
+  const keys = path.split(".");
+  let value = obj;
+  for (const key of keys) {
+    if (value == null || typeof value !== "object") {
+      return void 0;
+    }
+    value = value[key];
+  }
+  return value;
+}
+function interpolate(str, params) {
+  if (!params) return str;
+  return str.replace(/\{(\w+)\}/g, (match, key) => {
+    return key in params ? String(params[key]) : match;
+  });
+}
+function useI18n() {
+  const locale = useStore(effectiveLocale);
+  const trans = useStore(translations);
+  const t = (key, params) => {
+    const value = getNestedValue(trans, key);
+    if (typeof value !== "string") {
+      if (import.meta.env?.DEV) {
+        console.warn("[ez-i18n] Missing translation:", key);
+      }
+      return key;
+    }
+    return interpolate(value, params);
+  };
+  return {
+    t,
+    locale,
+    setLocale
+  };
+}
+export {
+  useI18n
+};

package/dist/runtime/vue-plugin.d.ts

@@ -1,7 +1,7 @@
 import * as vue from 'vue';
 import { Plugin } from 'vue';
 import { setLocale } from './index.js';
-import { T as TranslateFunction } from '../types-DwCG8sp8.js';
+import { T as TranslateFunction } from '../types-CHyDGt_C.js';
 import 'nanostores';
 
 /**

package/dist/types-CHyDGt_C.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Translation path for a single locale:
+ * - Single file: `./src/i18n/en.json`
+ * - Folder: `./src/i18n/en/` (auto-discover all JSONs inside)
+ * - Glob: `./src/i18n/en/**.json` (recursive)
+ * - Array: `['./common.json', './auth.json']`
+ */
+type LocaleTranslationPath = string | string[];
+/**
+ * Translation config can be:
+ * - A base directory string (auto-discovers locale folders): './public/i18n/'
+ * - Per-locale mapping: { en: './src/i18n/en/', es: './src/i18n/es.json' }
+ */
+type TranslationsConfig = string | Record<string, LocaleTranslationPath>;
+/**
+ * Configuration for ez-i18n Astro integration
+ */
+interface EzI18nConfig {
+    /**
+     * List of supported locale codes (e.g., ['en', 'es', 'fr'])
+     * Optional if using directory-based auto-discovery - locales will be
+     * detected from folder names in the translations directory.
+     */
+    locales?: string[];
+    /**
+     * Default locale to use when no preference is detected.
+     * Required - this tells us what to fall back to.
+     */
+    defaultLocale: string;
+    /**
+     * Cookie name for storing locale preference
+     * @default 'ez-locale'
+     */
+    cookieName?: string;
+    /**
+     * Translation file paths configuration.
+     * Paths are relative to your project root.
+     *
+     * Can be:
+     * - A base directory (auto-discovers locale folders):
+     *   translations: './public/i18n/'
+     *   → Scans for en/, es/, fr/ folders and their JSON files
+     *   → Auto-populates `locales` from discovered folders
+     *
+     * - Per-locale mapping with flexible path types:
+     *   translations: {
+     *     en: './src/i18n/en.json',           // single file
+     *     es: './src/i18n/es/',               // folder (all JSONs)
+     *     fr: './src/i18n/fr/**.json',          // glob pattern
+     *     de: ['./common.json', './auth.json'] // array of files
+     *   }
+     *
+     * If not specified, auto-discovers from ./public/i18n/
+     */
+    translations?: TranslationsConfig;
+}
+/**
+ * Cache file structure (.ez-i18n.json)
+ * Used to speed up subsequent builds by caching discovered translations
+ */
+interface TranslationCache {
+    version: number;
+    /** Discovered locale → file paths mapping */
+    discovered: Record<string, string[]>;
+    /** ISO timestamp of last scan */
+    lastScan: string;
+}
+/**
+ * Translation function type
+ */
+type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+/**
+ * Augment Astro's locals type
+ */
+declare global {
+    namespace App {
+        interface Locals {
+            /** Current locale code */
+            locale: string;
+            /** Loaded translations for the current locale */
+            translations: Record<string, unknown>;
+        }
+    }
+}
+
+export type { EzI18nConfig as E, LocaleTranslationPath as L, TranslateFunction as T, TranslationsConfig as a, TranslationCache as b };

package/dist/utils/index.d.ts

@@ -0,0 +1,59 @@
+import { L as LocaleTranslationPath, a as TranslationsConfig, b as TranslationCache } from '../types-CHyDGt_C.js';
+
+type PathType = 'file' | 'folder' | 'glob' | 'array';
+/**
+ * Detect the type of translation path
+ */
+declare function detectPathType(input: string | string[]): PathType;
+/**
+ * Resolve a single translation path to an array of absolute file paths.
+ * Results are sorted alphabetically for predictable merge order.
+ */
+declare function resolveTranslationPaths(input: LocaleTranslationPath, projectRoot: string): Promise<string[]>;
+/**
+ * Auto-discover translations from a base directory.
+ * Scans for locale folders (e.g., en/, es/, fr/) and their JSON files.
+ * Returns both discovered locales and their file mappings.
+ */
+declare function autoDiscoverTranslations(baseDir: string, projectRoot: string, configuredLocales?: string[]): Promise<{
+    locales: string[];
+    translations: Record<string, string[]>;
+}>;
+/**
+ * Resolve the full translations config to normalized form.
+ * Handles string (base dir), object (per-locale), or undefined (auto-discover).
+ */
+declare function resolveTranslationsConfig(config: TranslationsConfig | undefined, projectRoot: string, configuredLocales?: string[]): Promise<{
+    locales: string[];
+    translations: Record<string, string[]>;
+}>;
+/**
+ * Deep merge translation objects.
+ * - Objects are recursively merged
+ * - Arrays are REPLACED (not concatenated)
+ * - Primitives are overwritten by later values
+ * - Prototype pollution safe
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: T[]): T;
+/**
+ * Load cached translation discovery results
+ */
+declare function loadCache(projectRoot: string): TranslationCache | null;
+/**
+ * Save translation discovery results to cache
+ */
+declare function saveCache(projectRoot: string, discovered: Record<string, string[]>): void;
+/**
+ * Check if cache is still valid (files haven't changed)
+ */
+declare function isCacheValid(cache: TranslationCache, projectRoot: string): boolean;
+/**
+ * Convert an absolute path to a relative import path for Vite
+ */
+declare function toRelativeImport(absolutePath: string, projectRoot: string): string;
+/**
+ * Generate a glob pattern for import.meta.glob from a base directory
+ */
+declare function toGlobPattern(baseDir: string, projectRoot: string): string;
+
+export { type PathType, autoDiscoverTranslations, deepMerge, detectPathType, isCacheValid, loadCache, resolveTranslationPaths, resolveTranslationsConfig, saveCache, toGlobPattern, toRelativeImport };

package/dist/utils/index.js

@@ -0,0 +1,190 @@
+// src/utils/translations.ts
+import { glob } from "tinyglobby";
+import * as path from "path";
+import * as fs from "fs";
+var CACHE_FILE = ".ez-i18n.json";
+var CACHE_VERSION = 1;
+var DEFAULT_I18N_DIR = "./public/i18n";
+function detectPathType(input) {
+  if (Array.isArray(input)) return "array";
+  if (input.includes("*")) return "glob";
+  if (input.endsWith("/") || input.endsWith(path.sep)) return "folder";
+  return "file";
+}
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function resolveTranslationPaths(input, projectRoot) {
+  const type = detectPathType(input);
+  let files = [];
+  switch (type) {
+    case "array":
+      for (const entry of input) {
+        const resolved = await resolveTranslationPaths(entry, projectRoot);
+        files.push(...resolved);
+      }
+      break;
+    case "glob":
+      files = await glob(input, {
+        cwd: projectRoot,
+        absolute: true
+      });
+      break;
+    case "folder": {
+      const folderPath = path.resolve(projectRoot, input.replace(/\/$/, ""));
+      files = await glob("**/*.json", {
+        cwd: folderPath,
+        absolute: true
+      });
+      break;
+    }
+    case "file":
+    default: {
+      const filePath = path.resolve(projectRoot, input);
+      if (isDirectory(filePath)) {
+        files = await glob("**/*.json", {
+          cwd: filePath,
+          absolute: true
+        });
+      } else {
+        files = [filePath];
+      }
+      break;
+    }
+  }
+  return [...new Set(files)].sort((a, b) => a.localeCompare(b));
+}
+async function autoDiscoverTranslations(baseDir, projectRoot, configuredLocales) {
+  const absoluteBaseDir = path.resolve(projectRoot, baseDir.replace(/\/$/, ""));
+  if (!isDirectory(absoluteBaseDir)) {
+    console.warn(`[ez-i18n] Translation directory not found: ${absoluteBaseDir}`);
+    return { locales: configuredLocales || [], translations: {} };
+  }
+  const translations = {};
+  const discoveredLocales = [];
+  const entries = fs.readdirSync(absoluteBaseDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const locale = entry.name;
+      if (configuredLocales && configuredLocales.length > 0) {
+        if (!configuredLocales.includes(locale)) continue;
+      }
+      const localePath = path.join(absoluteBaseDir, locale);
+      const files = await glob("**/*.json", {
+        cwd: localePath,
+        absolute: true
+      });
+      if (files.length > 0) {
+        discoveredLocales.push(locale);
+        translations[locale] = files.sort((a, b) => a.localeCompare(b));
+      }
+    } else if (entry.isFile() && entry.name.endsWith(".json")) {
+      const locale = path.basename(entry.name, ".json");
+      if (configuredLocales && configuredLocales.length > 0) {
+        if (!configuredLocales.includes(locale)) continue;
+      }
+      const filePath = path.join(absoluteBaseDir, entry.name);
+      if (!translations[locale]) {
+        discoveredLocales.push(locale);
+        translations[locale] = [];
+      }
+      translations[locale].push(filePath);
+    }
+  }
+  const sortedLocales = [...new Set(discoveredLocales)].sort();
+  return { locales: sortedLocales, translations };
+}
+async function resolveTranslationsConfig(config, projectRoot, configuredLocales) {
+  if (!config) {
+    return autoDiscoverTranslations(DEFAULT_I18N_DIR, projectRoot, configuredLocales);
+  }
+  if (typeof config === "string") {
+    return autoDiscoverTranslations(config, projectRoot, configuredLocales);
+  }
+  const translations = {};
+  const locales = Object.keys(config);
+  for (const [locale, localePath] of Object.entries(config)) {
+    translations[locale] = await resolveTranslationPaths(localePath, projectRoot);
+  }
+  return { locales, translations };
+}
+function deepMerge(target, ...sources) {
+  const FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+  const result = { ...target };
+  for (const source of sources) {
+    if (!source || typeof source !== "object") continue;
+    for (const key of Object.keys(source)) {
+      if (FORBIDDEN_KEYS.has(key)) continue;
+      const targetVal = result[key];
+      const sourceVal = source[key];
+      if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
+        result[key] = deepMerge(
+          targetVal,
+          sourceVal
+        );
+      } else {
+        result[key] = sourceVal;
+      }
+    }
+  }
+  return result;
+}
+function loadCache(projectRoot) {
+  const cachePath = path.join(projectRoot, CACHE_FILE);
+  try {
+    if (!fs.existsSync(cachePath)) return null;
+    const content = fs.readFileSync(cachePath, "utf-8");
+    const cache = JSON.parse(content);
+    if (cache.version !== CACHE_VERSION) return null;
+    return cache;
+  } catch {
+    return null;
+  }
+}
+function saveCache(projectRoot, discovered) {
+  const cachePath = path.join(projectRoot, CACHE_FILE);
+  const cache = {
+    version: CACHE_VERSION,
+    discovered,
+    lastScan: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  try {
+    fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+  } catch (error) {
+    console.warn("[ez-i18n] Failed to write cache file:", error);
+  }
+}
+function isCacheValid(cache, projectRoot) {
+  for (const files of Object.values(cache.discovered)) {
+    for (const file of files) {
+      if (!fs.existsSync(file)) return false;
+    }
+  }
+  return true;
+}
+function toRelativeImport(absolutePath, projectRoot) {
+  const relativePath = path.relative(projectRoot, absolutePath);
+  const normalized = relativePath.replace(/\\/g, "/");
+  return normalized.startsWith(".") ? normalized : "./" + normalized;
+}
+function toGlobPattern(baseDir, projectRoot) {
+  const relativePath = path.relative(projectRoot, baseDir).replace(/\\/g, "/");
+  const normalized = relativePath.startsWith(".") ? relativePath : "./" + relativePath;
+  return `${normalized}/**/*.json`;
+}
+export {
+  autoDiscoverTranslations,
+  deepMerge,
+  detectPathType,
+  isCacheValid,
+  loadCache,
+  resolveTranslationPaths,
+  resolveTranslationsConfig,
+  saveCache,
+  toGlobPattern,
+  toRelativeImport
+};

package/package.json

@@ -1,89 +1,112 @@
-{
-  "name": "@zachhandley/ez-i18n",
-  "version": "0.1.1",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "Cookie-based i18n for Astro + Vue. No URL prefixes, reactive language switching.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./vue": {
-      "types": "./dist/runtime/vue-plugin.d.ts",
-      "import": "./dist/runtime/vue-plugin.js"
-    },
-    "./middleware": {
-      "import": "./dist/middleware.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
-    },
-    "./astro": {
-      "import": "./src/components/EzI18nHead.astro"
-    }
-  },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build",
-    "release": "pnpm build && npm publish",
-    "release:dry": "pnpm build && npm publish --dry-run"
-  },
-  "keywords": [
-    "astro",
-    "astro-integration",
-    "i18n",
-    "internationalization",
-    "vue",
-    "cookie-based",
-    "no-url-prefix"
-  ],
-  "author": "Zach Handley <zachhandley@gmail.com>",
-  "license": "MIT",
-  "homepage": "https://github.com/zachhandley/ez-i18n#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zachhandley/ez-i18n.git"
-  },
-  "bugs": {
-    "url": "https://github.com/zachhandley/ez-i18n/issues"
-  },
-  "peerDependencies": {
-    "astro": "^4.0.0 || ^5.0.0",
-    "vue": "^3.4.0",
-    "nanostores": "^0.9.0 || ^0.10.0 || ^0.11.0",
-    "@nanostores/persistent": "^0.10.0",
-    "@nanostores/vue": "^0.10.0"
-  },
-  "peerDependenciesMeta": {
-    "vue": {
-      "optional": true
-    },
-    "@nanostores/vue": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "astro": "^5.1.1",
-    "nanostores": "^0.11.3",
-    "@nanostores/persistent": "^0.10.2",
-    "@nanostores/vue": "^0.10.0",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vue": "^3.5.13",
-    "vite": "^6.0.3"
-  },
-  "packageManager": "pnpm@10.17.1+sha512.17c560fca4867ae9473a3899ad84a88334914f379be46d455cbf92e5cf4b39d34985d452d2583baf19967fa76cb5c17bc9e245529d0b98745721aa7200ecaf7a"
-}
+{
+  "name": "@zachhandley/ez-i18n",
+  "version": "0.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Cookie-based i18n for Astro + Vue + React. No URL prefixes, reactive language switching.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vue": {
+      "types": "./dist/runtime/vue-plugin.d.ts",
+      "import": "./dist/runtime/vue-plugin.js"
+    },
+    "./middleware": {
+      "import": "./dist/middleware.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./astro": {
+      "import": "./src/components/EzI18nHead.astro"
+    },
+    "./react": {
+      "types": "./dist/runtime/react-plugin.d.ts",
+      "import": "./dist/runtime/react-plugin.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build",
+    "release": "pnpm build && npm publish",
+    "release:dry": "pnpm build && npm publish --dry-run"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "i18n",
+    "internationalization",
+    "vue",
+    "react",
+    "cookie-based",
+    "no-url-prefix"
+  ],
+  "author": "Zach Handley <zachhandley@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/zachhandley/ez-i18n#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachhandley/ez-i18n.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zachhandley/ez-i18n/issues"
+  },
+  "dependencies": {
+    "tinyglobby": "^0.2.15"
+  },
+  "peerDependencies": {
+    "@nanostores/persistent": "^0.10.0",
+    "@nanostores/react": "^0.7.0 || ^0.8.0 || ^1.0.0",
+    "@nanostores/vue": "^0.10.0",
+    "astro": "^4.0.0 || ^5.0.0",
+    "nanostores": "^0.9.0 || ^0.10.0 || ^0.11.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@nanostores/vue": {
+      "optional": true
+    },
+    "@nanostores/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nanostores/persistent": "^0.10.2",
+    "@nanostores/react": "^1.0.0",
+    "@nanostores/vue": "^0.10.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.7",
+    "astro": "^5.1.1",
+    "nanostores": "^0.11.3",
+    "react": "^19.2.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.3",
+    "vue": "^3.5.13"
+  },
+  "packageManager": "pnpm@10.17.1+sha512.17c560fca4867ae9473a3899ad84a88334914f379be46d455cbf92e5cf4b39d34985d452d2583baf19967fa76cb5c17bc9e245529d0b98745721aa7200ecaf7a"
+}

package/src/components/EzI18nHead.astro

@@ -7,7 +7,7 @@
  *
  * @example
  * ---
- * import { EzI18nHead } from '@zachhandley/ez-i18n/astro';
+ * import EzI18nHead from '@zachhandley/ez-i18n/astro';
  * const { locale, translations } = Astro.locals;
  * ---
  * <html lang={locale}>