@zachhandley/ez-i18n 0.1.1 → 0.1.3

package/README.md

@@ -1,13 +1,17 @@
 # @zachhandley/ez-i18n
 
-Cookie-based i18n for Astro + Vue. No URL prefixes, reactive language switching.
+Cookie-based i18n for Astro + Vue + React. No URL prefixes, reactive language switching.
 
 ## Installation
 
 ```bash
 pnpm add @zachhandley/ez-i18n nanostores @nanostores/persistent
+
 # If using Vue:
 pnpm add @nanostores/vue
+
+# If using React:
+pnpm add @nanostores/react
 ```
 
 ## Usage
@@ -55,6 +59,80 @@ export default defineConfig({
 
 Create similar files for each locale: `src/i18n/en.json`, `src/i18n/es.json`, etc.
 
+### Multi-File Translations
+
+ez-i18n supports flexible translation file organization:
+
+#### Auto-Discovery (Zero Config)
+
+Just put your files in `public/i18n/` and ez-i18n will discover them automatically:
+
+```
+public/i18n/
+  en/
+    common.json
+    auth.json
+  es/
+    common.json
+    auth.json
+```
+
+```typescript
+// astro.config.ts - locales auto-discovered from folder names!
+ezI18n({
+  defaultLocale: 'en',
+  // No locales or translations needed - auto-discovered
+})
+```
+
+#### Base Directory
+
+Point to a folder and locales are discovered from subfolders:
+
+```typescript
+ezI18n({
+  defaultLocale: 'en',
+  translations: './src/i18n/',  // Discovers en/, es/, fr/ folders
+})
+```
+
+#### Per-Locale with Multiple Formats
+
+Mix and match different formats per locale:
+
+```typescript
+ezI18n({
+  locales: ['en', 'es', 'fr', 'de'],
+  defaultLocale: 'en',
+  translations: {
+    en: './src/i18n/en.json',              // Single file
+    es: './src/i18n/es/',                   // Folder (all JSONs merged)
+    fr: './src/i18n/fr/**/*.json',          // Glob pattern
+    de: ['./src/i18n/de/common.json',       // Array of files
+         './src/i18n/de/auth.json'],
+  },
+})
+```
+
+#### Merge Order
+
+When using multiple files per locale, files are merged **alphabetically by filename**. Later files override earlier ones for conflicting keys.
+
+```
+en/
+  01-common.json    # Loaded first
+  02-features.json  # Loaded second, overrides common
+  99-overrides.json # Loaded last, highest priority
+```
+
+#### Cache File
+
+A `.ez-i18n.json` cache file is generated to speed up subsequent builds. Add it to `.gitignore`:
+
+```gitignore
+.ez-i18n.json
+```
+
 ### Layout Setup
 
 Add the `EzI18nHead` component to your layout's head for automatic hydration:
@@ -62,7 +140,7 @@ Add the `EzI18nHead` component to your layout's head for automatic hydration:
 ```astro
 ---
 // src/layouts/Layout.astro
-import { EzI18nHead } from '@zachhandley/ez-i18n/astro';
+import EzI18nHead from '@zachhandley/ez-i18n/astro';
 const { locale, translations } = Astro.locals;
 ---
 
@@ -134,14 +212,43 @@ export default (app: App) => {
 };
 ```
 
+### In React Components
+
+```tsx
+import { useI18n } from '@zachhandley/ez-i18n/react';
+import { translationLoaders } from 'ez-i18n:translations';
+
+function MyComponent() {
+  const { t, locale, setLocale } = useI18n();
+
+  async function switchLocale(newLocale: string) {
+    await setLocale(newLocale, {
+      loadTranslations: translationLoaders[newLocale],
+    });
+  }
+
+  return (
+    <div>
+      <h1>{t('common.welcome')}</h1>
+      <p>{t('greeting', { name: 'World' })}</p>
+      <button onClick={() => switchLocale('es')}>Español</button>
+      <button onClick={() => switchLocale('fr')}>Français</button>
+    </div>
+  );
+}
+```
+
 ## Features
 
 - **No URL prefixes** - Locale stored in cookie, not URL path
 - **Reactive** - Language changes update immediately without page reload
 - **SSR compatible** - Proper hydration with server-rendered locale
 - **Vue integration** - Global `$t()`, `$locale`, `$setLocale` in templates
-- **Composable API** - `useI18n()` for Composition API usage
+- **React integration** - `useI18n()` hook for React components
 - **Middleware included** - Auto-detects locale from cookie, query param, or Accept-Language header
+- **Multi-file support** - Organize translations in folders, use globs, or arrays
+- **Auto-discovery** - Automatic locale detection from folder structure
+- **HMR in dev** - Hot reload translation changes without restart
 
 ## Locale Detection Priority
 
@@ -158,10 +265,16 @@ Astro integration function.
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `locales` | `string[]` | Yes | Supported locale codes |
+| `locales` | `string[]` | No | Supported locale codes (auto-discovered if not provided) |
 | `defaultLocale` | `string` | Yes | Fallback locale |
 | `cookieName` | `string` | No | Cookie name (default: `'ez-locale'`) |
-| `translations` | `Record<string, string>` | No | Paths to translation files (auto-loaded) |
+| `translations` | `string \| Record<string, TranslationPath>` | No | Base directory or per-locale paths (default: `./public/i18n/`) |
+
+**TranslationPath** can be:
+- Single file: `'./src/i18n/en.json'`
+- Folder: `'./src/i18n/en/'`
+- Glob: `'./src/i18n/en/**/*.json'`
+- Array: `['./common.json', './auth.json']`
 
 ### `EzI18nHead`
 
@@ -195,9 +308,15 @@ setLocale('es', { loadTranslations: translationLoaders['es'] });
 
 ### `useI18n()`
 
-Vue composable for Composition API usage.
+Hook for Vue (Composition API) and React.
 
 ```typescript
+// Vue
+import { useI18n } from '@zachhandley/ez-i18n/vue';
+
+// React
+import { useI18n } from '@zachhandley/ez-i18n/react';
+
 const { t, locale, setLocale } = useI18n();
 ```
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroIntegration } from 'astro';
-import { E as EzI18nConfig } from './types-DwCG8sp8.js';
-export { T as TranslateFunction } from './types-DwCG8sp8.js';
+import { E as EzI18nConfig } from './types-CHyDGt_C.js';
+export { T as TranslateFunction } from './types-CHyDGt_C.js';
 
 /**
  * ez-i18n Astro integration

package/dist/index.js

@@ -1,21 +1,235 @@
+// 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 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`;
+}
+
 // src/vite-plugin.ts
+import * as path2 from "path";
 var VIRTUAL_CONFIG = "ez-i18n:config";
 var VIRTUAL_RUNTIME = "ez-i18n:runtime";
 var VIRTUAL_TRANSLATIONS = "ez-i18n:translations";
 var RESOLVED_PREFIX = "\0";
-function resolveConfig(config) {
-  return {
-    locales: config.locales,
-    defaultLocale: config.defaultLocale,
-    cookieName: config.cookieName ?? "ez-locale",
-    translations: config.translations ?? {}
-  };
-}
 function vitePlugin(config) {
-  const resolved = resolveConfig(config);
+  let viteConfig;
+  let isDev = false;
+  let resolved;
+  let translationInfo = /* @__PURE__ */ new Map();
   return {
     name: "ez-i18n-vite",
     enforce: "pre",
+    configResolved(resolvedConfig) {
+      viteConfig = resolvedConfig;
+      isDev = resolvedConfig.command === "serve";
+    },
+    async buildStart() {
+      const projectRoot = viteConfig.root;
+      let useCache = false;
+      if (!isDev) {
+        const cache = loadCache(projectRoot);
+        if (cache && isCacheValid(cache, projectRoot)) {
+          resolved = {
+            locales: config.locales || Object.keys(cache.discovered),
+            defaultLocale: config.defaultLocale,
+            cookieName: config.cookieName ?? "ez-locale",
+            translations: cache.discovered
+          };
+          useCache = true;
+          for (const [locale, files] of Object.entries(cache.discovered)) {
+            translationInfo.set(locale, { locale, files });
+          }
+        }
+      }
+      if (!useCache) {
+        const { locales, translations } = await resolveTranslationsConfig(
+          config.translations,
+          projectRoot,
+          config.locales
+        );
+        const finalLocales = config.locales && config.locales.length > 0 ? config.locales : locales;
+        resolved = {
+          locales: finalLocales,
+          defaultLocale: config.defaultLocale,
+          cookieName: config.cookieName ?? "ez-locale",
+          translations
+        };
+        for (const locale of finalLocales) {
+          const files = translations[locale] || [];
+          const info = { locale, files };
+          if (isDev && config.translations) {
+            const localeConfig = typeof config.translations === "string" ? path2.join(config.translations, locale) : config.translations[locale];
+            if (localeConfig && typeof localeConfig === "string") {
+              const pathType = detectPathType(localeConfig);
+              if (pathType === "folder" || pathType === "glob") {
+                const basePath = pathType === "glob" ? localeConfig : toGlobPattern(path2.resolve(projectRoot, localeConfig), projectRoot);
+                info.globPattern = basePath;
+              }
+            }
+          }
+          translationInfo.set(locale, info);
+        }
+        if (!isDev && Object.keys(translations).length > 0) {
+          saveCache(projectRoot, translations);
+        }
+      }
+      if (!resolved.locales.includes(resolved.defaultLocale)) {
+        console.warn(
+          `[ez-i18n] defaultLocale "${resolved.defaultLocale}" not found in locales: [${resolved.locales.join(", ")}]`
+        );
+      }
+    },
     resolveId(id) {
       if (id === VIRTUAL_CONFIG || id === VIRTUAL_RUNTIME || id === VIRTUAL_TRANSLATIONS) {
         return RESOLVED_PREFIX + id;
@@ -81,21 +295,101 @@ export function t(key, params) {
 `;
       }
       if (id === RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS) {
-        const loaderEntries = Object.entries(resolved.translations).map(([locale, path]) => `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(path)})`).join(",\n");
-        return `
-/**
- * Translation loaders for ez-i18n
- * Auto-generated from config
- */
+        return isDev ? generateDevTranslationsModule(translationInfo, viteConfig.root) : generateBuildTranslationsModule(translationInfo, viteConfig.root);
+      }
+      return null;
+    },
+    // HMR support for dev mode
+    handleHotUpdate({ file, server }) {
+      if (!isDev) return;
+      for (const info of translationInfo.values()) {
+        if (info.files.includes(file)) {
+          const mod = server.moduleGraph.getModuleById(RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS);
+          if (mod) {
+            server.moduleGraph.invalidateModule(mod);
+            server.ws.send({
+              type: "full-reload",
+              path: "*"
+            });
+          }
+          break;
+        }
+      }
+    },
+    configureServer(server) {
+      const watchedDirs = /* @__PURE__ */ new Set();
+      if (config.translations) {
+        if (typeof config.translations === "string") {
+          watchedDirs.add(path2.resolve(viteConfig.root, config.translations));
+        } else {
+          for (const localePath of Object.values(config.translations)) {
+            if (typeof localePath === "string") {
+              const pathType = detectPathType(localePath);
+              if (pathType === "folder") {
+                watchedDirs.add(path2.resolve(viteConfig.root, localePath));
+              } else if (pathType === "glob") {
+                const baseDir = localePath.split("*")[0].replace(/\/$/, "");
+                if (baseDir) {
+                  watchedDirs.add(path2.resolve(viteConfig.root, baseDir));
+                }
+              }
+            } else if (Array.isArray(localePath)) {
+              for (const file of localePath) {
+                const dir = path2.dirname(path2.resolve(viteConfig.root, file));
+                watchedDirs.add(dir);
+              }
+            }
+          }
+        }
+      } else {
+        watchedDirs.add(path2.resolve(viteConfig.root, "./public/i18n"));
+      }
+      for (const dir of watchedDirs) {
+        server.watcher.add(dir);
+      }
+    }
+  };
+}
+function generateDevTranslationsModule(translationInfo, projectRoot) {
+  const imports = [];
+  const loaderEntries = [];
+  imports.push(getDeepMergeCode());
+  for (const [locale, info] of translationInfo) {
+    if (info.files.length === 0) {
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => ({})`);
+    } else if (info.globPattern) {
+      const varName = `__${locale}Modules`;
+      imports.push(
+        `const ${varName} = import.meta.glob(${JSON.stringify(info.globPattern)}, { eager: true, import: 'default' });`
+      );
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const modules = Object.values(${varName});
+    if (modules.length === 0) return {};
+    if (modules.length === 1) return modules[0];
+    return __deepMerge({}, ...modules);
+  }`);
+    } else if (info.files.length === 1) {
+      const relativePath = toRelativeImport(info.files[0], projectRoot);
+      loaderEntries.push(
+        `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
+      );
+    } else {
+      const fileImports = info.files.map((f) => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`).join(", ");
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const modules = await Promise.all([${fileImports}]);
+    const contents = modules.map(m => m.default ?? m);
+    if (contents.length === 1) return contents[0];
+    return __deepMerge({}, ...contents);
+  }`);
+    }
+  }
+  return `
+${imports.join("\n")}
+
 export const translationLoaders = {
-${loaderEntries}
+${loaderEntries.join(",\n")}
 };
 
-/**
- * Load translations for a specific locale
- * @param locale - Locale code to load translations for
- * @returns Translations object or empty object if not found
- */
 export async function loadTranslations(locale) {
   const loader = translationLoaders[locale];
   if (!loader) {
@@ -106,8 +400,7 @@ export async function loadTranslations(locale) {
   }
 
   try {
-    const mod = await loader();
-    return mod.default ?? mod;
+    return await loader();
   } catch (error) {
     if (import.meta.env.DEV) {
       console.error('[ez-i18n] Failed to load translations for locale:', locale, error);
@@ -116,9 +409,77 @@ export async function loadTranslations(locale) {
   }
 }
 `;
+}
+function generateBuildTranslationsModule(translationInfo, projectRoot) {
+  const loaderEntries = [];
+  let needsDeepMerge = false;
+  for (const [locale, info] of translationInfo) {
+    if (info.files.length === 0) {
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => ({})`);
+    } else if (info.files.length === 1) {
+      const relativePath = toRelativeImport(info.files[0], projectRoot);
+      loaderEntries.push(
+        `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
+      );
+    } else {
+      needsDeepMerge = true;
+      const fileImports = info.files.map((f) => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`).join(", ");
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const modules = await Promise.all([${fileImports}]);
+    const contents = modules.map(m => m.default ?? m);
+    return __deepMerge({}, ...contents);
+  }`);
+    }
+  }
+  const deepMergeCode = needsDeepMerge ? getDeepMergeCode() : "";
+  return `
+${deepMergeCode}
+
+export const translationLoaders = {
+${loaderEntries.join(",\n")}
+};
+
+export async function loadTranslations(locale) {
+  const loader = translationLoaders[locale];
+  if (!loader) {
+    return {};
+  }
+
+  try {
+    return await loader();
+  } catch (error) {
+    console.error('[ez-i18n] Failed to load translations:', locale, error);
+    return {};
+  }
+}
+`;
+}
+function getDeepMergeCode() {
+  return `
+function __deepMerge(target, ...sources) {
+  const FORBIDDEN = 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.has(key)) continue;
+      const tv = result[key], sv = source[key];
+      if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+        result[key] = __deepMerge(tv, sv);
+      } else {
+        result[key] = sv;
       }
-      return null;
     }
+  }
+  return result;
+}`;
+}
+function resolveConfig(config) {
+  return {
+    locales: config.locales || [],
+    defaultLocale: config.defaultLocale,
+    cookieName: config.cookieName ?? "ez-locale",
+    translations: {}
   };
 }
 

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

@@ -0,0 +1,29 @@
+import { setLocale } from './index.js';
+import { T as TranslateFunction } from '../types-CHyDGt_C.js';
+import 'nanostores';
+
+/**
+ * React hook for i18n
+ *
+ * @example
+ * import { useI18n } from '@zachhandley/ez-i18n/react';
+ *
+ * function MyComponent() {
+ *   const { t, locale, setLocale } = useI18n();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t('common.welcome')}</h1>
+ *       <p>{t('greeting', { name: 'World' })}</p>
+ *       <button onClick={() => setLocale('es')}>Español</button>
+ *     </div>
+ *   );
+ * }
+ */
+declare function useI18n(): {
+    t: TranslateFunction;
+    locale: string;
+    setLocale: typeof setLocale;
+};
+
+export { useI18n };