@zachhandley/ez-i18n 0.1.2 → 0.1.5

package/dist/utils/index.d.ts

@@ -0,0 +1,85 @@
+import { L as LocaleTranslationPath, a as TranslationsConfig, b as TranslationCache } from '../types-Cd9e7Lkc.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;
+/**
+ * Get namespace from file path relative to locale base directory.
+ *
+ * Examples:
+ * - filePath: /project/public/i18n/en/auth/login.json, localeDir: /project/public/i18n/en
+ *   → namespace: 'auth.login'
+ * - filePath: /project/public/i18n/en/common.json, localeDir: /project/public/i18n/en
+ *   → namespace: 'common'
+ * - filePath: /project/public/i18n/en/settings/index.json, localeDir: /project/public/i18n/en
+ *   → namespace: 'settings' (index is stripped)
+ */
+declare function getNamespaceFromPath(filePath: string, localeDir: string): string;
+/**
+ * Wrap a translation object with its namespace.
+ *
+ * Example:
+ * - namespace: 'auth.login'
+ * - content: { title: 'Welcome', subtitle: 'Login here' }
+ * - result: { auth: { login: { title: 'Welcome', subtitle: 'Login here' } } }
+ */
+declare function wrapWithNamespace(namespace: string, content: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Generate code that wraps imported content with namespace at runtime.
+ * Used in virtual module generation.
+ */
+declare function generateNamespaceWrapperCode(): string;
+
+export { type PathType, autoDiscoverTranslations, deepMerge, detectPathType, generateNamespaceWrapperCode, getNamespaceFromPath, isCacheValid, loadCache, resolveTranslationPaths, resolveTranslationsConfig, saveCache, toGlobPattern, toRelativeImport, wrapWithNamespace };

package/dist/utils/index.js

@@ -0,0 +1,220 @@
+// 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`;
+}
+function getNamespaceFromPath(filePath, localeDir) {
+  const relative2 = path.relative(localeDir, filePath);
+  const withoutExt = relative2.replace(/\.json$/i, "");
+  const namespace = withoutExt.replace(/[\\/]/g, ".");
+  return namespace.replace(/\.index$/, "");
+}
+function wrapWithNamespace(namespace, content) {
+  if (!namespace) return content;
+  const parts = namespace.split(".");
+  let result = content;
+  for (let i = parts.length - 1; i >= 0; i--) {
+    result = { [parts[i]]: result };
+  }
+  return result;
+}
+function generateNamespaceWrapperCode() {
+  return `
+function __wrapWithNamespace(namespace, content) {
+  if (!namespace) return content;
+  const parts = namespace.split('.');
+  let result = content;
+  for (let i = parts.length - 1; i >= 0; i--) {
+    result = { [parts[i]]: result };
+  }
+  return result;
+}`;
+}
+export {
+  autoDiscoverTranslations,
+  deepMerge,
+  detectPathType,
+  generateNamespaceWrapperCode,
+  getNamespaceFromPath,
+  isCacheValid,
+  loadCache,
+  resolveTranslationPaths,
+  resolveTranslationsConfig,
+  saveCache,
+  toGlobPattern,
+  toRelativeImport,
+  wrapWithNamespace
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachhandley/ez-i18n",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "publishConfig": {
     "access": "public"
   },
@@ -30,6 +30,10 @@
     "./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": [
@@ -64,6 +68,9 @@
   "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",

package/src/types.ts

@@ -1,14 +1,33 @@
+/**
+ * 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']`
+ */
+export 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' }
+ */
+export type TranslationsConfig = string | Record<string, LocaleTranslationPath>;
+
 /**
  * Configuration for ez-i18n Astro integration
  */
 export 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[];
+  locales?: string[];
 
   /**
-   * Default locale to use when no preference is detected
+   * Default locale to use when no preference is detected.
+   * Required - this tells us what to fall back to.
    */
   defaultLocale: string;
 
@@ -19,26 +38,69 @@ export interface EzI18nConfig {
   cookieName?: string;
 
   /**
-   * Translation file paths for each locale.
+   * Translation file paths configuration.
    * Paths are relative to your project root.
-   * Dynamic imports will be generated for code splitting.
-   * @example
-   * translations: {
-   *   en: './src/i18n/en.json',
-   *   es: './src/i18n/es.json',
-   * }
+   *
+   * 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?: Record<string, string>;
+  translations?: TranslationsConfig;
+
+  /**
+   * Derive namespace from file path relative to locale folder.
+   *
+   * When enabled:
+   * - `en/auth/login.json` with `{ "title": "..." }` → `$t('auth.login.title')`
+   * - `en/common.json` with `{ "actions": {...} }` → `$t('common.actions.save')`
+   *
+   * The file path (minus locale folder and .json extension) becomes the key prefix.
+   *
+   * @default true when using folder-based translations config
+   */
+  pathBasedNamespacing?: boolean;
 }
 
 /**
- * Resolved config with defaults applied
+ * Resolved config with defaults applied.
+ * After resolution:
+ * - locales is always populated (from config or auto-discovered)
+ * - translations is normalized to arrays of absolute file paths
  */
 export interface ResolvedEzI18nConfig {
   locales: string[];
   defaultLocale: string;
   cookieName: string;
-  translations: Record<string, string>;
+  /** Normalized: locale → array of resolved absolute file paths */
+  translations: Record<string, string[]>;
+  /** Whether to derive namespace from file path */
+  pathBasedNamespacing: boolean;
+  /** Base directory for each locale (used for namespace calculation) */
+  localeBaseDirs: Record<string, string>;
+}
+
+/**
+ * Cache file structure (.ez-i18n.json)
+ * Used to speed up subsequent builds by caching discovered translations
+ */
+export interface TranslationCache {
+  version: number;
+  /** Discovered locale → file paths mapping */
+  discovered: Record<string, string[]>;
+  /** ISO timestamp of last scan */
+  lastScan: string;
 }
 
 /**

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+export {
+  detectPathType,
+  resolveTranslationPaths,
+  autoDiscoverTranslations,
+  resolveTranslationsConfig,
+  deepMerge,
+  loadCache,
+  saveCache,
+  isCacheValid,
+  toRelativeImport,
+  toGlobPattern,
+  getNamespaceFromPath,
+  wrapWithNamespace,
+  generateNamespaceWrapperCode,
+  type PathType,
+} from './translations';