@zachhandley/ez-i18n 0.1.3 → 0.1.6

package/README.md

@@ -125,6 +125,44 @@ en/
   99-overrides.json # Loaded last, highest priority
 ```
 
+#### Path-Based Namespacing
+
+When using folder-based translation organization, ez-i18n automatically creates namespaces from your file paths. This is **enabled by default** when using folder-based config.
+
+**Example:**
+
+```
+public/i18n/
+  en/
+    auth/
+      login.json     # { "title": "Sign In", "button": "Log In" }
+      signup.json    # { "title": "Create Account" }
+    common.json      # { "welcome": "Welcome" }
+```
+
+Access translations using dot notation that mirrors the folder structure:
+
+```typescript
+$t('auth.login.title')     // "Sign In"
+$t('auth.login.button')    // "Log In"
+$t('auth.signup.title')    // "Create Account"
+$t('common.welcome')       // "Welcome"
+```
+
+**Disable path-based namespacing:**
+
+If you prefer to manage namespaces manually within your JSON files, you can disable this feature:
+
+```typescript
+ezI18n({
+  defaultLocale: 'en',
+  translations: './src/i18n/',
+  pathBasedNamespacing: false,  // Disable automatic path namespacing
+})
+```
+
+With `pathBasedNamespacing: false`, the file structure is ignored and keys are used directly from each JSON file.
+
 #### Cache File
 
 A `.ez-i18n.json` cache file is generated to speed up subsequent builds. Add it to `.gitignore`:
@@ -248,6 +286,7 @@ function MyComponent() {
 - **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
+- **Path-based namespacing** - Automatic namespacing from folder structure (`auth/login.json` becomes `auth.login.*`)
 - **HMR in dev** - Hot reload translation changes without restart
 
 ## Locale Detection Priority
@@ -269,6 +308,7 @@ Astro integration function.
 | `defaultLocale` | `string` | Yes | Fallback locale |
 | `cookieName` | `string` | No | Cookie name (default: `'ez-locale'`) |
 | `translations` | `string \| Record<string, TranslationPath>` | No | Base directory or per-locale paths (default: `./public/i18n/`) |
+| `pathBasedNamespacing` | `boolean` | No | Auto-namespace translations from folder paths (default: `true` for folder-based config) |
 
 **TranslationPath** can be:
 - Single file: `'./src/i18n/en.json'`

package/dist/index.d.ts

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

package/dist/index.js

@@ -155,6 +155,24 @@ function toGlobPattern(baseDir, projectRoot) {
   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";
@@ -176,19 +194,32 @@ function vitePlugin(config) {
     },
     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
+            translations: cache.discovered,
+            pathBasedNamespacing,
+            localeBaseDirs
           };
           useCache = true;
           for (const [locale, files] of Object.entries(cache.discovered)) {
-            translationInfo.set(locale, { locale, files });
+            translationInfo.set(locale, {
+              locale,
+              files,
+              localeBaseDir: localeBaseDirs[locale]
+            });
           }
         }
       }
@@ -199,15 +230,43 @@ function vitePlugin(config) {
           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
+          translations,
+          pathBasedNamespacing,
+          localeBaseDirs
         };
         for (const locale of finalLocales) {
           const files = translations[locale] || [];
-          const info = { locale, files };
+          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") {
@@ -295,13 +354,14 @@ export function t(key, params) {
 `;
       }
       if (id === RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS) {
-        return isDev ? generateDevTranslationsModule(translationInfo, viteConfig.root) : generateBuildTranslationsModule(translationInfo, viteConfig.root);
+        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;
+      if (!file.endsWith(".json")) return;
       for (const info of translationInfo.values()) {
         if (info.files.includes(file)) {
           const mod = server.moduleGraph.getModuleById(RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS);
@@ -350,13 +410,34 @@ export function t(key, params) {
     }
   };
 }
-function generateDevTranslationsModule(translationInfo, projectRoot) {
+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(
@@ -370,17 +451,38 @@ function generateDevTranslationsModule(translationInfo, projectRoot) {
   }`);
     } 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)`
-      );
+      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 {
-      const fileImports = info.files.map((f) => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`).join(", ");
-      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+      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 `
@@ -410,30 +512,57 @@ export async function loadTranslations(locale) {
 }
 `;
 }
-function generateBuildTranslationsModule(translationInfo, projectRoot) {
+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);
-      loaderEntries.push(
-        `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
-      );
+      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;
-      const fileImports = info.files.map((f) => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`).join(", ");
-      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+      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);
   }`);
+      }
     }
   }
-  const deepMergeCode = needsDeepMerge ? getDeepMergeCode() : "";
+  const helperCode = [
+    needsDeepMerge ? getDeepMergeCode() : "",
+    needsNamespaceWrapper ? generateNamespaceWrapperCode() : ""
+  ].filter(Boolean).join("\n");
   return `
-${deepMergeCode}
+${helperCode}
 
 export const translationLoaders = {
 ${loaderEntries.join(",\n")}
@@ -475,11 +604,14 @@ function __deepMerge(target, ...sources) {
 }`;
 }
 function resolveConfig(config) {
+  const isAutoDiscovery = !config.translations || typeof config.translations === "string";
   return {
     locales: config.locales || [],
     defaultLocale: config.defaultLocale,
     cookieName: config.cookieName ?? "ez-locale",
-    translations: {}
+    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-CHyDGt_C.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-CHyDGt_C.js';
+import { T as TranslateFunction } from '../types-Cd9e7Lkc.js';
 import 'nanostores';
 
 /**

package/dist/{types-CHyDGt_C.d.ts → types-Cd9e7Lkc.d.ts}

@@ -53,6 +53,18 @@ interface EzI18nConfig {
      * 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)

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { L as LocaleTranslationPath, a as TranslationsConfig, b as TranslationCache } from '../types-CHyDGt_C.js';
+import { L as LocaleTranslationPath, a as TranslationsConfig, b as TranslationCache } from '../types-Cd9e7Lkc.js';
 
 type PathType = 'file' | 'folder' | 'glob' | 'array';
 /**
@@ -55,5 +55,31 @@ declare function toRelativeImport(absolutePath: string, projectRoot: string): st
  * 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, isCacheValid, loadCache, resolveTranslationPaths, resolveTranslationsConfig, saveCache, toGlobPattern, toRelativeImport };
+export { type PathType, autoDiscoverTranslations, deepMerge, detectPathType, generateNamespaceWrapperCode, getNamespaceFromPath, isCacheValid, loadCache, resolveTranslationPaths, resolveTranslationsConfig, saveCache, toGlobPattern, toRelativeImport, wrapWithNamespace };

package/dist/utils/index.js

@@ -176,15 +176,45 @@ function toGlobPattern(baseDir, projectRoot) {
   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
+  toRelativeImport,
+  wrapWithNamespace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachhandley/ez-i18n",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "publishConfig": {
     "access": "public"
   },

package/src/types.ts

@@ -58,6 +58,19 @@ export interface EzI18nConfig {
    * 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;
 }
 
 /**
@@ -72,6 +85,10 @@ export interface ResolvedEzI18nConfig {
   cookieName: 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>;
 }
 
 /**

package/src/utils/index.ts

@@ -9,5 +9,8 @@ export {
   isCacheValid,
   toRelativeImport,
   toGlobPattern,
+  getNamespaceFromPath,
+  wrapWithNamespace,
+  generateNamespaceWrapperCode,
   type PathType,
 } from './translations';

package/src/utils/translations.ts

@@ -309,3 +309,70 @@ export function toGlobPattern(baseDir: string, projectRoot: string): string {
   const normalized = relativePath.startsWith('.') ? relativePath : './' + relativePath;
   return `${normalized}/**/*.json`;
 }
+
+/**
+ * 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)
+ */
+export function getNamespaceFromPath(filePath: string, localeDir: string): string {
+  // Get relative path from locale directory
+  const relative = path.relative(localeDir, filePath);
+
+  // Remove .json extension
+  const withoutExt = relative.replace(/\.json$/i, '');
+
+  // Convert path separators to dots
+  const namespace = withoutExt.replace(/[\\/]/g, '.');
+
+  // Remove trailing .index (index.json files represent the folder itself)
+  return namespace.replace(/\.index$/, '');
+}
+
+/**
+ * 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' } } }
+ */
+export function wrapWithNamespace(
+  namespace: string,
+  content: Record<string, unknown>
+): Record<string, unknown> {
+  if (!namespace) return content;
+
+  const parts = namespace.split('.');
+  let result: Record<string, unknown> = content;
+
+  // Build from inside out
+  for (let i = parts.length - 1; i >= 0; i--) {
+    result = { [parts[i]]: result };
+  }
+
+  return result;
+}
+
+/**
+ * Generate code that wraps imported content with namespace at runtime.
+ * Used in virtual module generation.
+ */
+export function generateNamespaceWrapperCode(): string {
+  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;
+}`;
+}

package/src/vite-plugin.ts

@@ -8,6 +8,8 @@ import {
   saveCache,
   isCacheValid,
   detectPathType,
+  getNamespaceFromPath,
+  generateNamespaceWrapperCode,
 } from './utils/translations';
 import * as path from 'node:path';
 
@@ -21,6 +23,8 @@ interface TranslationInfo {
   files: string[];
   /** Glob pattern for dev mode HMR (if applicable) */
   globPattern?: string;
+  /** Base directory for this locale (used for namespace calculation) */
+  localeBaseDir?: string;
 }
 
 /**
@@ -44,23 +48,45 @@ export function vitePlugin(config: EzI18nConfig): Plugin {
     async buildStart() {
       const projectRoot = viteConfig.root;
 
+      // Determine if path-based namespacing should be enabled
+      // Default to true when using folder-based or auto-discovery config
+      const isAutoDiscovery = !config.translations || typeof config.translations === 'string';
+      const pathBasedNamespacing = config.pathBasedNamespacing ?? isAutoDiscovery;
+
+      // Calculate base translation directory
+      const translationsBaseDir = typeof config.translations === 'string'
+        ? path.resolve(projectRoot, config.translations.replace(/\/$/, ''))
+        : path.resolve(projectRoot, './public/i18n');
+
       // Try to use cache in production builds
       let useCache = false;
       if (!isDev) {
         const cache = loadCache(projectRoot);
         if (cache && isCacheValid(cache, projectRoot)) {
+          // Build locale base dirs
+          const localeBaseDirs: Record<string, string> = {};
+          for (const locale of Object.keys(cache.discovered)) {
+            localeBaseDirs[locale] = path.join(translationsBaseDir, locale);
+          }
+
           // Use cached discovery
           resolved = {
             locales: config.locales || Object.keys(cache.discovered),
             defaultLocale: config.defaultLocale,
             cookieName: config.cookieName ?? 'ez-locale',
             translations: cache.discovered,
+            pathBasedNamespacing,
+            localeBaseDirs,
           };
           useCache = true;
 
           // Populate translationInfo from cache
           for (const [locale, files] of Object.entries(cache.discovered)) {
-            translationInfo.set(locale, { locale, files });
+            translationInfo.set(locale, {
+              locale,
+              files,
+              localeBaseDir: localeBaseDirs[locale],
+            });
           }
         }
       }
@@ -78,17 +104,52 @@ export function vitePlugin(config: EzI18nConfig): Plugin {
           ? config.locales
           : locales;
 
+        // Build locale base dirs
+        const localeBaseDirs: Record<string, string> = {};
+        for (const locale of finalLocales) {
+          if (isAutoDiscovery) {
+            // For auto-discovery, locale folder is under the base dir
+            localeBaseDirs[locale] = path.join(translationsBaseDir, locale);
+          } else if (typeof config.translations === 'object' && config.translations[locale]) {
+            // For explicit config, determine base from the config value
+            const localeConfig = config.translations[locale];
+            if (typeof localeConfig === 'string') {
+              const pathType = detectPathType(localeConfig);
+              if (pathType === 'folder' || pathType === 'file') {
+                // Use the folder itself or parent of file
+                const resolved = path.resolve(projectRoot, localeConfig.replace(/\/$/, ''));
+                localeBaseDirs[locale] = pathType === 'folder' ? resolved : path.dirname(resolved);
+              } else {
+                // Glob - use the non-glob prefix
+                const baseDir = localeConfig.split('*')[0].replace(/\/$/, '');
+                localeBaseDirs[locale] = path.resolve(projectRoot, baseDir);
+              }
+            } else {
+              // Array - use common parent directory
+              localeBaseDirs[locale] = translationsBaseDir;
+            }
+          } else {
+            localeBaseDirs[locale] = translationsBaseDir;
+          }
+        }
+
         resolved = {
           locales: finalLocales,
           defaultLocale: config.defaultLocale,
           cookieName: config.cookieName ?? 'ez-locale',
           translations,
+          pathBasedNamespacing,
+          localeBaseDirs,
         };
 
         // Build translation info for each locale
         for (const locale of finalLocales) {
           const files = translations[locale] || [];
-          const info: TranslationInfo = { locale, files };
+          const info: TranslationInfo = {
+            locale,
+            files,
+            localeBaseDir: localeBaseDirs[locale],
+          };
 
           // For dev mode, determine if we can use import.meta.glob
           if (isDev && config.translations) {
@@ -197,8 +258,8 @@ export function t(key, params) {
       // ez-i18n:translations - Translation loaders
       if (id === RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS) {
         return isDev
-          ? generateDevTranslationsModule(translationInfo, viteConfig.root)
-          : generateBuildTranslationsModule(translationInfo, viteConfig.root);
+          ? generateDevTranslationsModule(translationInfo, viteConfig.root, resolved.pathBasedNamespacing)
+          : generateBuildTranslationsModule(translationInfo, viteConfig.root, resolved.pathBasedNamespacing);
       }
 
       return null;
@@ -208,6 +269,9 @@ export function t(key, params) {
     handleHotUpdate({ file, server }) {
       if (!isDev) return;
 
+      // Only process JSON files
+      if (!file.endsWith('.json')) return;
+
       // Check if the changed file is a translation file
       for (const info of translationInfo.values()) {
         if (info.files.includes(file)) {
@@ -276,7 +340,8 @@ export function t(key, params) {
  */
 function generateDevTranslationsModule(
   translationInfo: Map<string, TranslationInfo>,
-  projectRoot: string
+  projectRoot: string,
+  pathBasedNamespacing: boolean
 ): string {
   const imports: string[] = [];
   const loaderEntries: string[] = [];
@@ -284,12 +349,37 @@ function generateDevTranslationsModule(
   // Add deepMerge inline for runtime merging
   imports.push(getDeepMergeCode());
 
+  // Add namespace wrapper if needed
+  if (pathBasedNamespacing) {
+    imports.push(generateNamespaceWrapperCode());
+  }
+
   for (const [locale, info] of translationInfo) {
     if (info.files.length === 0) {
       // No files - return empty object
       loaderEntries.push(`  ${JSON.stringify(locale)}: async () => ({})`);
+    } else if (info.globPattern && pathBasedNamespacing && info.localeBaseDir) {
+      // Use import.meta.glob with namespace wrapping
+      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) {
-      // Use import.meta.glob for HMR support
+      // Use import.meta.glob without namespace wrapping
       const varName = `__${locale}Modules`;
       imports.push(
         `const ${varName} = import.meta.glob(${JSON.stringify(info.globPattern)}, { eager: true, import: 'default' });`
@@ -302,23 +392,45 @@ function generateDevTranslationsModule(
     return __deepMerge({}, ...modules);
   }`);
     } else if (info.files.length === 1) {
-      // Single file - simple dynamic import
+      // Single file
       const relativePath = toRelativeImport(info.files[0], projectRoot);
-      loaderEntries.push(
-        `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
-      );
+      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 {
       // Multiple explicit files - import all and merge
-      const fileImports = info.files
-        .map(f => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`)
-        .join(', ');
+      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 () => {
+        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);
   }`);
+      }
     }
   }
 
@@ -356,39 +468,69 @@ export async function loadTranslations(locale) {
  */
 function generateBuildTranslationsModule(
   translationInfo: Map<string, TranslationInfo>,
-  projectRoot: string
+  projectRoot: string,
+  pathBasedNamespacing: boolean
 ): string {
   const loaderEntries: string[] = [];
   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) {
-      // Single file - simple dynamic import
+      // Single file
       const relativePath = toRelativeImport(info.files[0], projectRoot);
-      loaderEntries.push(
-        `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(relativePath)}).then(m => m.default ?? m)`
-      );
+      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 {
       // Multiple files - import and merge
       needsDeepMerge = true;
-      const fileImports = info.files
-        .map(f => `import(${JSON.stringify(toRelativeImport(f, projectRoot))})`)
-        .join(', ');
 
-      loaderEntries.push(`  ${JSON.stringify(locale)}: async () => {
+      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);
   }`);
+      }
     }
   }
 
-  const deepMergeCode = needsDeepMerge ? getDeepMergeCode() : '';
+  const helperCode = [
+    needsDeepMerge ? getDeepMergeCode() : '',
+    needsNamespaceWrapper ? generateNamespaceWrapperCode() : '',
+  ].filter(Boolean).join('\n');
 
   return `
-${deepMergeCode}
+${helperCode}
 
 export const translationLoaders = {
 ${loaderEntries.join(',\n')}
@@ -437,10 +579,13 @@ function __deepMerge(target, ...sources) {
 // Re-export resolveConfig for backwards compatibility
 export function resolveConfig(config: EzI18nConfig): ResolvedEzI18nConfig {
   // This is now a simplified version - full resolution happens in buildStart
+  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: {},
   };
 }