@nuraly/lumenjs 0.1.0 → 0.1.1

package/dist/build/build.js

@@ -4,6 +4,7 @@ import fs from 'fs';
 import { getSharedViteConfig } from '../dev-server/server.js';
 import { readProjectConfig } from '../dev-server/config.js';
 import { generateIndexHtml } from '../dev-server/index-html.js';
+import { filePathToTagName } from '../shared/utils.js';
 import { scanPages, scanLayouts, scanApiRoutes, getLayoutDirsForPage } from './scan.js';
 export async function buildProject(options) {
     const { projectDir } = options;
@@ -18,7 +19,7 @@ export async function buildProject(options) {
         fs.rmSync(outDir, { recursive: true });
     }
     fs.mkdirSync(outDir, { recursive: true });
-    const { title, integrations } = readProjectConfig(projectDir);
+    const { title, integrations, i18n: i18nConfig } = readProjectConfig(projectDir);
     const shared = getSharedViteConfig(projectDir, { mode: 'production', integrations });
     // Scan pages, layouts, and API routes for the manifest
     const pageEntries = scanPages(pagesDir);
@@ -141,14 +142,30 @@ export async function buildProject(options) {
             fs.unlinkSync(ssrEntryPath);
         }
     }
+    // --- Copy locales ---
+    if (i18nConfig) {
+        const localesDir = path.join(projectDir, 'locales');
+        const outLocalesDir = path.join(outDir, 'locales');
+        if (fs.existsSync(localesDir)) {
+            fs.mkdirSync(outLocalesDir, { recursive: true });
+            for (const file of fs.readdirSync(localesDir)) {
+                if (file.endsWith('.json')) {
+                    fs.copyFileSync(path.join(localesDir, file), path.join(outLocalesDir, file));
+                }
+            }
+            console.log(`[LumenJS] Copied ${i18nConfig.locales.length} locale(s) to output.`);
+        }
+    }
     // --- Write manifest ---
     const manifest = {
         routes: pageEntries.map(e => {
             const routeLayouts = getLayoutDirsForPage(e.filePath, pagesDir, layoutEntries);
+            const relPath = path.relative(pagesDir, e.filePath).replace(/\\/g, '/');
             return {
                 path: e.routePath,
                 module: e.hasLoader ? `pages/${e.name}.js` : '',
                 hasLoader: e.hasLoader,
+                tagName: filePathToTagName(relPath),
                 ...(routeLayouts.length > 0 ? { layouts: routeLayouts } : {}),
             };
         }),
@@ -162,6 +179,7 @@ export async function buildProject(options) {
             module: e.hasLoader ? (e.dir ? `layouts/${e.dir}/_layout.js` : 'layouts/_layout.js') : '',
             hasLoader: e.hasLoader,
         })),
+        ...(i18nConfig ? { i18n: i18nConfig } : {}),
     };
     fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
     console.log('[LumenJS] Build complete.');

package/dist/build/serve-i18n.d.ts

@@ -0,0 +1,6 @@
+import http from 'http';
+/**
+ * Handle `/__nk_i18n/<locale>.json` requests in production.
+ * Reads from the built `locales/` directory.
+ */
+export declare function handleI18nRequest(localesDir: string, locales: string[], pathname: string, req: http.IncomingMessage, res: http.ServerResponse): boolean;

package/dist/build/serve-i18n.js

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import path from 'path';
+import { sendCompressed } from './serve-static.js';
+/**
+ * Handle `/__nk_i18n/<locale>.json` requests in production.
+ * Reads from the built `locales/` directory.
+ */
+export function handleI18nRequest(localesDir, locales, pathname, req, res) {
+    const match = pathname.match(/^\/__nk_i18n\/([a-z]{2}(?:-[a-zA-Z]+)?)\.json$/);
+    if (!match)
+        return false;
+    const locale = match[1];
+    if (!locales.includes(locale)) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unknown locale' }));
+        return true;
+    }
+    const filePath = path.join(localesDir, `${locale}.json`);
+    if (!fs.existsSync(filePath)) {
+        sendCompressed(req, res, 200, 'application/json', '{}');
+        return true;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    sendCompressed(req, res, 200, 'application/json', content);
+    return true;
+}

package/dist/build/serve-loaders.js

@@ -31,7 +31,10 @@ export async function handleLayoutLoaderRequest(manifest, serverDir, queryString
             res.end(JSON.stringify({ __nk_no_loader: true }));
             return;
         }
-        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers });
+        // Parse locale from query for layout loader
+        const locale = query.__locale;
+        delete query.__locale;
+        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers, locale });
         if (isRedirectResponse(result)) {
             res.writeHead(result.status || 302, { Location: result.location });
             res.end();
@@ -91,7 +94,9 @@ export async function handleLoaderRequest(manifest, serverDir, pagesDir, pathnam
             res.end(JSON.stringify({ __nk_no_loader: true }));
             return;
         }
-        const result = await mod.loader({ params: matched.params, query, url: pagePath, headers });
+        const locale = query.__locale;
+        delete query.__locale;
+        const result = await mod.loader({ params: matched.params, query, url: pagePath, headers, locale });
         if (isRedirectResponse(result)) {
             res.writeHead(result.status || 302, { Location: result.location });
             res.end();

package/dist/build/serve-ssr.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { stripOuterLitMarkers, dirToLayoutTagName, findTagName, isRedirectResponse } from '../shared/utils.js';
+import { stripOuterLitMarkers, dirToLayoutTagName, isRedirectResponse } from '../shared/utils.js';
 import { matchRoute } from '../shared/route-matching.js';
 import { sendCompressed } from './serve-static.js';
 export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, queryString, indexHtmlShell, title, ssrRuntime, req, res) {
@@ -23,8 +23,8 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
                         return;
                     }
                 }
-                // Find tag name from module
-                const tagName = findTagName(mod);
+                // Use tag name from route manifest (matches client router)
+                const tagName = matched.route.tagName;
                 // Run layout loaders
                 const layoutDirs = (allMatched || matched).route.layouts || [];
                 const layoutsData = [];

package/dist/build/serve.js

@@ -8,6 +8,8 @@ import { handleApiRoute } from './serve-api.js';
 import { handleLoaderRequest, handleLayoutLoaderRequest } from './serve-loaders.js';
 import { handlePageRoute } from './serve-ssr.js';
 import { renderErrorPage } from './error-page.js';
+import { handleI18nRequest } from './serve-i18n.js';
+import { resolveLocale } from '../dev-server/middleware/locale.js';
 export async function serveProject(options) {
     const { projectDir } = options;
     const port = options.port || 3000;
@@ -21,6 +23,7 @@ export async function serveProject(options) {
     }
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
     const { title } = readProjectConfig(projectDir);
+    const localesDir = path.join(outDir, 'locales');
     // Read the built index.html shell
     const indexHtmlPath = path.join(clientDir, 'index.html');
     if (!fs.existsSync(indexHtmlPath)) {
@@ -54,18 +57,31 @@ export async function serveProject(options) {
                 if (served)
                     return;
             }
-            // 3. Layout loader endpoint
+            // 3. i18n translation endpoint
+            if (pathname.startsWith('/__nk_i18n/') && manifest.i18n) {
+                handleI18nRequest(localesDir, manifest.i18n.locales, pathname, req, res);
+                return;
+            }
+            // 4. Layout loader endpoint
             if (pathname === '/__nk_loader/__layout/' || pathname === '/__nk_loader/__layout') {
                 await handleLayoutLoaderRequest(manifest, serverDir, queryString, req.headers, res);
                 return;
             }
-            // 4. Loader endpoint for client-side navigation
+            // 5. Loader endpoint for client-side navigation
             if (pathname.startsWith('/__nk_loader/')) {
                 await handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
                 return;
             }
-            // 5. Page routes — SSR render
-            await handlePageRoute(manifest, serverDir, pagesDir, pathname, queryString, indexHtmlShell, title, ssrRuntime, req, res);
+            // 6. Resolve locale and strip prefix for page routing
+            let resolvedPathname = pathname;
+            let locale;
+            if (manifest.i18n) {
+                const result = resolveLocale(pathname, manifest.i18n, req.headers);
+                resolvedPathname = result.pathname;
+                locale = result.locale;
+            }
+            // 7. Page routes — SSR render
+            await handlePageRoute(manifest, serverDir, pagesDir, resolvedPathname, queryString, indexHtmlShell, title, ssrRuntime, req, res);
         }
         catch (err) {
             console.error('[LumenJS] Request error:', err);

package/dist/dev-server/config.d.ts

@@ -1,6 +1,12 @@
+export interface I18nConfig {
+    locales: string[];
+    defaultLocale: string;
+    prefixDefault: boolean;
+}
 export interface ProjectConfig {
     title: string;
     integrations: string[];
+    i18n?: I18nConfig;
 }
 /**
  * Reads the project config from lumenjs.config.ts.

package/dist/dev-server/config.js

@@ -26,7 +26,33 @@ export function readProjectConfig(projectDir) {
         }
         catch { /* use defaults */ }
     }
-    return { title, integrations };
+    // Parse i18n config (reuse the same file read)
+    let i18n;
+    if (fs.existsSync(configPath)) {
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf-8');
+            const i18nMatch = configContent.match(/i18n\s*:\s*\{([\s\S]*?)\}/);
+            if (i18nMatch) {
+                const block = i18nMatch[1];
+                const localesMatch = block.match(/locales\s*:\s*\[([^\]]*)\]/);
+                const defaultMatch = block.match(/defaultLocale\s*:\s*['"]([^'"]+)['"]/);
+                const prefixMatch = block.match(/prefixDefault\s*:\s*(true|false)/);
+                if (localesMatch && defaultMatch) {
+                    const locales = localesMatch[1]
+                        .split(',')
+                        .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
+                        .filter(Boolean);
+                    i18n = {
+                        locales,
+                        defaultLocale: defaultMatch[1],
+                        prefixDefault: prefixMatch ? prefixMatch[1] === 'true' : false,
+                    };
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return { title, integrations, ...(i18n ? { i18n } : {}) };
 }
 /**
  * Reads the project title from lumenjs.config.ts (or returns default).

package/dist/dev-server/index-html.d.ts

@@ -8,6 +8,13 @@ export interface IndexHtmlOptions {
         data: any;
     }>;
     integrations?: string[];
+    locale?: string;
+    i18nConfig?: {
+        locales: string[];
+        defaultLocale: string;
+        prefixDefault: boolean;
+    };
+    translations?: Record<string, string>;
 }
 /**
  * Generates the index.html shell that loads the LumenJS app.

package/dist/dev-server/index-html.js

@@ -19,16 +19,28 @@ export function generateIndexHtml(options) {
             : options.loaderData;
         loaderDataScript = `<script type="application/json" id="__nk_ssr_data__">${JSON.stringify(ssrData).replace(/</g, '\\u003c')}</script>`;
     }
+    // i18n: inline translations and config for client hydration
+    let i18nScript = '';
+    if (options.i18nConfig && options.locale && options.translations) {
+        const i18nData = {
+            config: options.i18nConfig,
+            locale: options.locale,
+            translations: options.translations,
+        };
+        i18nScript = `<script type="application/json" id="__nk_i18n__">${JSON.stringify(i18nData).replace(/</g, '\\u003c')}</script>`;
+    }
+    // i18n module is loaded via imports from router-hydration, no separate script needed
     const hydrateScript = isSSR
         ? `<script type="module">import '@lit-labs/ssr-client/lit-element-hydrate-support.js';</script>`
         : '';
+    const htmlLang = options.locale || 'en';
     return `<!DOCTYPE html>
-<html lang="en">
+<html lang="${htmlLang}">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>${escapeHtml(options.title)}</title>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nuralyui/themes@latest/dist/default.css">${options.integrations?.includes('tailwind') ? '\n  <link rel="stylesheet" href="/styles/tailwind.css">' : ''}
+  ${options.integrations?.includes('nuralyui') ? '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nuralyui/themes@latest/dist/default.css">' : ''}${options.integrations?.includes('tailwind') ? '\n  <script type="module">import "/styles/tailwind.css";</script>' : ''}
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     body { font-family: system-ui, -apple-system, sans-serif; min-height: 100vh; }
@@ -36,6 +48,7 @@ export function generateIndexHtml(options) {
   </style>
 </head>
 <body>
+  ${i18nScript}
   ${loaderDataScript}
   ${appTag}
   ${hydrateScript}

package/dist/dev-server/middleware/locale.d.ts

@@ -0,0 +1,20 @@
+export interface I18nConfig {
+    locales: string[];
+    defaultLocale: string;
+    prefixDefault: boolean;
+}
+export interface LocaleResult {
+    locale: string;
+    pathname: string;
+}
+/**
+ * Extract the locale from the request URL, cookie, or Accept-Language header.
+ * Returns the resolved locale and the pathname with the locale prefix stripped.
+ *
+ * Resolution order:
+ *   1. URL prefix: /fr/about → locale "fr", pathname "/about"
+ *   2. Cookie "nk-locale"
+ *   3. Accept-Language header
+ *   4. Config defaultLocale
+ */
+export declare function resolveLocale(pathname: string, config: I18nConfig, headers?: Record<string, string | string[] | undefined>): LocaleResult;

package/dist/dev-server/middleware/locale.js

@@ -0,0 +1,55 @@
+/**
+ * Extract the locale from the request URL, cookie, or Accept-Language header.
+ * Returns the resolved locale and the pathname with the locale prefix stripped.
+ *
+ * Resolution order:
+ *   1. URL prefix: /fr/about → locale "fr", pathname "/about"
+ *   2. Cookie "nk-locale"
+ *   3. Accept-Language header
+ *   4. Config defaultLocale
+ */
+export function resolveLocale(pathname, config, headers) {
+    // 1. URL prefix
+    for (const loc of config.locales) {
+        if (pathname === `/${loc}` || pathname.startsWith(`/${loc}/`)) {
+            return { locale: loc, pathname: pathname.slice(loc.length + 1) || '/' };
+        }
+    }
+    // 2. Cookie
+    const cookieHeader = headers?.cookie;
+    if (typeof cookieHeader === 'string') {
+        const match = cookieHeader.match(/(?:^|;\s*)nk-locale=([^;]+)/);
+        if (match && config.locales.includes(match[1])) {
+            return { locale: match[1], pathname };
+        }
+    }
+    // 3. Accept-Language
+    const acceptLang = headers?.['accept-language'];
+    if (typeof acceptLang === 'string') {
+        const preferred = parseAcceptLanguage(acceptLang);
+        for (const lang of preferred) {
+            const short = lang.split('-')[0];
+            if (config.locales.includes(short)) {
+                return { locale: short, pathname };
+            }
+            if (config.locales.includes(lang)) {
+                return { locale: lang, pathname };
+            }
+        }
+    }
+    // 4. Default
+    return { locale: config.defaultLocale, pathname };
+}
+/**
+ * Parse the Accept-Language header into a sorted list of language codes.
+ */
+function parseAcceptLanguage(header) {
+    return header
+        .split(',')
+        .map(part => {
+        const [lang, q] = part.trim().split(';q=');
+        return { lang: lang.trim().toLowerCase(), q: q ? parseFloat(q) : 1 };
+    })
+        .sort((a, b) => b.q - a.q)
+        .map(e => e.lang);
+}

package/dist/dev-server/plugins/vite-plugin-i18n.d.ts

@@ -0,0 +1,15 @@
+import { Plugin } from 'vite';
+import type { I18nConfig } from '../middleware/locale.js';
+/**
+ * Vite plugin for LumenJS i18n support.
+ *
+ * - Serves `/__nk_i18n/<locale>.json` with translation files
+ * - Provides a virtual module `@lumenjs/i18n` that re-exports the runtime
+ * - Watches locale files for HMR
+ */
+export declare function i18nPlugin(projectDir: string, config: I18nConfig): Plugin;
+/**
+ * Load translations for a locale from the project's locales/ directory.
+ * Used during SSR to inline translations in the HTML.
+ */
+export declare function loadTranslationsFromDisk(projectDir: string, locale: string): Record<string, string>;

package/dist/dev-server/plugins/vite-plugin-i18n.js

@@ -0,0 +1,71 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Vite plugin for LumenJS i18n support.
+ *
+ * - Serves `/__nk_i18n/<locale>.json` with translation files
+ * - Provides a virtual module `@lumenjs/i18n` that re-exports the runtime
+ * - Watches locale files for HMR
+ */
+export function i18nPlugin(projectDir, config) {
+    const localesDir = path.join(projectDir, 'locales');
+    return {
+        name: 'lumenjs-i18n',
+        configureServer(server) {
+            // Serve translation JSON files
+            server.middlewares.use((req, res, next) => {
+                if (!req.url?.startsWith('/__nk_i18n/'))
+                    return next();
+                const match = req.url.match(/^\/__nk_i18n\/([a-z]{2}(?:-[a-zA-Z]+)?)\.json$/);
+                if (!match)
+                    return next();
+                const locale = match[1];
+                if (!config.locales.includes(locale)) {
+                    res.statusCode = 404;
+                    res.end(JSON.stringify({ error: 'Unknown locale' }));
+                    return;
+                }
+                const filePath = path.join(localesDir, `${locale}.json`);
+                if (!fs.existsSync(filePath)) {
+                    res.statusCode = 200;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end('{}');
+                    return;
+                }
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    // Validate JSON
+                    JSON.parse(content);
+                    res.statusCode = 200;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.setHeader('Cache-Control', 'no-store');
+                    res.end(content);
+                }
+                catch {
+                    res.statusCode = 500;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: 'Invalid locale file' }));
+                }
+            });
+            // Watch locale directory for changes and trigger HMR
+            if (fs.existsSync(localesDir)) {
+                server.watcher.add(localesDir);
+            }
+        },
+    };
+}
+/**
+ * Load translations for a locale from the project's locales/ directory.
+ * Used during SSR to inline translations in the HTML.
+ */
+export function loadTranslationsFromDisk(projectDir, locale) {
+    const filePath = path.join(projectDir, 'locales', `${locale}.json`);
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/dev-server/plugins/vite-plugin-loaders.js

@@ -83,7 +83,10 @@ export function lumenLoadersPlugin(pagesDir) {
                         res.end(JSON.stringify({ __nk_no_loader: true }));
                         return;
                     }
-                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers });
+                    // Extract locale from query if provided by the client router
+                    const locale = query.__locale;
+                    delete query.__locale;
+                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers, locale });
                     if (isRedirectResponse(result)) {
                         res.statusCode = result.status || 302;
                         res.setHeader('Location', result.location);
@@ -195,7 +198,18 @@ async function handleLayoutLoader(server, pagesDir, dir, req, res) {
             res.end(JSON.stringify({ __nk_no_loader: true }));
             return;
         }
-        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers: req.headers });
+        // Parse locale from query for layout loader requests
+        const query = {};
+        const reqUrl = req.url || '';
+        const qs = reqUrl.split('?')[1];
+        if (qs) {
+            for (const pair of qs.split('&')) {
+                const [key, val] = pair.split('=');
+                query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+            }
+        }
+        const locale = query.__locale;
+        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers: req.headers, locale });
         if (isRedirectResponse(result)) {
             res.statusCode = result.status || 302;
             res.setHeader('Location', result.location);

package/dist/dev-server/plugins/vite-plugin-routes.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { dirToLayoutTagName, fileHasLoader, filePathToRoute } from '../../shared/utils.js';
+import { dirToLayoutTagName, fileHasLoader, filePathToRoute, filePathToTagName } from '../../shared/utils.js';
 const VIRTUAL_MODULE_ID = 'virtual:lumenjs-routes';
 const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
 /**
@@ -68,16 +68,6 @@ export function lumenRoutesPlugin(pagesDir) {
             }
         }
     }
-    function filePathToTagName(filePath) {
-        const name = filePath
-            .replace(/\.(ts|js)$/, '')
-            .replace(/\\/g, '-')
-            .replace(/\//g, '-')
-            .replace(/\[\.\.\.([^\]]+)\]/g, '$1')
-            .replace(/\[([^\]]+)\]/g, '$1')
-            .toLowerCase();
-        return `page-${name}`;
-    }
     /** Build the layout chain for a route based on its file path within pages/ */
     function getLayoutChain(componentPath, layouts) {
         const relativeToPages = path.relative(pagesDir, componentPath).replace(/\\/g, '/');

package/dist/dev-server/plugins/vite-plugin-source-annotator.js

@@ -29,7 +29,14 @@ export function sourceAnnotatorPlugin(projectDir) {
                     const escaped = content.trim().replace(/"/g, '"').replace(/\$\{/g, '__NK_EXPR__');
                     return `<${tag}${attrStr} data-nk-dynamic="${escaped}">${content}</`;
                 });
-                return 'html`' + dynamicAnnotated + '`';
+                // Detect t('key') calls inside template expressions and add data-nk-i18n-key
+                const i18nAnnotated = dynamicAnnotated.replace(/<(h[1-6]|p|span|a|label|li|button|div)(\s[^>]*)?>([^<]*\$\{t\(['"]([^'"]+)['"]\)\}[^<]*)<\//gi, (m, tag, attrs, content, key) => {
+                    const attrStr = attrs || '';
+                    if (attrStr.includes('data-nk-i18n-key'))
+                        return m;
+                    return `<${tag}${attrStr} data-nk-i18n-key="${key}">${content}</`;
+                });
+                return 'html`' + i18nAnnotated + '`';
             });
             if (transformed !== code) {
                 return { code: transformed, map: null };

package/dist/dev-server/plugins/vite-plugin-virtual-modules.d.ts

@@ -1,5 +1,10 @@
 import { Plugin } from 'vite';
 /**
  * Virtual module plugin — serves compiled LumenJS runtime and editor modules.
+ * Rewrites relative imports between split sub-modules to virtual module paths.
+ *
+ * i18n is resolved via resolve.alias (physical file) rather than as a virtual
+ * module, because Vite's import-analysis rejects bare @-prefixed specifiers
+ * that go through the virtual module path.
  */
 export declare function virtualModulesPlugin(runtimeDir: string, editorDir: string): Plugin;

package/dist/dev-server/plugins/vite-plugin-virtual-modules.js

@@ -2,36 +2,66 @@ import fs from 'fs';
 import path from 'path';
 /**
  * Virtual module plugin — serves compiled LumenJS runtime and editor modules.
+ * Rewrites relative imports between split sub-modules to virtual module paths.
+ *
+ * i18n is resolved via resolve.alias (physical file) rather than as a virtual
+ * module, because Vite's import-analysis rejects bare @-prefixed specifiers
+ * that go through the virtual module path.
  */
 export function virtualModulesPlugin(runtimeDir, editorDir) {
+    const runtimeModules = {
+        'app-shell': 'app-shell.js',
+        'router': 'router.js',
+        'router-data': 'router-data.js',
+        'router-hydration': 'router-hydration.js',
+        'i18n': 'i18n.js',
+    };
+    // Modules resolved via resolve.alias instead of virtual module.
+    // They still appear in the map so relative import rewrites work.
+    const aliasedModules = new Set(['i18n']);
+    const editorModules = {
+        'editor-bridge': 'editor-bridge.js',
+        'element-annotator': 'element-annotator.js',
+        'click-select': 'click-select.js',
+        'hover-detect': 'hover-detect.js',
+        'inline-text-edit': 'inline-text-edit.js',
+    };
+    function rewriteRelativeImports(code, modules) {
+        for (const name of Object.keys(modules)) {
+            const file = modules[name];
+            // Aliased modules use @lumenjs/name (resolved by Vite alias).
+            // Virtual modules use /@lumenjs/name (resolved by this plugin).
+            const prefix = aliasedModules.has(name) ? '@lumenjs' : '/@lumenjs';
+            code = code.replace(new RegExp(`from\\s+['"]\\.\\/${file.replace('.', '\\.')}['"]`, 'g'), `from '${prefix}/${name}'`);
+        }
+        return code;
+    }
     return {
         name: 'lumenjs-virtual-modules',
+        enforce: 'pre',
         resolveId(id) {
-            if (id === '/@lumenjs/app-shell')
-                return '\0lumenjs:app-shell';
-            if (id === '/@lumenjs/router')
-                return '\0lumenjs:router';
-            if (id === '/@lumenjs/editor-bridge')
-                return '\0lumenjs:editor-bridge';
-            if (id === '/@lumenjs/element-annotator')
-                return '\0lumenjs:element-annotator';
+            const match = id.match(/^\/@lumenjs\/(.+)$/);
+            if (!match)
+                return;
+            const name = match[1];
+            // Skip aliased modules — they're resolved via resolve.alias
+            if (aliasedModules.has(name))
+                return;
+            if (runtimeModules[name] || editorModules[name]) {
+                return `\0lumenjs:${name}`;
+            }
         },
         load(id) {
-            if (id === '\0lumenjs:app-shell') {
-                let code = fs.readFileSync(path.join(runtimeDir, 'app-shell.js'), 'utf-8');
-                code = code.replace(/from\s+['"]\.\/router\.js['"]/g, "from '/@lumenjs/router'");
-                return code;
-            }
-            if (id === '\0lumenjs:router') {
-                return fs.readFileSync(path.join(runtimeDir, 'router.js'), 'utf-8');
-            }
-            if (id === '\0lumenjs:editor-bridge') {
-                let code = fs.readFileSync(path.join(editorDir, 'editor-bridge.js'), 'utf-8');
-                code = code.replace(/from\s+['"]\.\/element-annotator\.js['"]/g, "from '/@lumenjs/element-annotator'");
-                return code;
+            if (!id.startsWith('\0lumenjs:'))
+                return;
+            const name = id.slice('\0lumenjs:'.length);
+            if (runtimeModules[name]) {
+                const code = fs.readFileSync(path.join(runtimeDir, runtimeModules[name]), 'utf-8');
+                return rewriteRelativeImports(code, runtimeModules);
             }
-            if (id === '\0lumenjs:element-annotator') {
-                return fs.readFileSync(path.join(editorDir, 'element-annotator.js'), 'utf-8');
+            if (editorModules[name]) {
+                const code = fs.readFileSync(path.join(editorDir, editorModules[name]), 'utf-8');
+                return rewriteRelativeImports(code, editorModules);
             }
         }
     };

package/dist/dev-server/server.d.ts

@@ -1,6 +1,6 @@
 import { ViteDevServer, UserConfig, Plugin } from 'vite';
 export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
-export type { ProjectConfig } from './config.js';
+export type { ProjectConfig, I18nConfig } from './config.js';
 export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
 export interface DevServerOptions {
     projectDir: string;

package/dist/dev-server/server.js

@@ -15,6 +15,8 @@ import { autoImportPlugin } from './plugins/vite-plugin-auto-import.js';
 import { litHmrPlugin } from './plugins/vite-plugin-lit-hmr.js';
 import { sourceAnnotatorPlugin } from './plugins/vite-plugin-source-annotator.js';
 import { virtualModulesPlugin } from './plugins/vite-plugin-virtual-modules.js';
+import { i18nPlugin, loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
+import { resolveLocale } from './middleware/locale.js';
 // Re-export for backwards compatibility
 export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
 export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
@@ -28,14 +30,21 @@ export function getSharedViteConfig(projectDir, options) {
     const pagesDir = path.join(projectDir, 'pages');
     const lumenNodeModules = getLumenJSNodeModules();
     const { runtimeDir, editorDir } = getLumenJSDirs();
-    // Resolve NuralyUI paths for aliases
-    const nuralyUIPaths = resolveNuralyUIPaths(projectDir);
+    // Resolve NuralyUI paths for aliases (only when nuralyui integration is enabled)
     const aliases = {};
-    if (nuralyUIPaths) {
-        Object.assign(aliases, getNuralyUIAliases(nuralyUIPaths.componentsPath, nuralyUIPaths.commonPath));
+    if (options?.integrations?.includes('nuralyui')) {
+        const nuralyUIPaths = resolveNuralyUIPaths(projectDir);
+        if (nuralyUIPaths) {
+            Object.assign(aliases, getNuralyUIAliases(nuralyUIPaths.componentsPath, nuralyUIPaths.commonPath));
+        }
     }
     const resolve = {
-        alias: { ...aliases },
+        alias: {
+            ...aliases,
+            // Map @lumenjs/i18n to the physical dist file so Vite resolves it
+            // without going through node_modules (it's not an npm package).
+            '@lumenjs/i18n': path.join(runtimeDir, 'i18n.js'),
+        },
         conditions: isDev ? ['development', 'browser'] : ['browser'],
         dedupe: ['lit', 'lit-html', 'lit-element', '@lit/reactive-element'],
     };
@@ -51,9 +60,12 @@ export function getSharedViteConfig(projectDir, options) {
         lumenRoutesPlugin(pagesDir),
         lumenLoadersPlugin(pagesDir),
         litDedupPlugin(lumenNodeModules, isDev),
-        autoImportPlugin(projectDir),
         virtualModulesPlugin(runtimeDir, editorDir),
     ];
+    // Conditionally add NuralyUI auto-import plugin
+    if (options?.integrations?.includes('nuralyui')) {
+        plugins.push(autoImportPlugin(projectDir));
+    }
     // Conditionally add Tailwind plugin from the project's node_modules
     if (options?.integrations?.includes('tailwind')) {
         try {
@@ -74,7 +86,7 @@ export async function createDevServer(options) {
     const apiDir = path.join(projectDir, 'api');
     const publicDir = path.join(projectDir, 'public');
     const config = readProjectConfig(projectDir);
-    const { title, integrations } = config;
+    const { title, integrations, i18n: i18nConfig } = config;
     const shared = getSharedViteConfig(projectDir, { integrations });
     const server = await createViteServer({
         root: projectDir,
@@ -92,6 +104,7 @@ export async function createDevServer(options) {
             ...shared.plugins,
             lumenApiRoutesPlugin(apiDir, projectDir),
             litHmrPlugin(projectDir),
+            ...(i18nConfig ? [i18nPlugin(projectDir, i18nConfig)] : []),
             ...(editorMode ? [sourceAnnotatorPlugin(projectDir)] : []),
             {
                 name: 'lumenjs-index-html',
@@ -99,10 +112,20 @@ export async function createDevServer(options) {
                     server.middlewares.use((req, res, next) => {
                         if (req.url && !req.url.startsWith('/@') && !req.url.startsWith('/node_modules') &&
                             !req.url.startsWith('/api/') && !req.url.startsWith('/__nk_loader/') &&
+                            !req.url.startsWith('/__nk_i18n/') &&
                             !req.url.includes('.') && req.method === 'GET') {
-                            const pathname = req.url.split('?')[0];
+                            let pathname = req.url.split('?')[0];
+                            // Resolve locale from URL/cookie/header
+                            let locale;
+                            let translations;
+                            if (i18nConfig) {
+                                const localeResult = resolveLocale(pathname, i18nConfig, req.headers);
+                                locale = localeResult.locale;
+                                pathname = localeResult.pathname;
+                                translations = loadTranslationsFromDisk(projectDir, locale);
+                            }
                             const SSR_PLACEHOLDER = '<!--__NK_SSR_CONTENT__-->';
-                            ssrRenderPage(server, pagesDir, pathname, req.headers).then(async (ssrResult) => {
+                            ssrRenderPage(server, pagesDir, pathname, req.headers, locale).then(async (ssrResult) => {
                                 if (ssrResult?.redirect) {
                                     res.writeHead(ssrResult.redirect.status, { Location: ssrResult.redirect.location });
                                     res.end();
@@ -115,6 +138,9 @@ export async function createDevServer(options) {
                                     loaderData: ssrResult?.loaderData,
                                     layoutsData: ssrResult?.layoutsData,
                                     integrations,
+                                    locale,
+                                    i18nConfig: i18nConfig || undefined,
+                                    translations,
                                 });
                                 const transformed = await server.transformIndexHtml(req.url, shellHtml);
                                 const finalHtml = ssrResult
@@ -125,7 +151,7 @@ export async function createDevServer(options) {
                                 res.end(finalHtml);
                             }).catch(err => {
                                 console.error('[LumenJS] SSR/HTML generation error:', err);
-                                const html = generateIndexHtml({ title, editorMode, integrations });
+                                const html = generateIndexHtml({ title, editorMode, integrations, locale, i18nConfig: i18nConfig || undefined, translations });
                                 server.transformIndexHtml(req.url, html).then(transformed => {
                                     res.setHeader('Content-Type', 'text/html');
                                     res.setHeader('Cache-Control', 'no-store');
@@ -142,6 +168,7 @@ export async function createDevServer(options) {
         esbuild: shared.esbuild,
         optimizeDeps: {
             include: ['lit', 'lit/decorators.js', 'lit/directive.js', 'lit/directive-helpers.js', 'lit/async-directive.js', 'lit-html', 'lit-element', '@lit/reactive-element'],
+            exclude: ['@lumenjs/i18n'],
         },
         ssr: {
             noExternal: true,

package/dist/dev-server/ssr-render.d.ts

@@ -9,7 +9,7 @@ export interface LayoutSSRData {
  *
  * Returns pre-rendered HTML and loader data, or null on failure (falls back to CSR).
  */
-export declare function ssrRenderPage(server: ViteDevServer, pagesDir: string, pathname: string, headers?: Record<string, string | string[] | undefined>): Promise<{
+export declare function ssrRenderPage(server: ViteDevServer, pagesDir: string, pathname: string, headers?: Record<string, string | string[] | undefined>, locale?: string): Promise<{
     html: string;
     loaderData: any;
     layoutsData?: LayoutSSRData[];

package/dist/dev-server/ssr-render.js

@@ -1,15 +1,16 @@
 import path from 'path';
 import fs from 'fs';
 import { resolvePageFile, extractRouteParams } from './plugins/vite-plugin-loaders.js';
-import { stripOuterLitMarkers, dirToLayoutTagName, findTagName } from '../shared/utils.js';
+import { stripOuterLitMarkers, dirToLayoutTagName, filePathToTagName } from '../shared/utils.js';
 import { installDomShims } from '../shared/dom-shims.js';
+import { loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
 /**
  * Server-side render a LumenJS page using @lit-labs/ssr.
  * Wraps the page in its layout chain if layouts exist.
  *
  * Returns pre-rendered HTML and loader data, or null on failure (falls back to CSR).
  */
-export async function ssrRenderPage(server, pagesDir, pathname, headers) {
+export async function ssrRenderPage(server, pagesDir, pathname, headers, locale) {
     try {
         const filePath = resolvePageFile(pagesDir, pathname);
         if (!filePath)
@@ -19,6 +20,21 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers) {
         await server.ssrLoadModule('@lit-labs/ssr/lib/install-global-dom-shim.js');
         // Patch missing DOM APIs that NuralyUI components may use during SSR
         installDomShims();
+        // Initialize i18n in the SSR context so t() works during render
+        if (locale) {
+            const projectDir = path.resolve(pagesDir, '..');
+            const translations = loadTranslationsFromDisk(projectDir, locale);
+            try {
+                // Load the same i18n module the page will import (via resolve.alias)
+                const i18nMod = await server.ssrLoadModule('@lumenjs/i18n');
+                if (i18nMod?.initI18n) {
+                    i18nMod.initI18n({ locales: [], defaultLocale: locale, prefixDefault: false }, locale, translations);
+                }
+            }
+            catch {
+                // i18n module not available — translations will show keys
+            }
+        }
         // Invalidate SSR module cache so we always get fresh content after file edits.
         // Also clear the custom element from the SSR registry so the new class is used.
         const g = globalThis;
@@ -29,15 +45,14 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers) {
         // Run loader if present
         let loaderData = undefined;
         if (mod.loader && typeof mod.loader === 'function') {
-            loaderData = await mod.loader({ params, query: {}, url: pathname, headers: headers || {} });
+            loaderData = await mod.loader({ params, query: {}, url: pathname, headers: headers || {}, locale });
             if (loaderData && typeof loaderData === 'object' && loaderData.__nk_redirect) {
                 return { html: '', loaderData: null, redirect: { location: loaderData.location, status: loaderData.status || 302 } };
             }
         }
-        // Determine the custom element tag name
-        const tagName = findTagName(mod);
-        if (!tagName)
-            return null;
+        // Determine the custom element tag name from file path (matches client router)
+        const relPath = path.relative(pagesDir, filePath).replace(/\\/g, '/');
+        const tagName = filePathToTagName(relPath);
         // Discover layout chain for this page
         const layoutChain = discoverLayoutChain(pagesDir, filePath);
         const layoutsData = [];
@@ -50,7 +65,7 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers) {
             const layoutMod = await server.ssrLoadModule(layout.filePath);
             let layoutLoaderData = undefined;
             if (layoutMod.loader && typeof layoutMod.loader === 'function') {
-                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: headers || {} });
+                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: headers || {}, locale });
                 if (layoutLoaderData && typeof layoutLoaderData === 'object' && layoutLoaderData.__nk_redirect) {
                     return { html: '', loaderData: null, redirect: { location: layoutLoaderData.location, status: layoutLoaderData.status || 302 } };
                 }

package/dist/editor/editor-bridge.d.ts

@@ -1,5 +1,5 @@
 export interface NkEditorMessage {
-    type: 'NK_READY' | 'NK_ELEMENT_CLICKED' | 'NK_ELEMENT_HOVERED' | 'NK_SELECT_ELEMENT' | 'NK_HIGHLIGHT_ELEMENT' | 'NK_TEXT_CHANGED' | 'NK_SET_PREVIEW_MODE';
+    type: 'NK_READY' | 'NK_ELEMENT_CLICKED' | 'NK_ELEMENT_HOVERED' | 'NK_SELECT_ELEMENT' | 'NK_HIGHLIGHT_ELEMENT' | 'NK_TEXT_CHANGED' | 'NK_TRANSLATION_CHANGED' | 'NK_SET_PREVIEW_MODE';
     payload?: any;
 }
 export declare function isPreviewMode(): boolean;

package/dist/editor/inline-text-edit.js

@@ -93,10 +93,21 @@ export function setupInlineTextEdit() {
             editingEl.style.minWidth = '';
             editingEl = null;
             if (newText !== originalText) {
-                sendToHost({
-                    type: 'NK_TEXT_CHANGED',
-                    payload: { sourceFile, line, originalText, newText }
-                });
+                // Check if this element has an i18n key — if so, send a translation change
+                const i18nKey = textEl.getAttribute('data-nk-i18n-key');
+                if (i18nKey) {
+                    const locale = document.documentElement.lang || 'en';
+                    sendToHost({
+                        type: 'NK_TRANSLATION_CHANGED',
+                        payload: { key: i18nKey, locale, originalText, newText }
+                    });
+                }
+                else {
+                    sendToHost({
+                        type: 'NK_TEXT_CHANGED',
+                        payload: { sourceFile, line, originalText, newText }
+                    });
+                }
             }
         };
         textEl.addEventListener('blur', commitEdit, { once: true });

package/dist/runtime/i18n.d.ts

@@ -0,0 +1,56 @@
+/**
+ * LumenJS i18n runtime — provides translation lookup, locale management,
+ * and translation loading for both SSR and client-side navigation.
+ */
+/**
+ * Look up a translation key. Returns the translated string, or the key itself
+ * if no translation is found.
+ */
+export declare function t(key: string): string;
+/** Returns the current locale. */
+export declare function getLocale(): string;
+/** Returns the i18n config, or null if i18n is not enabled. */
+export declare function getI18nConfig(): {
+    locales: string[];
+    defaultLocale: string;
+    prefixDefault: boolean;
+} | null;
+/**
+ * Switch to a new locale. Navigates to the same pathname under the new
+ * locale prefix and sets the `nk-locale` cookie.
+ */
+export declare function setLocale(locale: string): void;
+/**
+ * Initialise the i18n runtime with config and translations.
+ * Called during hydration (from SSR data) or on first load.
+ */
+export declare function initI18n(config: {
+    locales: string[];
+    defaultLocale: string;
+    prefixDefault: boolean;
+}, locale: string, trans: Record<string, string>): void;
+/**
+ * Load translations for a locale from the server and swap them in.
+ * Used during client-side locale switches.
+ */
+export declare function loadTranslations(locale: string): Promise<void>;
+/**
+ * Strip the locale prefix from a pathname.
+ *   /fr/about → /about
+ *   /about    → /about
+ */
+export declare function stripLocalePrefix(pathname: string): string;
+/**
+ * Prepend the locale prefix to a pathname.
+ *   (fr, /about) → /fr/about
+ *   (en, /about) → /about        (when prefixDefault=false)
+ */
+export declare function buildLocalePath(locale: string, pathname: string): string;
+/**
+ * Detect the locale from a URL pathname.
+ * Returns the locale and the pathname with the prefix stripped.
+ */
+export declare function detectLocaleFromPath(pathname: string): {
+    locale: string;
+    pathname: string;
+};

package/dist/runtime/i18n.js

@@ -0,0 +1,100 @@
+/**
+ * LumenJS i18n runtime — provides translation lookup, locale management,
+ * and translation loading for both SSR and client-side navigation.
+ */
+let currentLocale = 'en';
+let translations = {};
+let i18nConfig = null;
+/**
+ * Look up a translation key. Returns the translated string, or the key itself
+ * if no translation is found.
+ */
+export function t(key) {
+    return translations[key] ?? key;
+}
+/** Returns the current locale. */
+export function getLocale() {
+    return currentLocale;
+}
+/** Returns the i18n config, or null if i18n is not enabled. */
+export function getI18nConfig() {
+    return i18nConfig;
+}
+/**
+ * Switch to a new locale. Navigates to the same pathname under the new
+ * locale prefix and sets the `nk-locale` cookie.
+ */
+export function setLocale(locale) {
+    if (!i18nConfig || !i18nConfig.locales.includes(locale))
+        return;
+    document.cookie = `nk-locale=${locale};path=/;max-age=${60 * 60 * 24 * 365};SameSite=Lax`;
+    const pathname = stripLocalePrefix(location.pathname);
+    const newPath = buildLocalePath(locale, pathname);
+    location.href = newPath;
+}
+/**
+ * Initialise the i18n runtime with config and translations.
+ * Called during hydration (from SSR data) or on first load.
+ */
+export function initI18n(config, locale, trans) {
+    i18nConfig = config;
+    currentLocale = locale;
+    translations = trans;
+}
+/**
+ * Load translations for a locale from the server and swap them in.
+ * Used during client-side locale switches.
+ */
+export async function loadTranslations(locale) {
+    const res = await fetch(`/__nk_i18n/${locale}.json`);
+    if (!res.ok) {
+        console.error(`[i18n] Failed to load translations for locale "${locale}"`);
+        return;
+    }
+    translations = await res.json();
+    currentLocale = locale;
+}
+/**
+ * Strip the locale prefix from a pathname.
+ *   /fr/about → /about
+ *   /about    → /about
+ */
+export function stripLocalePrefix(pathname) {
+    if (!i18nConfig)
+        return pathname;
+    for (const loc of i18nConfig.locales) {
+        if (loc === i18nConfig.defaultLocale && !i18nConfig.prefixDefault)
+            continue;
+        if (pathname === `/${loc}` || pathname.startsWith(`/${loc}/`)) {
+            return pathname.slice(loc.length + 1) || '/';
+        }
+    }
+    return pathname;
+}
+/**
+ * Prepend the locale prefix to a pathname.
+ *   (fr, /about) → /fr/about
+ *   (en, /about) → /about        (when prefixDefault=false)
+ */
+export function buildLocalePath(locale, pathname) {
+    if (!i18nConfig)
+        return pathname;
+    if (locale === i18nConfig.defaultLocale && !i18nConfig.prefixDefault) {
+        return pathname;
+    }
+    return `/${locale}${pathname === '/' ? '' : pathname}` || `/${locale}`;
+}
+/**
+ * Detect the locale from a URL pathname.
+ * Returns the locale and the pathname with the prefix stripped.
+ */
+export function detectLocaleFromPath(pathname) {
+    if (!i18nConfig)
+        return { locale: 'en', pathname };
+    for (const loc of i18nConfig.locales) {
+        if (pathname === `/${loc}` || pathname.startsWith(`/${loc}/`)) {
+            return { locale: loc, pathname: pathname.slice(loc.length + 1) || '/' };
+        }
+    }
+    return { locale: i18nConfig.defaultLocale, pathname };
+}

package/dist/runtime/router-data.js

@@ -1,8 +1,13 @@
+import { getI18nConfig, getLocale } from './i18n.js';
 export async function fetchLoaderData(pathname, params) {
     const url = new URL(`/__nk_loader${pathname}`, location.origin);
     if (Object.keys(params).length > 0) {
         url.searchParams.set('__params', JSON.stringify(params));
     }
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
     const res = await fetch(url.toString());
     if (!res.ok) {
         throw new Error(`Loader returned ${res.status}`);
@@ -15,6 +20,10 @@ export async function fetchLoaderData(pathname, params) {
 export async function fetchLayoutLoaderData(dir) {
     const url = new URL(`/__nk_loader/__layout/`, location.origin);
     url.searchParams.set('__dir', dir);
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
     const res = await fetch(url.toString());
     if (!res.ok) {
         throw new Error(`Layout loader returned ${res.status}`);

package/dist/runtime/router-hydration.js

@@ -1,10 +1,24 @@
+import { initI18n, stripLocalePrefix, getI18nConfig } from './i18n.js';
 /**
  * Hydrate the initial SSR-rendered route.
  * Sets loaderData on existing DOM elements BEFORE loading modules to avoid
  * hydration mismatches with Lit's microtask-based hydration.
  */
 export async function hydrateInitialRoute(routes, outlet, matchRoute, onHydrated) {
-    const match = matchRoute(location.pathname);
+    // Read i18n data and init before anything else
+    const i18nScript = document.getElementById('__nk_i18n__');
+    if (i18nScript) {
+        try {
+            const i18nData = JSON.parse(i18nScript.textContent || '');
+            initI18n(i18nData.config, i18nData.locale, i18nData.translations);
+        }
+        catch { /* ignore */ }
+        i18nScript.remove();
+    }
+    // Strip locale prefix for route matching (routes are locale-agnostic)
+    const config = getI18nConfig();
+    const matchPath = config ? stripLocalePrefix(location.pathname) : location.pathname;
+    const match = matchRoute(matchPath);
     if (!match)
         return;
     const layouts = match.route.layouts || [];

package/dist/runtime/router.d.ts

@@ -32,4 +32,8 @@ export declare class NkRouter {
     private buildLayoutTree;
     private createPageElement;
     private handleLinkClick;
+    /** Strip locale prefix from a path for internal route matching. */
+    private stripLocale;
+    /** Prepend locale prefix for browser-facing URLs. */
+    private withLocale;
 }

package/dist/runtime/router.js

@@ -1,5 +1,6 @@
 import { fetchLoaderData, fetchLayoutLoaderData, render404 } from './router-data.js';
 import { hydrateInitialRoute } from './router-hydration.js';
+import { getI18nConfig, getLocale, stripLocalePrefix, buildLocalePath } from './i18n.js';
 /**
  * Simple client-side router for LumenJS pages.
  * Handles popstate and link clicks for SPA navigation.
@@ -17,7 +18,10 @@ export class NkRouter {
             ...r,
             ...this.compilePattern(r.path),
         }));
-        window.addEventListener('popstate', () => this.navigate(location.pathname, false));
+        window.addEventListener('popstate', () => {
+            const path = this.stripLocale(location.pathname);
+            this.navigate(path, false);
+        });
         document.addEventListener('click', (e) => this.handleLinkClick(e));
         if (hydrate) {
             hydrateInitialRoute(this.routes, this.outlet, (p) => this.matchRoute(p), (tag, layoutTags, params) => {
@@ -27,7 +31,8 @@ export class NkRouter {
             });
         }
         else {
-            this.navigate(location.pathname, false);
+            const path = this.stripLocale(location.pathname);
+            this.navigate(path, false);
         }
     }
     compilePattern(path) {
@@ -48,7 +53,8 @@ export class NkRouter {
             return;
         }
         if (pushState) {
-            history.pushState(null, '', pathname);
+            const localePath = this.withLocale(pathname);
+            history.pushState(null, '', localePath);
         }
         this.params = match.params;
         // Lazy-load the page component if not yet registered
@@ -197,6 +203,16 @@ export class NkRouter {
         if (!href || href.startsWith('http') || href.startsWith('#') || anchor.hasAttribute('target'))
             return;
         event.preventDefault();
-        this.navigate(href);
+        this.navigate(this.stripLocale(href));
+    }
+    /** Strip locale prefix from a path for internal route matching. */
+    stripLocale(path) {
+        const config = getI18nConfig();
+        return config ? stripLocalePrefix(path) : path;
+    }
+    /** Prepend locale prefix for browser-facing URLs. */
+    withLocale(path) {
+        const config = getI18nConfig();
+        return config ? buildLocalePath(getLocale(), path) : path;
     }
 }

package/dist/shared/types.d.ts

@@ -7,10 +7,17 @@ export interface ManifestRoute {
     path: string;
     module: string;
     hasLoader: boolean;
+    tagName?: string;
     layouts?: string[];
 }
+export interface I18nManifest {
+    locales: string[];
+    defaultLocale: string;
+    prefixDefault: boolean;
+}
 export interface BuildManifest {
     routes: ManifestRoute[];
     apiRoutes: ManifestRoute[];
     layouts: ManifestLayout[];
+    i18n?: I18nManifest;
 }

package/dist/shared/utils.d.ts

@@ -17,6 +17,13 @@ export declare function dirToLayoutTagName(dir: string): string;
  * Pages use @customElement('page-xxx') which registers the element.
  */
 export declare function findTagName(mod: Record<string, any>): string | null;
+/**
+ * Convert a relative file path within pages/ to a page tag name.
+ *   'index.ts'           → 'page-index'
+ *   'docs/api-routes.ts' → 'page-docs-api-routes'
+ *   'blog/[slug].ts'     → 'page-blog-slug'
+ */
+export declare function filePathToTagName(filePath: string): string;
 /**
  * Check if a redirect response was returned from a loader.
  */

package/dist/shared/utils.js

@@ -49,6 +49,22 @@ export function findTagName(mod) {
     }
     return null;
 }
+/**
+ * Convert a relative file path within pages/ to a page tag name.
+ *   'index.ts'           → 'page-index'
+ *   'docs/api-routes.ts' → 'page-docs-api-routes'
+ *   'blog/[slug].ts'     → 'page-blog-slug'
+ */
+export function filePathToTagName(filePath) {
+    const name = filePath
+        .replace(/\.(ts|js)$/, '')
+        .replace(/\\/g, '-')
+        .replace(/\//g, '-')
+        .replace(/\[\.\.\.([^\]]+)\]/g, '$1')
+        .replace(/\[([^\]]+)\]/g, '$1')
+        .toLowerCase();
+    return `page-${name}`;
+}
 /**
  * Check if a redirect response was returned from a loader.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuraly/lumenjs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes",
   "type": "module",
   "main": "dist/cli.js",