@nuraly/lumenjs 0.1.0 → 0.1.2

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,17 +104,39 @@ export async function createDevServer(options) {
             ...shared.plugins,
             lumenApiRoutesPlugin(apiDir, projectDir),
             litHmrPlugin(projectDir),
+            ...(i18nConfig ? [i18nPlugin(projectDir, i18nConfig)] : []),
             ...(editorMode ? [sourceAnnotatorPlugin(projectDir)] : []),
             {
                 name: 'lumenjs-index-html',
                 configureServer(server) {
                     server.middlewares.use((req, res, next) => {
+                        // Guard against malformed percent-encoded URLs that crash Vite's transformIndexHtml
+                        if (req.url) {
+                            try {
+                                decodeURIComponent(req.url);
+                            }
+                            catch {
+                                res.statusCode = 400;
+                                res.end('Bad Request');
+                                return;
+                            }
+                        }
                         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 +149,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 +162,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 +179,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.
  */