@zachhandley/ez-i18n 0.1.2 → 0.1.3

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,6 +1,6 @@
 {
   "name": "@zachhandley/ez-i18n",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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,52 @@ 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;
 }
 
 /**
- * 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[]>;
+}
+
+/**
+ * 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,13 @@
+export {
+  detectPathType,
+  resolveTranslationPaths,
+  autoDiscoverTranslations,
+  resolveTranslationsConfig,
+  deepMerge,
+  loadCache,
+  saveCache,
+  isCacheValid,
+  toRelativeImport,
+  toGlobPattern,
+  type PathType,
+} from './translations';

package/src/utils/translations.ts

@@ -0,0 +1,311 @@
+import { glob } from 'tinyglobby';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import type { LocaleTranslationPath, TranslationsConfig, TranslationCache } from '../types';
+
+const CACHE_FILE = '.ez-i18n.json';
+const CACHE_VERSION = 1;
+const DEFAULT_I18N_DIR = './public/i18n';
+
+export type PathType = 'file' | 'folder' | 'glob' | 'array';
+
+/**
+ * Detect the type of translation path
+ */
+export function detectPathType(input: string | string[]): PathType {
+  if (Array.isArray(input)) return 'array';
+  if (input.includes('*')) return 'glob';
+  if (input.endsWith('/') || input.endsWith(path.sep)) return 'folder';
+  return 'file';
+}
+
+/**
+ * Check if a path is a directory (handles missing trailing slash)
+ */
+function isDirectory(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a single translation path to an array of absolute file paths.
+ * Results are sorted alphabetically for predictable merge order.
+ */
+export async function resolveTranslationPaths(
+  input: LocaleTranslationPath,
+  projectRoot: string
+): Promise<string[]> {
+  const type = detectPathType(input);
+  let files: string[] = [];
+
+  switch (type) {
+    case 'array':
+      // Each entry could itself be a glob, folder, or file
+      for (const entry of input as string[]) {
+        const resolved = await resolveTranslationPaths(entry, projectRoot);
+        files.push(...resolved);
+      }
+      break;
+
+    case 'glob':
+      files = await glob(input as string, {
+        cwd: projectRoot,
+        absolute: true,
+      });
+      break;
+
+    case 'folder': {
+      const folderPath = path.resolve(projectRoot, (input as string).replace(/\/$/, ''));
+      files = await glob('**/*.json', {
+        cwd: folderPath,
+        absolute: true,
+      });
+      break;
+    }
+
+    case 'file':
+    default: {
+      const filePath = path.resolve(projectRoot, input as string);
+      // Check if it's actually a directory (user omitted trailing slash)
+      if (isDirectory(filePath)) {
+        files = await glob('**/*.json', {
+          cwd: filePath,
+          absolute: true,
+        });
+      } else {
+        files = [filePath];
+      }
+      break;
+    }
+  }
+
+  // Sort alphabetically for predictable merge order
+  return [...new Set(files)].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * 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.
+ */
+export async function autoDiscoverTranslations(
+  baseDir: string,
+  projectRoot: string,
+  configuredLocales?: string[]
+): Promise<{ locales: string[]; translations: Record<string, string[]> }> {
+  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: Record<string, string[]> = {};
+  const discoveredLocales: string[] = [];
+
+  // Read directory entries
+  const entries = fs.readdirSync(absoluteBaseDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // This is a locale folder (e.g., en/, es/)
+      const locale = entry.name;
+
+      // If locales were configured, only include matching ones
+      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')) {
+      // Root-level JSON files (e.g., en.json, es.json)
+      // Extract locale from filename
+      const locale = path.basename(entry.name, '.json');
+
+      // If locales were configured, only include matching ones
+      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);
+    }
+  }
+
+  // Sort locales for consistency
+  const sortedLocales = [...new Set(discoveredLocales)].sort();
+
+  return { locales: sortedLocales, translations };
+}
+
+/**
+ * Resolve the full translations config to normalized form.
+ * Handles string (base dir), object (per-locale), or undefined (auto-discover).
+ */
+export async function resolveTranslationsConfig(
+  config: TranslationsConfig | undefined,
+  projectRoot: string,
+  configuredLocales?: string[]
+): Promise<{ locales: string[]; translations: Record<string, string[]> }> {
+  // No config - auto-discover from default location
+  if (!config) {
+    return autoDiscoverTranslations(DEFAULT_I18N_DIR, projectRoot, configuredLocales);
+  }
+
+  // String - treat as base directory for auto-discovery
+  if (typeof config === 'string') {
+    return autoDiscoverTranslations(config, projectRoot, configuredLocales);
+  }
+
+  // Object - per-locale mapping
+  const translations: Record<string, string[]> = {};
+  const locales = Object.keys(config);
+
+  for (const [locale, localePath] of Object.entries(config)) {
+    translations[locale] = await resolveTranslationPaths(localePath, projectRoot);
+  }
+
+  return { locales, translations };
+}
+
+/**
+ * Deep merge translation objects.
+ * - Objects are recursively merged
+ * - Arrays are REPLACED (not concatenated)
+ * - Primitives are overwritten by later values
+ * - Prototype pollution safe
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: T[]
+): T {
+  const FORBIDDEN_KEYS = 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 as keyof T];
+      const sourceVal = source[key as keyof T];
+
+      if (
+        sourceVal !== null &&
+        typeof sourceVal === 'object' &&
+        !Array.isArray(sourceVal) &&
+        targetVal !== null &&
+        typeof targetVal === 'object' &&
+        !Array.isArray(targetVal)
+      ) {
+        // Both are plain objects - recurse
+        (result as Record<string, unknown>)[key] = deepMerge(
+          targetVal as Record<string, unknown>,
+          sourceVal as Record<string, unknown>
+        );
+      } else {
+        // Arrays replace, primitives overwrite
+        (result as Record<string, unknown>)[key] = sourceVal;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load cached translation discovery results
+ */
+export function loadCache(projectRoot: string): TranslationCache | null {
+  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) as TranslationCache;
+
+    // Validate cache version
+    if (cache.version !== CACHE_VERSION) return null;
+
+    return cache;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save translation discovery results to cache
+ */
+export function saveCache(
+  projectRoot: string,
+  discovered: Record<string, string[]>
+): void {
+  const cachePath = path.join(projectRoot, CACHE_FILE);
+
+  const cache: TranslationCache = {
+    version: CACHE_VERSION,
+    discovered,
+    lastScan: new Date().toISOString(),
+  };
+
+  try {
+    fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+  } catch (error) {
+    console.warn('[ez-i18n] Failed to write cache file:', error);
+  }
+}
+
+/**
+ * Check if cache is still valid (files haven't changed)
+ */
+export function isCacheValid(
+  cache: TranslationCache,
+  projectRoot: string
+): boolean {
+  // Check if all cached files still exist
+  for (const files of Object.values(cache.discovered)) {
+    for (const file of files) {
+      if (!fs.existsSync(file)) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Convert an absolute path to a relative import path for Vite
+ */
+export function toRelativeImport(absolutePath: string, projectRoot: string): string {
+  const relativePath = path.relative(projectRoot, absolutePath);
+  // Ensure it starts with ./ and uses forward slashes
+  const normalized = relativePath.replace(/\\/g, '/');
+  return normalized.startsWith('.') ? normalized : './' + normalized;
+}
+
+/**
+ * Generate a glob pattern for import.meta.glob from a base directory
+ */
+export function toGlobPattern(baseDir: string, projectRoot: string): string {
+  const relativePath = path.relative(projectRoot, baseDir).replace(/\\/g, '/');
+  const normalized = relativePath.startsWith('.') ? relativePath : './' + relativePath;
+  return `${normalized}/**/*.json`;
+}