@uniweb/build 0.2.5 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -51,7 +51,7 @@
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.0.7",
-    "@uniweb/runtime": "0.3.1"
+    "@uniweb/runtime": "0.4.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -60,7 +60,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.2.3"
+    "@uniweb/core": "0.2.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/audit.js

@@ -0,0 +1,184 @@
+/**
+ * Audit translations for stale and missing entries
+ *
+ * Compares locale translation files against the manifest to identify:
+ * - Valid: translations that match current manifest entries
+ * - Missing: manifest entries without translations
+ * - Stale: translations for content that no longer exists
+ */
+
+import { readFile, writeFile } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * Audit a locale file against the manifest
+ * @param {string} localesPath - Path to locales directory
+ * @param {string} locale - Locale code (e.g., 'es')
+ * @returns {Promise<Object>} Audit result { locale, exists, total, valid, missing, stale }
+ */
+export async function auditLocale(localesPath, locale) {
+  const manifestPath = join(localesPath, 'manifest.json')
+  const localePath = join(localesPath, `${locale}.json`)
+
+  if (!existsSync(manifestPath)) {
+    throw new Error('Manifest not found. Run "uniweb i18n extract" first.')
+  }
+
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf-8'))
+  const manifestHashes = new Set(Object.keys(manifest.units))
+
+  // Handle missing locale file
+  if (!existsSync(localePath)) {
+    return {
+      locale,
+      exists: false,
+      total: manifestHashes.size,
+      valid: [],
+      missing: [...manifestHashes],
+      stale: []
+    }
+  }
+
+  const translations = JSON.parse(await readFile(localePath, 'utf-8'))
+  const translationHashes = new Set(Object.keys(translations))
+
+  const valid = []
+  const missing = []
+  const stale = []
+
+  // Check manifest entries
+  for (const hash of manifestHashes) {
+    if (translationHashes.has(hash)) {
+      valid.push({
+        hash,
+        source: manifest.units[hash].source,
+        translation: getTranslationText(translations[hash])
+      })
+    } else {
+      missing.push({
+        hash,
+        source: manifest.units[hash].source,
+        field: manifest.units[hash].field,
+        contexts: manifest.units[hash].contexts
+      })
+    }
+  }
+
+  // Check for stale entries (in translations but not in manifest)
+  for (const hash of translationHashes) {
+    if (!manifestHashes.has(hash)) {
+      stale.push({
+        hash,
+        translation: getTranslationText(translations[hash])
+      })
+    }
+  }
+
+  return {
+    locale,
+    exists: true,
+    total: manifestHashes.size,
+    valid,
+    missing,
+    stale
+  }
+}
+
+/**
+ * Get translation text (handles string or object with default/overrides)
+ * @param {string|Object} translation - Translation value
+ * @returns {string} The translation text
+ */
+function getTranslationText(translation) {
+  if (typeof translation === 'string') return translation
+  if (typeof translation === 'object' && translation !== null) {
+    if (translation.default) return translation.default
+  }
+  return String(translation)
+}
+
+/**
+ * Remove stale entries from a locale file
+ * @param {string} localesPath - Path to locales directory
+ * @param {string} locale - Locale code
+ * @param {string[]} staleHashes - Hashes to remove
+ * @returns {Promise<number>} Number of entries removed
+ */
+export async function cleanLocale(localesPath, locale, staleHashes) {
+  const localePath = join(localesPath, `${locale}.json`)
+
+  if (!existsSync(localePath)) {
+    return 0
+  }
+
+  const translations = JSON.parse(await readFile(localePath, 'utf-8'))
+
+  let removed = 0
+  for (const hash of staleHashes) {
+    if (hash in translations) {
+      delete translations[hash]
+      removed++
+    }
+  }
+
+  if (removed > 0) {
+    await writeFile(localePath, JSON.stringify(translations, null, 2))
+  }
+
+  return removed
+}
+
+/**
+ * Format audit results for console output
+ * @param {Object[]} results - Array of audit results from auditLocale
+ * @param {Object} options - Formatting options
+ * @param {boolean} [options.verbose=false] - Show stale entry details
+ * @returns {string} Formatted report
+ */
+export function formatAuditReport(results, options = {}) {
+  const { verbose = false } = options
+  const lines = []
+
+  for (const result of results) {
+    lines.push(`\n${result.locale}:`)
+
+    if (!result.exists) {
+      lines.push(`  No translation file`)
+      lines.push(`  ${result.total} strings need translation`)
+      continue
+    }
+
+    const coverage = result.total > 0
+      ? Math.round((result.valid.length / result.total) * 100)
+      : 100
+
+    lines.push(`  Valid:   ${result.valid.length} (${coverage}%)`)
+    lines.push(`  Missing: ${result.missing.length}`)
+    lines.push(`  Stale:   ${result.stale.length}`)
+
+    if (verbose && result.stale.length > 0) {
+      lines.push(`\n  Stale entries:`)
+      for (const entry of result.stale.slice(0, 10)) {
+        const preview = truncate(entry.translation, 40)
+        lines.push(`    - ${entry.hash}: "${preview}"`)
+      }
+      if (result.stale.length > 10) {
+        lines.push(`    ... and ${result.stale.length - 10} more`)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Truncate string for display
+ * @param {string} str - String to truncate
+ * @param {number} maxLen - Maximum length
+ * @returns {string} Truncated string
+ */
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str
+  return str.slice(0, maxLen - 3) + '...'
+}

package/src/i18n/collections.js

@@ -0,0 +1,420 @@
+/**
+ * Collection i18n support
+ *
+ * Extract translatable strings from collection items and merge translations.
+ * Collections are separate from page content (stored in public/data/*.json).
+ */
+
+import { readFile, writeFile, readdir, mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { computeHash } from './hash.js'
+
+export const COLLECTIONS_DIR = 'collections'
+
+/**
+ * Extract translatable content from all collections
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} Manifest with translation units
+ */
+export async function extractCollectionContent(siteRoot, options = {}) {
+  const dataDir = join(siteRoot, 'public', 'data')
+
+  if (!existsSync(dataDir)) {
+    return { version: '1.0', units: {} }
+  }
+
+  const units = {}
+
+  let files
+  try {
+    files = await readdir(dataDir)
+  } catch {
+    return { version: '1.0', units: {} }
+  }
+
+  const jsonFiles = files.filter(f => f.endsWith('.json'))
+
+  for (const file of jsonFiles) {
+    const collectionName = file.replace('.json', '')
+    const filePath = join(dataDir, file)
+
+    try {
+      const raw = await readFile(filePath, 'utf-8')
+      const items = JSON.parse(raw)
+
+      if (!Array.isArray(items)) continue
+
+      for (const item of items) {
+        extractFromItem(item, collectionName, units)
+      }
+    } catch (err) {
+      // Skip files that can't be parsed
+      console.warn(`[i18n] Skipping collection ${file}: ${err.message}`)
+    }
+  }
+
+  return {
+    version: '1.0',
+    extracted: new Date().toISOString(),
+    units
+  }
+}
+
+/**
+ * Extract translatable strings from a collection item
+ * @param {Object} item - Collection item
+ * @param {string} collectionName - Name of the collection
+ * @param {Object} units - Units accumulator
+ */
+function extractFromItem(item, collectionName, units) {
+  const slug = item.slug || 'unknown'
+  const context = { collection: collectionName, item: slug }
+
+  // Extract string fields from frontmatter
+  // Common translatable fields
+  const translatableFields = ['title', 'description', 'excerpt', 'summary', 'subtitle']
+
+  for (const field of translatableFields) {
+    if (item[field] && typeof item[field] === 'string' && item[field].trim()) {
+      addUnit(units, item[field], field, context)
+    }
+  }
+
+  // Extract from tags/categories if they're strings
+  if (Array.isArray(item.tags)) {
+    item.tags.forEach((tag, i) => {
+      if (typeof tag === 'string' && tag.trim()) {
+        addUnit(units, tag, `tag.${i}`, context)
+      }
+    })
+  }
+
+  if (Array.isArray(item.categories)) {
+    item.categories.forEach((cat, i) => {
+      if (typeof cat === 'string' && cat.trim()) {
+        addUnit(units, cat, `category.${i}`, context)
+      }
+    })
+  }
+
+  // Extract from ProseMirror content body
+  if (item.content?.type === 'doc') {
+    extractFromProseMirrorDoc(item.content, context, units)
+  }
+}
+
+/**
+ * Extract from ProseMirror document
+ * @param {Object} doc - ProseMirror document
+ * @param {Object} context - Context for the item
+ * @param {Object} units - Units accumulator
+ */
+function extractFromProseMirrorDoc(doc, context, units) {
+  if (!doc.content) return
+
+  let headingIndex = 0
+  let paragraphIndex = 0
+
+  for (const node of doc.content) {
+    if (node.type === 'heading') {
+      const text = extractTextFromNode(node)
+      if (text) {
+        addUnit(units, text, `content.heading.${headingIndex}`, context)
+        headingIndex++
+      }
+    } else if (node.type === 'paragraph') {
+      const text = extractTextFromNode(node)
+      if (text) {
+        addUnit(units, text, `content.paragraph.${paragraphIndex}`, context)
+        paragraphIndex++
+      }
+    } else if (node.type === 'bulletList' || node.type === 'orderedList') {
+      extractFromList(node, context, units)
+    }
+  }
+}
+
+/**
+ * Extract from list nodes
+ */
+function extractFromList(listNode, context, units) {
+  if (!listNode.content) return
+
+  listNode.content.forEach((listItem, index) => {
+    if (listItem.type === 'listItem' && listItem.content) {
+      for (const child of listItem.content) {
+        if (child.type === 'paragraph') {
+          const text = extractTextFromNode(child)
+          if (text) {
+            addUnit(units, text, `content.list.${index}`, context)
+          }
+        }
+      }
+    }
+  })
+}
+
+/**
+ * Extract text content from a node
+ */
+function extractTextFromNode(node) {
+  if (!node.content) return ''
+  return node.content
+    .filter(n => n.type === 'text')
+    .map(n => n.text || '')
+    .join('')
+    .trim()
+}
+
+/**
+ * Add a translation unit to the accumulator
+ */
+function addUnit(units, source, field, context) {
+  if (!source || source.length === 0) return
+
+  const hash = computeHash(source)
+
+  if (units[hash]) {
+    const existingContexts = units[hash].contexts
+    const contextKey = `${context.collection}:${context.item}`
+    const exists = existingContexts.some(
+      c => `${c.collection}:${c.item}` === contextKey
+    )
+    if (!exists) {
+      existingContexts.push({ ...context })
+    }
+  } else {
+    units[hash] = {
+      source,
+      field,
+      contexts: [{ ...context }]
+    }
+  }
+}
+
+/**
+ * Merge translations into collection data and write locale-specific files
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} Map of locale to output paths
+ */
+export async function buildLocalizedCollections(siteRoot, options = {}) {
+  const {
+    locales = [],
+    outputDir = join(siteRoot, 'dist'),
+    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR)
+  } = options
+
+  const dataDir = join(siteRoot, 'public', 'data')
+
+  if (!existsSync(dataDir)) {
+    return {}
+  }
+
+  let files
+  try {
+    files = await readdir(dataDir)
+  } catch {
+    return {}
+  }
+
+  const jsonFiles = files.filter(f => f.endsWith('.json'))
+
+  if (jsonFiles.length === 0) {
+    return {}
+  }
+
+  const outputs = {}
+
+  for (const locale of locales) {
+    // Load translations for this locale
+    const localePath = join(collectionsLocalesDir, `${locale}.json`)
+    let translations = {}
+    if (existsSync(localePath)) {
+      try {
+        translations = JSON.parse(await readFile(localePath, 'utf-8'))
+      } catch {
+        // Use empty translations if file can't be parsed
+      }
+    }
+
+    // Create locale data directory
+    const localeDataDir = join(outputDir, locale, 'data')
+    await mkdir(localeDataDir, { recursive: true })
+
+    outputs[locale] = {}
+
+    for (const file of jsonFiles) {
+      const collectionName = file.replace('.json', '')
+      const sourcePath = join(dataDir, file)
+
+      try {
+        const raw = await readFile(sourcePath, 'utf-8')
+        const items = JSON.parse(raw)
+
+        if (!Array.isArray(items)) {
+          // Copy as-is if not an array
+          const destPath = join(localeDataDir, file)
+          await writeFile(destPath, raw)
+          outputs[locale][collectionName] = destPath
+          continue
+        }
+
+        // Translate each item
+        const translatedItems = items.map(item =>
+          translateItem(item, collectionName, translations)
+        )
+
+        const destPath = join(localeDataDir, file)
+        await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
+        outputs[locale][collectionName] = destPath
+      } catch (err) {
+        console.warn(`[i18n] Failed to translate collection ${file}: ${err.message}`)
+      }
+    }
+  }
+
+  return outputs
+}
+
+/**
+ * Apply translations to a collection item
+ */
+function translateItem(item, collectionName, translations) {
+  const translated = { ...item }
+  const slug = item.slug || 'unknown'
+  const context = { collection: collectionName, item: slug }
+
+  // Translate frontmatter fields
+  const translatableFields = ['title', 'description', 'excerpt', 'summary', 'subtitle']
+
+  for (const field of translatableFields) {
+    if (translated[field] && typeof translated[field] === 'string') {
+      translated[field] = lookupTranslation(
+        translated[field],
+        context,
+        translations
+      )
+    }
+  }
+
+  // Translate tags
+  if (Array.isArray(translated.tags)) {
+    translated.tags = translated.tags.map(tag => {
+      if (typeof tag === 'string') {
+        return lookupTranslation(tag, context, translations)
+      }
+      return tag
+    })
+  }
+
+  // Translate categories
+  if (Array.isArray(translated.categories)) {
+    translated.categories = translated.categories.map(cat => {
+      if (typeof cat === 'string') {
+        return lookupTranslation(cat, context, translations)
+      }
+      return cat
+    })
+  }
+
+  // Translate ProseMirror content
+  if (translated.content?.type === 'doc') {
+    translated.content = translateProseMirrorDoc(
+      translated.content,
+      context,
+      translations
+    )
+  }
+
+  return translated
+}
+
+/**
+ * Translate a ProseMirror document
+ */
+function translateProseMirrorDoc(doc, context, translations) {
+  if (!doc.content) return doc
+
+  const translated = { ...doc, content: [] }
+
+  for (const node of doc.content) {
+    translated.content.push(translateNode(node, context, translations))
+  }
+
+  return translated
+}
+
+/**
+ * Recursively translate a node
+ */
+function translateNode(node, context, translations) {
+  if (!node.content) return node
+
+  const translated = { ...node, content: [] }
+
+  for (const child of node.content) {
+    if (child.type === 'text' && child.text) {
+      const translatedText = lookupTranslation(child.text, context, translations)
+      translated.content.push({ ...child, text: translatedText })
+    } else {
+      translated.content.push(translateNode(child, context, translations))
+    }
+  }
+
+  return translated
+}
+
+/**
+ * Look up translation for a piece of text
+ */
+function lookupTranslation(source, context, translations) {
+  const trimmed = source.trim()
+  if (!trimmed) return source
+
+  const hash = computeHash(trimmed)
+  const translation = translations[hash]
+
+  if (!translation) return source
+
+  if (typeof translation === 'string') {
+    // Preserve leading/trailing whitespace from original
+    const leadingSpace = source.match(/^\s*/)[0]
+    const trailingSpace = source.match(/\s*$/)[0]
+    return leadingSpace + translation + trailingSpace
+  }
+
+  if (typeof translation === 'object' && translation !== null) {
+    const contextKey = `${context.collection}:${context.item}`
+    if (translation.overrides?.[contextKey]) {
+      return translation.overrides[contextKey]
+    }
+    if (translation.default) {
+      return translation.default
+    }
+  }
+
+  return source
+}
+
+/**
+ * Get available collection locales
+ * @param {string} localesPath - Path to locales directory
+ * @returns {Promise<string[]>} Array of locale codes
+ */
+export async function getCollectionLocales(localesPath) {
+  const collectionsDir = join(localesPath, COLLECTIONS_DIR)
+  if (!existsSync(collectionsDir)) return []
+
+  try {
+    const files = await readdir(collectionsDir)
+    return files
+      .filter(f => f.endsWith('.json') && f !== 'manifest.json')
+      .map(f => f.replace('.json', ''))
+      .sort()
+  } catch {
+    return []
+  }
+}

package/src/i18n/index.js

@@ -15,6 +15,13 @@ import { computeHash, normalizeText } from './hash.js'
 import { extractTranslatableContent } from './extract.js'
 import { syncManifests, formatSyncReport } from './sync.js'
 import { mergeTranslations, generateAllLocales } from './merge.js'
+import { auditLocale, cleanLocale, formatAuditReport } from './audit.js'
+import {
+  extractCollectionContent,
+  buildLocalizedCollections,
+  getCollectionLocales,
+  COLLECTIONS_DIR
+} from './collections.js'
 import { generateSearchIndex, isSearchEnabled } from '../search/index.js'
 
 export {
@@ -29,6 +36,17 @@ export {
   mergeTranslations,
   generateAllLocales,
 
+  // Audit functions
+  auditLocale,
+  cleanLocale,
+  formatAuditReport,
+
+  // Collection functions
+  extractCollectionContent,
+  buildLocalizedCollections,
+  getCollectionLocales,
+  COLLECTIONS_DIR,
+
   // Locale resolution
   getAvailableLocales,
   resolveLocales
@@ -149,6 +167,46 @@ export async function extractManifest(siteRoot, options = {}) {
   return { manifest, report }
 }
 
+/**
+ * Extract collection manifest from collection data and write to file
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} { manifest, report }
+ */
+export async function extractCollectionManifest(siteRoot, options = {}) {
+  const { localesDir = DEFAULTS.localesDir } = options
+
+  // Extract translatable content from collections
+  const manifest = await extractCollectionContent(siteRoot)
+
+  // Ensure collections locales directory exists
+  const collectionsDir = join(siteRoot, localesDir, COLLECTIONS_DIR)
+  if (!existsSync(collectionsDir)) {
+    await mkdir(collectionsDir, { recursive: true })
+  }
+
+  const manifestPath = join(collectionsDir, 'manifest.json')
+
+  // Load previous manifest for comparison
+  let previousManifest = null
+  if (existsSync(manifestPath)) {
+    try {
+      const prevRaw = await readFile(manifestPath, 'utf-8')
+      previousManifest = JSON.parse(prevRaw)
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  // Generate sync report
+  const report = syncManifests(previousManifest, manifest)
+
+  // Write new manifest
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+
+  return { manifest, report }
+}
+
 /**
  * Get translation status for all configured locales
  * @param {string} siteRoot - Site root directory

package/src/prerender.js

@@ -9,7 +9,7 @@
  */
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
@@ -381,6 +381,62 @@ function createPageElement(page, website) {
   )
 }
 
+/**
+ * Discover all locale content files in the dist directory
+ * Returns an array of { locale, contentPath, htmlPath, isDefault }
+ *
+ * @param {string} distDir - Path to dist directory
+ * @param {Object} defaultContent - Default site content (to get default locale)
+ * @returns {Array} Locale configurations
+ */
+async function discoverLocaleContents(distDir, defaultContent) {
+  const locales = []
+  const defaultLocale = defaultContent.config?.defaultLanguage || 'en'
+
+  // Add the default locale (root level)
+  locales.push({
+    locale: defaultLocale,
+    contentPath: join(distDir, 'site-content.json'),
+    htmlPath: join(distDir, 'index.html'),
+    isDefault: true,
+    routePrefix: ''
+  })
+
+  // Check for locale subdirectories with site-content.json
+  try {
+    const entries = readdirSync(distDir)
+    for (const entry of entries) {
+      const entryPath = join(distDir, entry)
+      // Skip if not a directory
+      if (!statSync(entryPath).isDirectory()) continue
+
+      // Check if this looks like a locale code (2-3 letter code)
+      if (!/^[a-z]{2,3}(-[A-Z]{2})?$/.test(entry)) continue
+
+      // Check if it has a site-content.json
+      const localeContentPath = join(entryPath, 'site-content.json')
+      const localeHtmlPath = join(entryPath, 'index.html')
+
+      if (existsSync(localeContentPath)) {
+        locales.push({
+          locale: entry,
+          contentPath: localeContentPath,
+          htmlPath: localeHtmlPath,
+          isDefault: false,
+          routePrefix: `/${entry}`
+        })
+      }
+    }
+  } catch (err) {
+    // Ignore errors reading directory
+    if (process.env.DEBUG) {
+      console.error('Error discovering locale contents:', err.message)
+    }
+  }
+
+  return locales
+}
+
 /**
  * Pre-render all pages in a built site to static HTML
  *
@@ -407,33 +463,21 @@ export async function prerenderSite(siteDir, options = {}) {
   onProgress('Loading dependencies...')
   await loadDependencies(siteDir)
 
-  // Load site content
+  // Load default site content
   onProgress('Loading site content...')
   const contentPath = join(distDir, 'site-content.json')
   if (!existsSync(contentPath)) {
     throw new Error(`site-content.json not found at: ${contentPath}`)
   }
-  const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
-
-  // Execute data fetches (site, page, section levels)
-  onProgress('Executing data fetches...')
-  const { siteCascadedData, pageFetchedData } = await executeAllFetches(siteContent, siteDir, onProgress)
-
-  // Expand dynamic pages (e.g., /blog/:slug → /blog/post-1, /blog/post-2)
-  if (siteContent.pages?.some(p => p.isDynamic)) {
-    onProgress('Expanding dynamic routes...')
-    siteContent.pages = expandDynamicPages(siteContent.pages, pageFetchedData, onProgress)
-  }
+  const defaultSiteContent = JSON.parse(await readFile(contentPath, 'utf8'))
 
-  // Load the HTML shell
-  onProgress('Loading HTML shell...')
-  const shellPath = join(distDir, 'index.html')
-  if (!existsSync(shellPath)) {
-    throw new Error(`index.html not found at: ${shellPath}`)
+  // Discover all locale content files
+  const localeConfigs = await discoverLocaleContents(distDir, defaultSiteContent)
+  if (localeConfigs.length > 1) {
+    onProgress(`Found ${localeConfigs.length} locales: ${localeConfigs.map(l => l.locale).join(', ')}`)
   }
-  const htmlShell = await readFile(shellPath, 'utf8')
 
-  // Load the foundation module
+  // Load the foundation module (shared across all locales)
   onProgress('Loading foundation...')
   const foundationPath = join(foundationDir, 'dist', 'foundation.js')
   if (!existsSync(foundationPath)) {
@@ -442,58 +486,87 @@ export async function prerenderSite(siteDir, options = {}) {
   const foundationUrl = pathToFileURL(foundationPath).href
   const foundation = await import(foundationUrl)
 
-  // Initialize the Uniweb runtime (this sets globalThis.uniweb)
-  onProgress('Initializing runtime...')
-  const uniweb = createUniweb(siteContent)
-  uniweb.setFoundation(foundation)
+  // Pre-render each locale
+  const renderedFiles = []
 
-  // Set foundation capabilities (Layout, props, etc.)
-  if (foundation.capabilities) {
-    uniweb.setFoundationConfig(foundation.capabilities)
-  }
+  for (const localeConfig of localeConfigs) {
+    const { locale, contentPath: localeContentPath, htmlPath, isDefault, routePrefix } = localeConfig
 
-  // Pre-render each page
-  const renderedFiles = []
-  const pages = uniweb.activeWebsite.pages
-  const website = uniweb.activeWebsite
+    onProgress(`\nRendering ${isDefault ? 'default' : locale} locale...`)
 
-  for (const page of pages) {
-    // Each page has a single canonical route
-    // Index pages already have their parent route as their canonical route
-    onProgress(`Rendering ${page.route}...`)
-
-    // Set this as the active page
-    uniweb.activeWebsite.setActivePage(page.route)
-
-    // Create the page element using inline SSR rendering
-    // (uses React from prerender's scope to avoid module resolution issues)
-    const element = createPageElement(page, website)
-
-    // Render to HTML string
-    let renderedContent
-    try {
-      renderedContent = renderToString(element)
-    } catch (err) {
-      console.warn(`Warning: Failed to render ${page.route}: ${err.message}`)
-      if (process.env.DEBUG) {
-        console.error(err.stack)
-      }
-      continue
+    // Load locale-specific content
+    const siteContent = JSON.parse(await readFile(localeContentPath, 'utf8'))
+
+    // Set the active locale in the content
+    siteContent.config = siteContent.config || {}
+    siteContent.config.activeLocale = locale
+
+    // Execute data fetches (site, page, section levels)
+    onProgress('Executing data fetches...')
+    const { siteCascadedData, pageFetchedData } = await executeAllFetches(siteContent, siteDir, onProgress)
+
+    // Expand dynamic pages (e.g., /blog/:slug → /blog/post-1, /blog/post-2)
+    if (siteContent.pages?.some(p => p.isDynamic)) {
+      onProgress('Expanding dynamic routes...')
+      siteContent.pages = expandDynamicPages(siteContent.pages, pageFetchedData, onProgress)
+    }
+
+    // Load the HTML shell for this locale
+    const shellPath = existsSync(htmlPath) ? htmlPath : join(distDir, 'index.html')
+    const htmlShell = await readFile(shellPath, 'utf8')
+
+    // Initialize the Uniweb runtime for this locale
+    onProgress('Initializing runtime...')
+    const uniweb = createUniweb(siteContent)
+    uniweb.setFoundation(foundation)
+
+    // Set foundation capabilities (Layout, props, etc.)
+    if (foundation.capabilities) {
+      uniweb.setFoundationConfig(foundation.capabilities)
     }
 
-    // Inject into shell
-    const html = injectContent(htmlShell, renderedContent, page, siteContent)
+    // Pre-render each page
+    const pages = uniweb.activeWebsite.pages
+    const website = uniweb.activeWebsite
 
-    // Output to the canonical route
-    const outputPath = getOutputPath(distDir, page.route)
-    await mkdir(dirname(outputPath), { recursive: true })
-    await writeFile(outputPath, html)
+    for (const page of pages) {
+      // Build the output route with locale prefix
+      const outputRoute = routePrefix + page.route
 
-    renderedFiles.push(outputPath)
-    onProgress(`  → ${outputPath.replace(distDir, 'dist')}`)
+      onProgress(`Rendering ${outputRoute}...`)
+
+      // Set this as the active page
+      uniweb.activeWebsite.setActivePage(page.route)
+
+      // Create the page element using inline SSR rendering
+      const element = createPageElement(page, website)
+
+      // Render to HTML string
+      let renderedContent
+      try {
+        renderedContent = renderToString(element)
+      } catch (err) {
+        console.warn(`Warning: Failed to render ${outputRoute}: ${err.message}`)
+        if (process.env.DEBUG) {
+          console.error(err.stack)
+        }
+        continue
+      }
+
+      // Inject into shell
+      const html = injectContent(htmlShell, renderedContent, page, siteContent)
+
+      // Output to the locale-prefixed route
+      const outputPath = getOutputPath(distDir, outputRoute)
+      await mkdir(dirname(outputPath), { recursive: true })
+      await writeFile(outputPath, html)
+
+      renderedFiles.push(outputPath)
+      onProgress(`  → ${outputPath.replace(distDir, 'dist')}`)
+    }
   }
 
-  onProgress(`Pre-rendered ${renderedFiles.length} pages`)
+  onProgress(`\nPre-rendered ${renderedFiles.length} pages across ${localeConfigs.length} locale(s)`)
 
   return {
     pages: renderedFiles.length,

package/src/site/config.js

@@ -119,6 +119,7 @@ export function readSiteConfig(siteRoot) {
  * @param {Object} [options.assets] - Asset processing configuration
  * @param {Object} [options.search] - Search index configuration
  * @param {boolean} [options.tailwind] - Include Tailwind CSS v4 Vite plugin (default: true)
+ * @param {string} [options.base] - Base public path for deployment (e.g., '/demos/mysite/')
  * @returns {Promise<Object>} Vite configuration
  */
 export async function defineSiteConfig(options = {}) {
@@ -131,6 +132,7 @@ export async function defineSiteConfig(options = {}) {
     assets = {},
     search = {},
     tailwind = true,
+    base: baseOption,
     ...restOptions
   } = options
 
@@ -140,6 +142,11 @@ export async function defineSiteConfig(options = {}) {
   // Read site.yml
   const siteConfig = readSiteConfig(siteRoot)
 
+  // Determine base path for deployment (priority: option > env > site.yml)
+  // Ensures trailing slash for Vite compatibility
+  const rawBase = baseOption || process.env.UNIWEB_BASE || siteConfig.base
+  const base = rawBase ? (rawBase.endsWith('/') ? rawBase : `${rawBase}/`) : undefined
+
   // Detect foundation type
   const foundationInfo = detectFoundationType(siteConfig.foundation, siteRoot)
 
@@ -269,6 +276,10 @@ export async function defineSiteConfig(options = {}) {
   }
 
   return {
+    // Base public path for deployment (e.g., '/demos/mysite/')
+    // Vite uses this to prefix all asset URLs and sets import.meta.env.BASE_URL
+    ...(base && { base }),
+
     plugins,
 
     define: {

package/src/theme/processor.js

@@ -29,6 +29,37 @@ const DEFAULT_FONTS = {
   mono: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace',
 }
 
+/**
+ * Default code block theme configuration
+ * Uses Shiki CSS variable names for compatibility
+ * These values are NOT converted to CSS here - the kit's Code component
+ * injects them at runtime only when code blocks are used (tree-shaking)
+ */
+const DEFAULT_CODE_THEME = {
+  // Background and foreground
+  background: '#1e1e2e',      // Dark editor background
+  foreground: '#cdd6f4',      // Default text color
+
+  // Syntax highlighting colors (Shiki token variables)
+  keyword: '#cba6f7',         // Purple - keywords (if, else, function)
+  string: '#a6e3a1',          // Green - strings
+  number: '#fab387',          // Orange - numbers
+  comment: '#6c7086',         // Gray - comments
+  function: '#89b4fa',        // Blue - function names
+  variable: '#f5e0dc',        // Light pink - variables
+  operator: '#89dceb',        // Cyan - operators
+  punctuation: '#9399b2',     // Gray - punctuation
+  type: '#f9e2af',            // Yellow - types
+  constant: '#f38ba8',        // Red - constants
+  property: '#94e2d5',        // Teal - properties
+  tag: '#89b4fa',             // Blue - HTML/JSX tags
+  attribute: '#f9e2af',       // Yellow - attributes
+
+  // UI elements
+  lineNumber: '#6c7086',      // Line number color
+  selection: '#45475a',       // Selection background
+}
+
 /**
  * Validate color configuration
  *
@@ -158,6 +189,35 @@ function validateAppearance(appearance) {
   return { valid: errors.length === 0, errors }
 }
 
+/**
+ * Validate code block theme configuration
+ *
+ * @param {Object} code - Code theme configuration
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateCodeTheme(code) {
+  const errors = []
+
+  if (!code || typeof code !== 'object') {
+    return { valid: true, errors } // No code config is valid (use defaults)
+  }
+
+  // Validate color values
+  for (const [name, value] of Object.entries(code)) {
+    if (typeof value !== 'string') {
+      errors.push(`code.${name} must be a string, got ${typeof value}`)
+      continue
+    }
+
+    // Basic color format check (hex, rgb, hsl, or color name)
+    if (!isValidColor(value)) {
+      errors.push(`code.${name} has invalid color value: ${value}`)
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
 /**
  * Validate foundation variables configuration
  *
@@ -203,11 +263,13 @@ export function validateThemeConfig(config) {
   const contextValidation = validateContexts(config.contexts)
   const fontValidation = validateFonts(config.fonts)
   const appearanceValidation = validateAppearance(config.appearance)
+  const codeValidation = validateCodeTheme(config.code)
 
   allErrors.push(...colorValidation.errors)
   allErrors.push(...contextValidation.errors)
   allErrors.push(...fontValidation.errors)
   allErrors.push(...appearanceValidation.errors)
+  allErrors.push(...codeValidation.errors)
 
   return {
     valid: allErrors.length === 0,
@@ -352,6 +414,14 @@ export function processTheme(rawConfig = {}, options = {}) {
     warnings.push(...foundationValidation.errors)
   }
 
+  // Process code block theme
+  // These values are stored for runtime injection by kit's Code component
+  // (not converted to CSS here - enables tree-shaking when code blocks aren't used)
+  const code = {
+    ...DEFAULT_CODE_THEME,
+    ...(rawConfig.code || {}),
+  }
+
   const config = {
     colors,      // Raw colors for CSS generator
     palettes,    // Generated palettes for Theme class
@@ -359,6 +429,7 @@ export function processTheme(rawConfig = {}, options = {}) {
     fonts,
     appearance,
     foundationVars: mergedFoundationVars,
+    code,        // Code block theme for runtime injection
   }
 
   return { config, errors, warnings }