@inglorious/ssx 1.6.5 → 1.7.1

package/README.md

@@ -202,6 +202,61 @@ src/pages/
 
 Dynamic routes use underscore prefix: `_id.js`, `_slug.js`, etc.
 
+### 🌍 Internationalization (i18n)
+
+Configure locales in `src/site.config.js`:
+
+```javascript
+export default {
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en", "it", "pt"],
+  },
+}
+```
+
+SSX generates localized variants for both static and dynamic pages:
+
+- Static page `src/pages/about.js`:
+  - `/about` (default locale)
+  - `/it/about`
+  - `/pt/about`
+- Dynamic page `src/pages/posts/_slug.js` with `staticPaths()`:
+  - `/posts/hello-world`
+  - `/it/posts/hello-world`
+  - `/pt/posts/hello-world`
+
+On the client, SSX automatically keeps `entity.locale` in sync on navigation (`routeChange`), so pages can usually just render from `entity.locale`:
+
+```javascript
+const messages = {
+  en: "Hello world!",
+  it: "Ciao mondo!",
+  pt: "Olá mundo!",
+}
+
+export const hello = {
+  render(entity) {
+    return html`<h1>${messages[entity.locale] ?? messages.en}</h1>`
+  },
+}
+```
+
+SSX automatically injects `page.locale` into `entity.locale` during server-side build/render too, so `load` is optional for locale initialization.
+
+If you need custom behavior, you can still override it in `load`:
+
+```javascript
+export async function load(entity, page) {
+  entity.locale = page.locale || "en"
+}
+```
+
+Notes:
+
+- The default locale is not prefixed (`/about`, not `/en/about`).
+- Locale-prefixed routes are handled in both build output and client-side navigation.
+
 ### ⚛️ Entity-Based State and Behavior
 
 ```javascript
@@ -552,6 +607,12 @@ export default {
     scrollBehavior: "smooth",
   },
 
+  // i18n routing
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en", "it", "pt"],
+  },
+
   // Vite config passthrough
   vite: {
     server: {
@@ -660,7 +721,7 @@ await build({
   outDir: "dist",
   configFile: "site.config.js",
   incremental: true,
-  clean: false,
+  force: false,
 })
 ```
 
@@ -693,9 +754,9 @@ Check out these example projects:
 
 - [x] TypeScript support
 - [x] Image optimization
-- [ ] API routes (serverless functions)
 - [x] Markdown support
-- [ ] i18n helpers
+- [x] i18n routing and locale-aware client navigation
+- [ ] API routes (serverless functions)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ssx",
-  "version": "1.6.5",
+  "version": "1.7.1",
   "description": "Server-Side-X. Xecution? Xperience? Who knows.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -27,7 +27,11 @@
   },
   "exports": {
     ".": "./types/index.d.ts",
-    "./markdown": "./src/utils/markdown.js"
+    "./markdown": "./src/utils/markdown.js",
+    "./i18n": {
+      "types": "./types/i18n.d.ts",
+      "import": "./src/utils/i18n.js"
+    }
   },
   "files": [
     "bin",
@@ -57,7 +61,7 @@
     "svgo": "^4.0.0",
     "vite": "^7.1.3",
     "vite-plugin-image-optimizer": "^2.0.3",
-    "@inglorious/web": "4.2.5"
+    "@inglorious/web": "4.3.0"
   },
   "devDependencies": {
     "prettier": "^3.6.2",

package/src/build/index.js

@@ -11,6 +11,7 @@ import {
   createManifest,
   determineRebuildPages,
   hashEntities,
+  hashRuntime,
   loadManifest,
   saveManifest,
 } from "./manifest.js"
@@ -27,12 +28,15 @@ import { createViteConfig } from "./vite-config.js"
  * @param {string} [options.rootDir="src"] - Source directory.
  * @param {string} [options.outDir="dist"] - Output directory.
  * @param {boolean} [options.incremental=true] - Whether to use incremental builds.
- * @param {boolean} [options.clean=false] - Whether to clean the output directory before building.
+ * @param {boolean} [options.force=false] - Whether to force a clean output directory before building.
  * @param {Object} [options.sitemap] - Sitemap configuration.
  * @param {Object} [options.rss] - RSS configuration.
  * @returns {Promise<{changed: number, skipped: number}>} Build statistics.
  */
 export async function build(options = {}) {
+  const previousNodeEnv = process.env.NODE_ENV
+  process.env.NODE_ENV = "production"
+
   const config = await loadConfig(options)
 
   const mergedOptions = { ...config, ...options }
@@ -40,7 +44,7 @@ export async function build(options = {}) {
     rootDir = ".",
     outDir = "dist",
     incremental = true,
-    clean = false,
+    force = false,
     sitemap,
     rss,
   } = mergedOptions
@@ -52,20 +56,21 @@ export async function build(options = {}) {
   // Create a temporary Vite server to load modules (supports TS)
   const vite = await createServer({
     ...createViteConfig(mergedOptions),
+    mode: "production",
     server: { middlewareMode: true, hmr: false },
     appType: "custom",
   })
   const loader = (p) => vite.ssrLoadModule(p)
 
   // 0. Get all pages to build (Fail fast if source is broken)
-  const allPages = await getPages(pagesDir, loader)
+  const allPages = await getPages(pagesDir, mergedOptions, loader)
   console.log(`📄 Found ${allPages.length} pages\n`)
 
   // Load previous build manifest
-  const manifest = incremental && !clean ? await loadManifest(outDir) : null
+  const manifest = incremental && !force ? await loadManifest(outDir) : null
 
   // 1. Clean and create output directory
-  if (clean || !manifest) {
+  if (force || !manifest) {
     // Clean output directory if forced or first build
     await fs.rm(outDir, { recursive: true, force: true })
     await fs.mkdir(outDir, { recursive: true })
@@ -75,15 +80,21 @@ export async function build(options = {}) {
   }
 
   // 2. Copy public assets before generating pages (could be useful if need to read `public/data.json`)
-  await copyPublicDir(options)
+  await copyPublicDir(mergedOptions)
 
   // Determine which pages need rebuilding
   const entitiesHash = await hashEntities(rootDir)
+  const runtimeHash = await hashRuntime()
   let pagesToChange = allPages
   let pagesToSkip = []
 
   if (manifest) {
-    const result = await determineRebuildPages(allPages, manifest, entitiesHash)
+    const result = await determineRebuildPages(
+      allPages,
+      manifest,
+      entitiesHash,
+      runtimeHash,
+    )
     pagesToChange = result.pagesToBuild
     pagesToSkip = result.pagesToSkip
 
@@ -129,7 +140,7 @@ export async function build(options = {}) {
   // 8. Always regenerate client-side JavaScript (it's cheap and ensures consistency)
   console.log("\n📝 Generating client scripts...\n")
 
-  const app = generateApp(store, allPages)
+  const app = generateApp(allPages, { ...mergedOptions, isDev: false })
   await fs.writeFile(path.join(outDir, "main.js"), app, "utf-8")
   console.log(`  ✓ main.js\n`)
 
@@ -147,7 +158,10 @@ export async function build(options = {}) {
 
   // 11. Bundle with Vite
   console.log("\n📦 Bundling with Vite...\n")
-  const viteConfig = createViteConfig(mergedOptions)
+  const viteConfig = {
+    ...createViteConfig(mergedOptions),
+    mode: "production",
+  }
   await viteBuild(viteConfig)
 
   await vite.close()
@@ -156,16 +170,28 @@ export async function build(options = {}) {
 
   // 13. Save manifest for next build
   if (incremental) {
-    const newManifest = await createManifest(allGeneratedPages, entitiesHash)
+    const newManifest = await createManifest(
+      allGeneratedPages,
+      entitiesHash,
+      runtimeHash,
+    )
     await saveManifest(outDir, newManifest)
   }
 
   console.log("\n✨ Build complete!\n")
 
-  return {
+  const result = {
     changed: changedPages.length,
     skipped: skippedPages.length,
   }
+
+  if (previousNodeEnv == null) {
+    delete process.env.NODE_ENV
+  } else {
+    process.env.NODE_ENV = previousNodeEnv
+  }
+
+  return result
 }
 
 /**

package/src/build/manifest.js

@@ -3,6 +3,14 @@ import fs from "node:fs/promises"
 import path from "node:path"
 
 const MANIFEST_FILE = ".ssx-manifest.json"
+const RUNTIME_FILES = [
+  "../scripts/app.js",
+  "./pages.js",
+  "./vite-config.js",
+  "../utils/i18n.js",
+  "../router/index.js",
+  "../render/index.js",
+]
 
 /**
  * Loads the build manifest from the previous build.
@@ -18,7 +26,7 @@ export async function loadManifest(outDir) {
     return JSON.parse(content)
   } catch {
     // No manifest exists (first build or clean build)
-    return { pages: {}, entities: null, buildTime: null }
+    return { pages: {}, entities: null, runtime: null, buildTime: null }
   }
 }
 
@@ -61,6 +69,25 @@ export async function hashEntities(rootDir) {
   return await hashFile(entitiesPath)
 }
 
+/**
+ * Computes a hash for SSX runtime internals.
+ * When this changes, page HTML should be regenerated even if source pages did not change.
+ *
+ * @returns {Promise<string>} Hash of runtime internals.
+ */
+export async function hashRuntime() {
+  const root = import.meta.dirname
+  const contents = await Promise.all(
+    RUNTIME_FILES.map(async (relativePath) => {
+      const filePath = path.resolve(root, relativePath)
+      const content = await fs.readFile(filePath, "utf-8")
+      return `${relativePath}:${content}`
+    }),
+  )
+
+  return crypto.createHash("md5").update(contents.join("\n")).digest("hex")
+}
+
 /**
  * Determines which pages need to be rebuilt.
  * Compares current file hashes against the manifest.
@@ -68,15 +95,26 @@ export async function hashEntities(rootDir) {
  * @param {Array<Object>} pages - All pages to potentially build.
  * @param {Object} manifest - Previous build manifest.
  * @param {string} entitiesHash - Current entities hash.
+ * @param {string} runtimeHash - Current SSX runtime hash.
  * @returns {Promise<{pagesToBuild: Array<Object>, pagesToSkip: Array<Object>}>} Object with pagesToBuild and pagesSkipped.
  */
-export async function determineRebuildPages(pages, manifest, entitiesHash) {
+export async function determineRebuildPages(
+  pages,
+  manifest,
+  entitiesHash,
+  runtimeHash,
+) {
   // If entities changed, rebuild all pages
   if (manifest.entities !== entitiesHash) {
     console.log("📦 Entities changed, rebuilding all pages\n")
     return { pagesToBuild: pages, pagesToSkip: [] }
   }
 
+  if (manifest.runtime !== runtimeHash) {
+    console.log("🔁 SSX runtime changed, rebuilding all pages\n")
+    return { pagesToBuild: pages, pagesToSkip: [] }
+  }
+
   const pagesToBuild = []
   const pagesToSkip = []
 
@@ -99,9 +137,10 @@ export async function determineRebuildPages(pages, manifest, entitiesHash) {
  *
  * @param {Array<Object>} renderedPages - All rendered pages.
  * @param {string} entitiesHash - Hash of entities file.
+ * @param {string} runtimeHash - Hash of SSX runtime internals.
  * @returns {Promise<Object>} New manifest.
  */
-export async function createManifest(renderedPages, entitiesHash) {
+export async function createManifest(renderedPages, entitiesHash, runtimeHash) {
   const pages = {}
 
   for (const page of renderedPages) {
@@ -115,6 +154,7 @@ export async function createManifest(renderedPages, entitiesHash) {
   return {
     pages,
     entities: entitiesHash,
+    runtime: runtimeHash,
     buildTime: new Date().toISOString(),
   }
 }

package/src/build/manifest.test.js

@@ -7,6 +7,7 @@ import {
   determineRebuildPages,
   hashEntities,
   hashFile,
+  hashRuntime,
   loadManifest,
   saveManifest,
 } from "./manifest"
@@ -37,7 +38,12 @@ describe("manifest", () => {
       fs.readFile.mockRejectedValue(new Error("ENOENT"))
 
       const result = await loadManifest("dist")
-      expect(result).toEqual({ pages: {}, entities: null, buildTime: null })
+      expect(result).toEqual({
+        pages: {},
+        entities: null,
+        runtime: null,
+        buildTime: null,
+      })
     })
   })
 
@@ -80,11 +86,20 @@ describe("manifest", () => {
     })
   })
 
+  describe("hashRuntime", () => {
+    it("should hash SSX runtime files", async () => {
+      fs.readFile.mockResolvedValue("runtime")
+      const hash = await hashRuntime()
+      expect(typeof hash).toBe("string")
+      expect(hash.length).toBe(32)
+    })
+  })
+
   describe("determineRebuildPages", () => {
     it("should rebuild all if entities hash changed", async () => {
       const pages = [{ path: "/" }]
       const manifest = { entities: "old" }
-      const result = await determineRebuildPages(pages, manifest, "new")
+      const result = await determineRebuildPages(pages, manifest, "new", "rt")
 
       expect(result.pagesToBuild).toEqual(pages)
       expect(result.pagesToSkip).toEqual([])
@@ -113,13 +128,35 @@ describe("manifest", () => {
         return ""
       })
 
-      const result = await determineRebuildPages(pages, manifest, "hash")
+      const result = await determineRebuildPages(
+        pages,
+        { ...manifest, runtime: "same-rt" },
+        "hash",
+        "same-rt",
+      )
 
       expect(result.pagesToBuild).toHaveLength(1)
       expect(result.pagesToBuild[0].path).toBe("/changed")
       expect(result.pagesToSkip).toHaveLength(1)
       expect(result.pagesToSkip[0].path).toBe("/same")
     })
+
+    it("should rebuild all if runtime hash changed", async () => {
+      const pages = [{ path: "/" }]
+      const manifest = { entities: "hash", runtime: "old-rt" }
+      const result = await determineRebuildPages(
+        pages,
+        manifest,
+        "hash",
+        "new-rt",
+      )
+
+      expect(result.pagesToBuild).toEqual(pages)
+      expect(result.pagesToSkip).toEqual([])
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("runtime changed"),
+      )
+    })
   })
 
   describe("createManifest", () => {
@@ -129,6 +166,7 @@ describe("manifest", () => {
         { path: "/about", filePath: "about.js" },
       ]
       const entitiesHash = "entities-hash"
+      const runtimeHash = "runtime-hash"
 
       fs.readFile.mockImplementation(async (path) => {
         if (path === "index.js") return "index content"
@@ -136,9 +174,14 @@ describe("manifest", () => {
         return ""
       })
 
-      const manifest = await createManifest(renderedPages, entitiesHash)
+      const manifest = await createManifest(
+        renderedPages,
+        entitiesHash,
+        runtimeHash,
+      )
 
       expect(manifest.entities).toBe(entitiesHash)
+      expect(manifest.runtime).toBe(runtimeHash)
       expect(manifest.buildTime).toBeDefined()
       expect(manifest.pages["/"]).toEqual({
         hash: "176b689259e8d68ef0aa869fd3b3be45",

package/src/build/pages.js

@@ -32,6 +32,10 @@ export async function generatePages(store, pages, options = {}, loader) {
     page.module = module
 
     const entity = api.getEntity(page.moduleName)
+    if (page.locale) {
+      entity.locale = page.locale
+    }
+
     if (module.load) {
       await module.load(entity, page)
     }

package/src/build/pages.test.js

@@ -80,4 +80,54 @@ describe("generatePages", () => {
     expect(renderPage).toHaveBeenCalled()
     expect(extractPageMetadata).not.toHaveBeenCalled()
   })
+
+  it("should set entity.locale from page.locale even without load()", async () => {
+    const entity = {}
+    const store = { _api: { getEntity: vi.fn(() => entity) } }
+    const pages = [
+      {
+        path: "/it/p4",
+        filePath: "virtual-page.js",
+        moduleName: "p4",
+        locale: "it",
+      },
+    ]
+    const loader = vi.fn(async () => ({ render: () => {} }))
+
+    vi.clearAllMocks()
+    renderPage.mockResolvedValue("<html></html>")
+    extractPageMetadata.mockReturnValue({})
+
+    await generatePages(store, pages, {}, loader)
+
+    expect(entity.locale).toBe("it")
+  })
+
+  it("should overwrite entity.locale for each localized page render", async () => {
+    const entity = { locale: "en" }
+    const store = { _api: { getEntity: vi.fn(() => entity) } }
+    const pages = [
+      {
+        path: "/it/p5",
+        filePath: "virtual-page.js",
+        moduleName: "p5",
+        locale: "it",
+      },
+      {
+        path: "/pt/p5",
+        filePath: "virtual-page.js",
+        moduleName: "p5",
+        locale: "pt",
+      },
+    ]
+    const loader = vi.fn(async () => ({ render: () => {} }))
+
+    vi.clearAllMocks()
+    renderPage.mockResolvedValue("<html></html>")
+    extractPageMetadata.mockReturnValue({})
+
+    await generatePages(store, pages, {}, loader)
+
+    expect(entity.locale).toBe("pt")
+  })
 })

package/src/build/vite-config.js

@@ -1,5 +1,6 @@
 import path from "node:path"
 
+import { minifyTemplateLiterals } from "rollup-plugin-minify-template-literals"
 import { mergeConfig } from "vite"
 import { ViteImageOptimizer } from "vite-plugin-image-optimizer"
 
@@ -21,6 +22,7 @@ export function createViteConfig(options = {}) {
       root: process.cwd(),
       publicDir: publicDir,
       plugins: [
+        minifyTemplateLiterals(),
         ViteImageOptimizer({
           // Options can be overridden by the user in site.config.js via the `vite` property
         }),
@@ -44,9 +46,6 @@ export function createViteConfig(options = {}) {
               }
             },
           },
-          plugins: [
-            // minifyTemplateLiterals(), // TODO: minification breaks hydration. The footprint difference is minimal after all
-          ],
         },
       },
       resolve: {

package/src/dev/index.js

@@ -51,7 +51,7 @@ export async function dev(options = {}) {
       }
 
       // Get all pages on each request (in dev mode, pages might be added/removed)
-      const pages = await getPages(pagesDir, loader)
+      const pages = await getPages(pagesDir, mergedOptions, loader)
 
       // Find matching page
       const page = pages.find((p) => matchRoute(p.path, url))
@@ -64,12 +64,16 @@ export async function dev(options = {}) {
       const store = await generateStore(pages, mergedOptions, loader)
 
       const entity = store._api.getEntity(page.moduleName)
+      if (page.locale) {
+        entity.locale = page.locale
+      }
+
       if (module.load) {
         await module.load(entity, page)
       }
 
       // Generate and update the virtual app file BEFORE rendering
-      const app = generateApp(store, pages)
+      const app = generateApp(store, pages, { ...mergedOptions, isDev: true })
       virtualFiles.set("/main.js", app)
 
       // Invalidate the virtual module to ensure Vite picks up changes

package/src/render/html.js

@@ -18,6 +18,7 @@ import { layout as defaultLayout } from "./layout.js"
  * @param {boolean} [options.wrap=false] - Whether to wrap the output in a full HTML document.
  * @param {Function} [options.layout] - Custom layout function.
  * @param {boolean} [options.stripLitMarkers=false] - Whether to remove Lit hydration markers (for static output).
+ * @param {Object} [options.ssxEntity] - Per-page entity state for client hydration.
  * @returns {Promise<string>} The generated HTML string.
  */
 export async function toHTML(store, renderFn, options = {}) {
@@ -38,7 +39,16 @@ export async function toHTML(store, renderFn, options = {}) {
   if (!options.wrap) return finalHTML
 
   const layout = options.layout ?? defaultLayout
-  return layout(finalHTML, options)
+  let html = layout(finalHTML, options)
+
+  if (options.ssxEntity) {
+    html = html.replace(
+      /<body[^>]*>/,
+      `$&<script type="application/json" id="__SSX_ENTITY__">${JSON.stringify(options.ssxEntity)}</script>`,
+    )
+  }
+
+  return html
 }
 
 /**

package/src/render/index.js

@@ -52,5 +52,6 @@ export async function renderPage(store, page, entity, options = {}) {
     styles,
     head,
     scripts,
+    ssxEntity: { [moduleName]: entity },
   })
 }

package/src/router/index.js

@@ -17,10 +17,11 @@ const SCORE_MULTIPLIER = 0.1
  * to generate all possible paths.
  *
  * @param {string} pagesDir - The directory containing page files.
+ * @param {Object} [options] - config object with i18n configuration { defaultLocale, locales }.
  * @param {Function} [loader] - Optional loader function (e.g. vite.ssrLoadModule).
  * @returns {Promise<Array<Object>>} A list of page objects with metadata.
  */
-export async function getPages(pagesDir = "pages", loader) {
+export async function getPages(pagesDir = "pages", options, loader) {
   const routes = await getRoutes(pagesDir)
   const pages = []
   const load = loader || ((p) => import(pathToFileURL(path.resolve(p))))
@@ -45,7 +46,7 @@ export async function getPages(pagesDir = "pages", loader) {
 
             const params = extractParams(route, path)
 
-            pages.push({
+            addPages(pages, options, {
               pattern: route.pattern,
               path,
               params,
@@ -61,8 +62,7 @@ export async function getPages(pagesDir = "pages", loader) {
           )
         }
       } else {
-        // Static route - add directly
-        pages.push({
+        addPages(pages, options, {
           pattern: route.pattern,
           path: route.pattern || "/",
           params: {},
@@ -81,38 +81,30 @@ export async function getPages(pagesDir = "pages", loader) {
   return pages
 }
 
-/**
- * Resolves a URL to a specific page file and extracts route parameters.
- * This is primarily used by the development server for on-demand rendering.
- *
- * @param {string} url - The URL to resolve (e.g., "/posts/hello").
- * @param {string} pagesDir - The directory containing page files.
- * @returns {Promise<{filePath: string, params: Object}|null>} The resolved page info or null if not found.
- */
-export async function resolvePage(url, pagesDir = "pages") {
-  const routes = await getRoutes(pagesDir)
-
-  // Normalize URL (remove query string and hash)
-  const [fullPath] = url.split("?")
-  const [normalizedUrl] = fullPath.split("#")
+function addPages(pages, options = {}, pageData) {
+  const { i18n = {} } = options
 
-  for (const route of routes) {
-    const match = route.regex.exec(normalizedUrl)
+  if (!i18n.locales?.length) {
+    pages.push(pageData)
+    return
+  }
 
-    if (match) {
-      const params = {}
-      route.params.forEach((param, i) => {
-        params[param] = match[i + NEXT_MATCH]
-      })
+  for (const locale of i18n.locales) {
+    const isDefault = locale === i18n.defaultLocale
+    const prefix = isDefault ? "" : `/${locale}`
 
-      return {
-        filePath: route.filePath,
-        params,
-      }
+    let localizedPath = prefix + pageData.path
+    // Handle root path: / -> / (default), /fr (fr)
+    if (pageData.path === "/" && !isDefault) {
+      localizedPath = prefix
     }
-  }
 
-  return null
+    pages.push({
+      ...pageData,
+      path: localizedPath,
+      locale,
+    })
+  }
 }
 
 /**

package/src/router/router.test.js

@@ -2,7 +2,7 @@ import path from "node:path"
 
 import { afterEach, describe, expect, it, vi } from "vitest"
 
-import { getPages, getRoutes, matchRoute, resolvePage } from "./index.js"
+import { getPages, getRoutes, matchRoute } from "./index.js"
 
 const ROOT_DIR = path.join(import.meta.dirname, "..", "__fixtures__")
 const PAGES_DIR = path.join(ROOT_DIR, "src", "pages")
@@ -39,56 +39,7 @@ describe("router", () => {
       // Root usually comes after specific paths but before catch-all if it was a catch-all root,
       // but here / is static.
       // Let's just check that we found them.
-      expect(routes).toHaveLength(6)
-    })
-  })
-
-  describe("resolvePage", () => {
-    it("should resolve root page", async () => {
-      const page = await resolvePage("/", PAGES_DIR)
-      expect(page).not.toBeNull()
-      expect(page.filePath).toContain("index.js")
-      expect(page.params).toEqual({})
-    })
-
-    it("should resolve static page", async () => {
-      const page = await resolvePage("/about", PAGES_DIR)
-      expect(page).not.toBeNull()
-      expect(page.filePath).toContain("about.js")
-      expect(page.params).toEqual({})
-    })
-
-    it("should resolve dynamic page with params", async () => {
-      const page = await resolvePage("/posts/hello-world", PAGES_DIR)
-      expect(page).not.toBeNull()
-      expect(page.filePath).toContain("posts")
-      expect(page.params).toEqual({ slug: "hello-world" })
-    })
-
-    it("should resolve catch-all page", async () => {
-      const page = await resolvePage("/api/v1/users", PAGES_DIR)
-      expect(page).not.toBeNull()
-      expect(page.filePath).toContain("api")
-      expect(page.params).toEqual({ path: "v1/users" })
-    })
-
-    it("should return null for non-matching url", async () => {
-      // Since we have a catch-all /api/*, /api/foo matches.
-      // But /foo doesn't match anything except maybe if we had a root catch-all.
-      // We don't have a root catch-all, just /api/*.
-      // Wait, /blog/:slug matches /blog/foo.
-      // /posts/:id matches /posts/1.
-      // /about matches /about.
-      // / matches /.
-      // So /foo should return null.
-      const page = await resolvePage("/foo", PAGES_DIR)
-      expect(page).toBeNull()
-    })
-
-    it("should return null for dynamic route missing param", async () => {
-      // /posts/:slug requires a slug
-      const page = await resolvePage("/posts", PAGES_DIR)
-      expect(page).toBeNull()
+      expect(routes.length).toBeGreaterThanOrEqual(6)
     })
   })
 
@@ -116,6 +67,40 @@ describe("router", () => {
       expect(consoleSpy).toHaveBeenCalled()
       expect(consoleSpy.mock.calls[2][0]).toContain("has no staticPaths")
     })
+
+    it("should localize static and dynamic pages when i18n is enabled", async () => {
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+      const i18n = {
+        defaultLocale: "en",
+        locales: ["en", "it"],
+      }
+      const pages = await getPages(PAGES_DIR, { i18n })
+
+      const rootPages = pages.filter((p) => p.pattern === "/")
+      expect(rootPages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ path: "/", locale: "en" }),
+          expect.objectContaining({ path: "/it", locale: "it" }),
+        ]),
+      )
+
+      const aboutPages = pages.filter((p) => p.pattern === "/about")
+      expect(aboutPages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ path: "/about", locale: "en" }),
+          expect.objectContaining({ path: "/it/about", locale: "it" }),
+        ]),
+      )
+
+      expect(
+        pages.some(
+          (p) =>
+            p.pattern === "/posts/:slug" && p.path.startsWith("/it/posts/"),
+        ),
+      ).toBe(true)
+
+      expect(consoleSpy).toHaveBeenCalled()
+    })
   })
 
   describe("matchRoute", () => {

package/src/scripts/app.js

@@ -2,52 +2,92 @@
  * Generates the client-side entry point script.
  * This script hydrates the store with the initial state (entities) and sets up the router.
  *
- * @param {Object} store - The server-side store instance containing the initial state.
  * @param {Array<Object>} pages - List of page objects to generate routes for.
+ * @param {Object} [options] - Runtime options.
  * @returns {string} The generated JavaScript code for the client entry point.
  */
-export function generateApp(store, pages) {
-  // Collect all unique page modules and their exports
-  const routes = pages
-    .filter((page, index) => {
-      return pages.findIndex((p) => p.pattern === page.pattern) === index
-    })
-    .map(
-      (page) =>
-        `  "${page.pattern}": () => import("@/pages/${page.modulePath}")`,
+export function generateApp(pages, options = {}) {
+  const i18n = options.i18n || inferI18nFromPages(pages)
+  const isDev = Boolean(options.isDev)
+
+  // Build client route map, including localized patterns (e.g. /it/about).
+  const routesByPattern = new Map()
+  for (const page of pages) {
+    const routePattern = getClientRoutePattern(page)
+    if (routesByPattern.has(routePattern)) continue
+    routesByPattern.set(
+      routePattern,
+      `  "${routePattern}": () => import("@/pages/${page.modulePath}")`,
     )
+  }
+  const routes = [...routesByPattern.values()]
 
   return `import { createDevtools, createStore, mount } from "@inglorious/web"
 import { getRoute, router, setRoutes } from "@inglorious/web/router"
+import { getLocaleFromPath } from "@inglorious/ssx/i18n"
+
+const normalizePathname = (path = "/") => path.split("?")[0].split("#")[0]
+const normalizeRoutePath = (path = "/") => {
+  const pathname = normalizePathname(path)
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1)
+  }
+  return pathname
+}
 
 const pages = ${JSON.stringify(
-    pages.map(({ pattern, path, moduleName }) => ({
+    pages.map(({ pattern, path, moduleName, locale }) => ({
       pattern,
       path,
       moduleName,
+      locale,
     })),
     null,
     2,
   )}
-const path = window.location.pathname + window.location.search + window.location.hash
-const page = pages.find((page) => page.path === path)
+const path = normalizeRoutePath(window.location.pathname)
+const page = pages.find((page) => normalizeRoutePath(page.path) === path)
 
 const types = { router }
 
+const i18n = ${JSON.stringify(i18n, null, 2)}
+const isDev = ${JSON.stringify(isDev)}
+
+const ssxEntity = JSON.parse(document.getElementById("__SSX_ENTITY__").textContent)
+
 const entities = {
   router: {
     type: "router",
-    path: page.path,
-    route: page.moduleName,
+    path,
+    route: page?.moduleName,
   },
-${JSON.stringify(store.getState(), null, 2).slice(1, -1)}
+  i18n: {
+    type: "i18n",
+    ...i18n,
+  },
+  ...ssxEntity,
 }
 
 const middlewares = []
-if (import.meta.env.DEV) {
+if (isDev) {
   middlewares.push(createDevtools().middleware)
 }
 
+const systems = []
+if (i18n.defaultLocale && i18n.locales?.length) {
+  systems.push({
+    routeChange(state, payload) {
+      const routeType = payload?.route
+      if (!routeType) return
+
+      const entity = state[routeType]
+      if (!entity) return
+
+      entity.locale = getLocaleFromPath(payload.path, i18n)
+    },
+  })
+}
+
 setRoutes({
 ${routes.join(",\n")}
 })
@@ -56,7 +96,7 @@ const module = await getRoute(page.pattern)()
 const type = module[page.moduleName]
 types[page.moduleName] = type
 
-const store = createStore({ types, entities, middlewares, autoCreateEntities: true })
+const store = createStore({ types, entities, middlewares, systems, autoCreateEntities: true })
 
 const root = document.getElementById("root")
 
@@ -66,3 +106,39 @@ mount(store, (api) => {
 }, root)
 `
 }
+
+function inferI18nFromPages(pages = []) {
+  const locales = [...new Set(pages.map((page) => page.locale).filter(Boolean))]
+  if (!locales.length) return {}
+
+  const defaultLocale =
+    locales.find((locale) =>
+      pages.some((page) => {
+        if (page.locale !== locale) return false
+        const localePrefix = `/${locale}`
+        return (
+          page.path === "/" ||
+          !(
+            page.path === localePrefix ||
+            page.path.startsWith(`${localePrefix}/`)
+          )
+        )
+      }),
+    ) || locales[0]
+
+  return { defaultLocale, locales }
+}
+
+function getClientRoutePattern(page) {
+  const { pattern = "/", path = "", locale } = page
+  if (!locale) return pattern
+
+  const localePrefix = `/${locale}`
+  const isLocalePrefixedPath =
+    path === localePrefix || path.startsWith(`${localePrefix}/`)
+
+  if (!isLocalePrefixedPath) return pattern
+  if (pattern === "/") return localePrefix
+
+  return `${localePrefix}${pattern}`
+}

package/src/scripts/app.test.js

@@ -2,7 +2,6 @@ import path from "node:path"
 
 import { describe, expect, it } from "vitest"
 
-import { generateStore } from "../store"
 import { generateApp } from "./app"
 
 const ROOT_DIR = path.join(import.meta.dirname, "..", "__fixtures__")
@@ -16,9 +15,8 @@ describe("generateApp", () => {
       modulePath: "index.js",
       filePath: PAGES_DIR,
     }
-    const store = await generateStore([page], { rootDir: ROOT_DIR })
 
-    const app = generateApp(store, [page])
+    const app = generateApp([page])
 
     expect(app).toMatchSnapshot()
   })
@@ -30,9 +28,8 @@ describe("generateApp", () => {
       modulePath: "about.js",
       filePath: path.join(PAGES_DIR, "about.js"),
     }
-    const store = await generateStore([page], { rootDir: ROOT_DIR })
 
-    const app = generateApp(store, [page])
+    const app = generateApp([page])
 
     expect(app).toMatchSnapshot()
   })
@@ -44,9 +41,8 @@ describe("generateApp", () => {
       modulePath: "blog.js",
       filePath: path.join(PAGES_DIR, "blog.js"),
     }
-    const store = await generateStore([page], { rootDir: ROOT_DIR })
 
-    const app = generateApp(store, [page])
+    const app = generateApp([page])
 
     expect(app).toMatchSnapshot()
   })
@@ -58,10 +54,46 @@ describe("generateApp", () => {
       modulePath: "post.js",
       filePath: path.join(PAGES_DIR, "posts", "_slug.js"),
     }
-    const store = await generateStore([page], { rootDir: ROOT_DIR })
 
-    const app = generateApp(store, [page])
+    const app = generateApp([page])
 
     expect(app).toMatchSnapshot()
   })
+
+  it("should include localized client routes when i18n pages are provided", async () => {
+    const page = {
+      pattern: "/hello",
+      path: "/hello",
+      modulePath: "hello.js",
+      filePath: path.join(PAGES_DIR, "hello.js"),
+      moduleName: "hello",
+      locale: "en",
+    }
+    const localizedPages = [
+      page,
+      { ...page, path: "/it/hello", locale: "it" },
+      { ...page, path: "/pt/hello", locale: "pt" },
+    ]
+
+    const app = generateApp(localizedPages)
+
+    expect(app).toContain(`"/hello": () => import("@/pages/hello.js")`)
+    expect(app).toContain(`"/it/hello": () => import("@/pages/hello.js")`)
+    expect(app).toContain(`"/pt/hello": () => import("@/pages/hello.js")`)
+    expect(app).toContain(`const isDev = false`)
+    expect(app).toContain(
+      `import { getLocaleFromPath } from "@inglorious/ssx/i18n"`,
+    )
+    expect(app).toContain(`const systems = []`)
+    expect(app).toContain(`routeChange(state, payload)`)
+    expect(app).toContain(
+      `entity.locale = getLocaleFromPath(payload.path, i18n)`,
+    )
+    expect(app).toContain(
+      `const path = normalizeRoutePath(window.location.pathname)`,
+    )
+    expect(app).toContain(
+      `const page = pages.find((page) => normalizeRoutePath(page.path) === path)`,
+    )
+  })
 })

package/src/utils/i18n.js

@@ -0,0 +1,11 @@
+export function getLocaleFromPath(
+  pathname,
+  { defaultLocale = "en", locales = [] } = {},
+) {
+  const [pathOnly] = pathname.split("?")
+  const [cleanPath] = pathOnly.split("#")
+  const first = cleanPath.split("/").filter(Boolean)[0]
+
+  if (first && locales.includes(first)) return first
+  return defaultLocale
+}

package/src/utils/markdown.js

@@ -3,39 +3,9 @@ import katex from "katex"
 import MarkdownIt from "markdown-it"
 import texmath from "markdown-it-texmath"
 
-export function createMarkdownRenderer() {
-  const md = new MarkdownIt({
-    html: true,
-    linkify: true,
-    typographer: true,
-    highlight: (str, lang) => {
-      if (lang === "mermaid") {
-        return `<div class="mermaid">${str}</div>`
-      }
-      if (lang && hljs.getLanguage(lang)) {
-        try {
-          return hljs.highlight(str, { language: lang }).value
-        } catch (err) {
-          console.error(err)
-        }
-      }
-      return "" // use external default escaping
-    },
-  })
-
-  // Add LaTeX support
-  md.use(texmath, {
-    engine: katex,
-    delimiters: "dollars",
-    katexOptions: { macros: { "\\RR": "\\mathbb{R}" } },
-  })
-
-  return md
-}
-
 export function renderMarkdown(markdown) {
   const md = createMarkdownRenderer()
-  // Simple frontmatter stripping for runtime rendering (avoids Buffer/gray-matter on client)
+  // gray-matter gives an error on the client, so we are going to use a simpler way to extract content
   const content = markdown.replace(/^---[\s\S]*?---\n/, "")
   return md.render(content)
 }
@@ -50,6 +20,7 @@ export function markdownPlugin(options = {}) {
     async transform(code, id) {
       if (!id.endsWith(".md")) return
 
+      // prevents importing gray-matter on the client
       const matter = (await import("gray-matter")).default
       const { content, data } = matter(code)
       const htmlContent = md.render(content)
@@ -58,18 +29,14 @@ export function markdownPlugin(options = {}) {
 
       let mermaidCode = ""
       if (hasMermaid) {
-        mermaidCode = `
-          import mermaid from "mermaid"
-          if (typeof window !== "undefined") {
-            mermaid.initialize({ startOnLoad: false })
-          }
-        `
+        mermaidCode = `import mermaid from "mermaid"`
       }
 
       return `
-        import { html, unsafeHTML } from "@inglorious/web"
         import "katex/dist/katex.min.css"
         import "highlight.js/styles/${theme}.css"
+
+        import { html, unsafeHTML } from "@inglorious/web"
         ${mermaidCode}
 
         export const metadata = ${JSON.stringify(data)}
@@ -79,7 +46,7 @@ export function markdownPlugin(options = {}) {
             if (typeof window !== "undefined" && ${hasMermaid}) {
               setTimeout(() => {
                 mermaid.run({ querySelector: ".mermaid" })
-              }, 0)
+              })
             }
             return html\`<div class="markdown-body">\${unsafeHTML(${JSON.stringify(htmlContent)})}</div>\`
           }
@@ -88,3 +55,48 @@ export function markdownPlugin(options = {}) {
     },
   }
 }
+
+function createMarkdownRenderer() {
+  const md = new MarkdownIt({
+    html: true,
+    linkify: true,
+    typographer: true,
+    highlight: (str, lang) => {
+      if (lang && hljs.getLanguage(lang)) {
+        try {
+          return hljs.highlight(str, { language: lang }).value
+        } catch (err) {
+          console.error(err)
+        }
+      }
+      return "" // use external default escaping
+    },
+  })
+
+  // Add LaTeX support
+  md.use(texmath, {
+    engine: katex,
+    delimiters: "dollars",
+    katexOptions: { macros: { "\\RR": "\\mathbb{R}" } },
+  })
+
+  const defaultFence =
+    md.renderer.rules.fence?.bind(md.renderer.rules) ||
+    ((tokens, idx, options, env, self) =>
+      self.renderToken(tokens, idx, options, env, self))
+
+  // Render mermaid fences as standalone blocks (not nested in <pre><code>),
+  // avoiding invalid HTML that can cause hydration mismatches.
+  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const token = tokens[idx]
+    const lang = token.info?.trim().split(/\s+/)[0]
+
+    if (lang === "mermaid") {
+      return `<div class="mermaid">${md.utils.escapeHtml(token.content)}</div>\n`
+    }
+
+    return defaultFence(tokens, idx, options, env, self)
+  }
+
+  return md
+}

package/types/i18n.d.ts

@@ -0,0 +1,6 @@
+export interface I18nConfig {
+  defaultLocale: string
+  locales: string[]
+}
+
+export function getLocaleFromPath(pathname: string, config: I18nConfig): string