@zachhandley/ez-i18n 0.1.2 → 0.1.5

package/dist/index.js

@@ -1,21 +1,294 @@
+// 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`;
+}
+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 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;
+}`;
+}
+
 // 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;
+      const isAutoDiscovery = !config.translations || typeof config.translations === "string";
+      const pathBasedNamespacing = config.pathBasedNamespacing ?? isAutoDiscovery;
+      const translationsBaseDir = typeof config.translations === "string" ? path2.resolve(projectRoot, config.translations.replace(/\/$/, "")) : path2.resolve(projectRoot, "./public/i18n");
+      let useCache = false;
+      if (!isDev) {
+        const cache = loadCache(projectRoot);
+        if (cache && isCacheValid(cache, projectRoot)) {
+          const localeBaseDirs = {};
+          for (const locale of Object.keys(cache.discovered)) {
+            localeBaseDirs[locale] = path2.join(translationsBaseDir, locale);
+          }
+          resolved = {
+            locales: config.locales || Object.keys(cache.discovered),
+            defaultLocale: config.defaultLocale,
+            cookieName: config.cookieName ?? "ez-locale",
+            translations: cache.discovered,
+            pathBasedNamespacing,
+            localeBaseDirs
+          };
+          useCache = true;
+          for (const [locale, files] of Object.entries(cache.discovered)) {
+            translationInfo.set(locale, {
+              locale,
+              files,
+              localeBaseDir: localeBaseDirs[locale]
+            });
+          }
+        }
+      }
+      if (!useCache) {
+        const { locales, translations } = await resolveTranslationsConfig(
+          config.translations,
+          projectRoot,
+          config.locales
+        );
+        const finalLocales = config.locales && config.locales.length > 0 ? config.locales : locales;
+        const localeBaseDirs = {};
+        for (const locale of finalLocales) {
+          if (isAutoDiscovery) {
+            localeBaseDirs[locale] = path2.join(translationsBaseDir, locale);
+          } else if (typeof config.translations === "object" && config.translations[locale]) {
+            const localeConfig = config.translations[locale];
+            if (typeof localeConfig === "string") {
+              const pathType = detectPathType(localeConfig);
+              if (pathType === "folder" || pathType === "file") {
+                const resolved2 = path2.resolve(projectRoot, localeConfig.replace(/\/$/, ""));
+                localeBaseDirs[locale] = pathType === "folder" ? resolved2 : path2.dirname(resolved2);
+              } else {
+                const baseDir = localeConfig.split("*")[0].replace(/\/$/, "");
+                localeBaseDirs[locale] = path2.resolve(projectRoot, baseDir);
+              }
+            } else {
+              localeBaseDirs[locale] = translationsBaseDir;
+            }
+          } else {
+            localeBaseDirs[locale] = translationsBaseDir;
+          }
+        }
+        resolved = {
+          locales: finalLocales,
+          defaultLocale: config.defaultLocale,
+          cookieName: config.cookieName ?? "ez-locale",
+          translations,
+          pathBasedNamespacing,
+          localeBaseDirs
+        };
+        for (const locale of finalLocales) {
+          const files = translations[locale] || [];
+          const info = {
+            locale,
+            files,
+            localeBaseDir: localeBaseDirs[locale]
+          };
+          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 +354,143 @@ 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, resolved.pathBasedNamespacing) : generateBuildTranslationsModule(translationInfo, viteConfig.root, resolved.pathBasedNamespacing);
+      }
+      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, pathBasedNamespacing) {
+  const imports = [];
+  const loaderEntries = [];
+  imports.push(getDeepMergeCode());
+  if (pathBasedNamespacing) {
+    imports.push(generateNamespaceWrapperCode());
+  }
+  for (const [locale, info] of translationInfo) {
+    if (info.files.length === 0) {
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => ({})`);
+    } else if (info.globPattern && pathBasedNamespacing && info.localeBaseDir) {
+      const varName = `__${locale}Modules`;
+      const localeBaseDir = info.localeBaseDir.replace(/\\/g, "/");
+      imports.push(
+        `const ${varName} = import.meta.glob(${JSON.stringify(info.globPattern)}, { eager: true, import: 'default' });`
+      );
+      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const entries = Object.entries(${varName});
+    if (entries.length === 0) return {};
+    const localeBaseDir = ${JSON.stringify(localeBaseDir)};
+    const wrapped = entries.map(([filePath, content]) => {
+      // Extract relative path from locale base dir
+      const relativePath = filePath.replace(localeBaseDir + '/', '').replace(/\\.json$/i, '');
+      const namespace = relativePath.replace(/[\\/]/g, '.').replace(/\\.index$/, '');
+      return __wrapWithNamespace(namespace, content);
+    });
+    return __deepMerge({}, ...wrapped);
+  }`);
+    } 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);
+      if (pathBasedNamespacing && info.localeBaseDir) {
+        const namespace = getNamespaceFromPath(info.files[0], info.localeBaseDir);
+        loaderEntries.push(
+          `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => __wrapWithNamespace(${JSON.stringify(namespace)}, m.default ?? m))`
+        );
+      } else {
+        loaderEntries.push(
+          `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
+        );
+      }
+    } else {
+      if (pathBasedNamespacing && info.localeBaseDir) {
+        const fileEntries = info.files.map((f) => {
+          const relativePath = toRelativeImport(f, projectRoot);
+          const namespace = getNamespaceFromPath(f, info.localeBaseDir);
+          return `{ path: ${JSON.stringify(relativePath)}, namespace: ${JSON.stringify(namespace)} }`;
+        });
+        loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const fileInfos = [${fileEntries.join(", ")}];
+    const modules = await Promise.all(fileInfos.map(f => import(f.path)));
+    const wrapped = modules.map((m, i) => __wrapWithNamespace(fileInfos[i].namespace, m.default ?? m));
+    return __deepMerge({}, ...wrapped);
+  }`);
+      } 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 +501,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 +510,107 @@ export async function loadTranslations(locale) {
   }
 }
 `;
+}
+function generateBuildTranslationsModule(translationInfo, projectRoot, pathBasedNamespacing) {
+  const loaderEntries = [];
+  let needsDeepMerge = false;
+  let needsNamespaceWrapper = 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);
+      if (pathBasedNamespacing && info.localeBaseDir) {
+        needsNamespaceWrapper = true;
+        const namespace = getNamespaceFromPath(info.files[0], info.localeBaseDir);
+        loaderEntries.push(
+          `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => __wrapWithNamespace(${JSON.stringify(namespace)}, m.default ?? m))`
+        );
+      } else {
+        loaderEntries.push(
+          `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
+        );
+      }
+    } else {
+      needsDeepMerge = true;
+      if (pathBasedNamespacing && info.localeBaseDir) {
+        needsNamespaceWrapper = true;
+        const fileEntries = info.files.map((f) => {
+          const relativePath = toRelativeImport(f, projectRoot);
+          const namespace = getNamespaceFromPath(f, info.localeBaseDir);
+          return `{ path: ${JSON.stringify(relativePath)}, namespace: ${JSON.stringify(namespace)} }`;
+        });
+        loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+    const fileInfos = [${fileEntries.join(", ")}];
+    const modules = await Promise.all(fileInfos.map(f => import(f.path)));
+    const wrapped = modules.map((m, i) => __wrapWithNamespace(fileInfos[i].namespace, m.default ?? m));
+    return __deepMerge({}, ...wrapped);
+  }`);
+      } 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);
+    return __deepMerge({}, ...contents);
+  }`);
       }
-      return null;
     }
+  }
+  const helperCode = [
+    needsDeepMerge ? getDeepMergeCode() : "",
+    needsNamespaceWrapper ? generateNamespaceWrapperCode() : ""
+  ].filter(Boolean).join("\n");
+  return `
+${helperCode}
+
+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 result;
+}`;
+}
+function resolveConfig(config) {
+  const isAutoDiscovery = !config.translations || typeof config.translations === "string";
+  return {
+    locales: config.locales || [],
+    defaultLocale: config.defaultLocale,
+    cookieName: config.cookieName ?? "ez-locale",
+    translations: {},
+    pathBasedNamespacing: config.pathBasedNamespacing ?? isAutoDiscovery,
+    localeBaseDirs: {}
   };
 }
 

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

@@ -1,5 +1,5 @@
 import { setLocale } from './index.js';
-import { T as TranslateFunction } from '../types-DwCG8sp8.js';
+import { T as TranslateFunction } from '../types-Cd9e7Lkc.js';
 import 'nanostores';
 
 /**

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-Cd9e7Lkc.js';
 import 'nanostores';
 
 /**

package/dist/types-Cd9e7Lkc.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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;
+    /**
+     * 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;
+}
+/**
+ * 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 };