uniweb 0.3.7 → 0.4.0

package/README.md

@@ -6,8 +6,10 @@ Create well-structured Vite + React projects with file-based routing, localizati
 
 ## Quick Start
 
+> **Need pnpm?** Run `npm install -g pnpm` or see [pnpm installation](https://pnpm.io/installation).
+
 ```bash
-npx uniweb@latest create my-site --template marketing
+pnpm create uniweb my-site --template marketing
 cd my-site
 pnpm install
 pnpm dev
@@ -33,16 +35,16 @@ The `marketing` template includes real components (Hero, Features, Pricing, Test
 
 ```bash
 # Multilingual business site (English, Spanish, French)
-npx uniweb@latest create my-site --template international
+pnpm create uniweb my-site --template international
 
 # Academic site (researcher portfolios, lab pages)
-npx uniweb@latest create my-site --template academic
+pnpm create uniweb my-site --template academic
 
 # Documentation site
-npx uniweb@latest create my-site --template docs
+pnpm create uniweb my-site --template docs
 
 # Minimal starter (build from scratch)
-npx uniweb@latest create my-site
+pnpm create uniweb my-site
 ```
 
 Every project is a workspace with two packages:
@@ -111,7 +113,11 @@ Access the parsed data via `content.data`:
 ```jsx
 function TeamCard({ content }) {
   const member = content.data['team-member']
-  return <div>{member.name} — {member.role}</div>
+  return (
+    <div>
+      {member.name} — {member.role}
+    </div>
+  )
 }
 ```
 
@@ -245,14 +251,24 @@ Start with local files deployed anywhere. The same foundation works across all t
 
 ---
 
-## Installation
+## Create a Project
 
 ```bash
-# Use directly with npx (recommended)
-npx uniweb@latest <command>
+# pnpm (recommended)
+pnpm create uniweb my-site --template marketing
 
-# Or install globally
+# npm (use -- before options)
+npm create uniweb@latest my-site -- --template marketing
+
+# npx
+npx uniweb@latest create my-site --template marketing
+```
+
+Alternatively, install the CLI globally:
+
+```bash
 npm install -g uniweb
+uniweb create my-site --template marketing
 ```
 
 **Requirements:**
@@ -276,7 +292,7 @@ Or see the [official pnpm installation guide](https://pnpm.io/installation) for
 
 ### `create`
 
-Create a new Uniweb project.
+Create a new Uniweb project. See [Create a Project](#create-a-project) for usage examples.
 
 ```bash
 uniweb create [project-name] [options]
@@ -298,31 +314,6 @@ uniweb create [project-name] [options]
 | GitHub     | `github:user/repo`             | GitHub repositories             |
 | GitHub URL | `https://github.com/user/repo` | Full GitHub URLs                |
 
-**Examples:**
-
-```bash
-# Interactive prompts
-uniweb create
-
-# Create with specific name (defaults to single template)
-uniweb create my-project
-
-# Single project with site + foundation
-uniweb create my-project --template single
-
-# Multi-site/foundation monorepo
-uniweb create my-workspace --template multi
-
-# Official marketing template (landing pages, pricing, testimonials)
-uniweb create my-site --template marketing
-
-# From npm package
-uniweb create my-site --template @myorg/starter-template
-
-# From GitHub repository
-uniweb create my-site --template github:myorg/uniweb-template
-```
-
 ### `build`
 
 Build the current project.
@@ -425,7 +416,7 @@ Feature-rich templates with real components and sample content.
 ### Marketing
 
 ```bash
-uniweb create my-site --template marketing
+pnpm create uniweb my-site --template marketing
 ```
 
 **Includes:** Hero, Features, Pricing, Testimonials, CTA, FAQ, Stats, LogoCloud, Video, Gallery, Team
@@ -435,13 +426,13 @@ Perfect for product launches, SaaS websites, and business landing pages.
 **Tailwind v3 variant:**
 
 ```bash
-uniweb create my-site --template marketing --variant tailwind3
+pnpm create uniweb my-site --template marketing --variant tailwind3
 ```
 
 ### Academic
 
 ```bash
-uniweb create my-site --template academic
+pnpm create uniweb my-site --template academic
 ```
 
 **Includes:** ProfileHero, PublicationList, ResearchAreas, TeamGrid, Timeline, ContactCard, Navbar, Footer
@@ -451,7 +442,7 @@ Perfect for researcher portfolios, lab websites, and academic department sites.
 ### Docs
 
 ```bash
-uniweb create my-site --template docs
+pnpm create uniweb my-site --template docs
 ```
 
 **Includes:** Header, LeftPanel, DocSection, CodeBlock, Footer
@@ -461,7 +452,7 @@ Perfect for technical documentation, guides, and API references.
 ### International
 
 ```bash
-uniweb create my-site --template international
+pnpm create uniweb my-site --template international
 ```
 
 **Includes:** Hero, Features, Team, CTA, Header (with language switcher), Footer (with language links)
@@ -489,13 +480,13 @@ Use templates from npm or GitHub:
 
 ```bash
 # npm package
-uniweb create my-site --template @myorg/template-name
+pnpm create uniweb my-site --template @myorg/template-name
 
 # GitHub repository
-uniweb create my-site --template github:user/repo
+pnpm create uniweb my-site --template github:user/repo
 
 # GitHub with specific branch/tag
-uniweb create my-site --template github:user/repo#v1.0.0
+pnpm create uniweb my-site --template github:user/repo#v1.0.0
 ```
 
 ## Dependency Management
@@ -665,7 +656,7 @@ Set your homepage with `index:` in `site.yml`:
 
 ```yaml
 # site.yml
-index: home  # The page folder that becomes /
+index: home # The page folder that becomes /
 ```
 
 The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
@@ -685,8 +676,8 @@ Becomes:
 
 ```js
 content.items = [
-  { title: "First item", paragraphs: [], links: [], imgs: [] },
-  { title: "Second item", paragraphs: [], links: [], imgs: [] }
+  { title: 'First item', paragraphs: [], links: [], imgs: [] },
+  { title: 'Second item', paragraphs: [], links: [], imgs: [] },
 ]
 ```
 
@@ -708,7 +699,11 @@ Are accessible via `content.data`:
 ```jsx
 function TeamMember({ content }) {
   const member = content.data['team-member']
-  return <div>{member.name} - {member.role}</div>
+  return (
+    <div>
+      {member.name} - {member.role}
+    </div>
+  )
 }
 ```
 
@@ -718,12 +713,12 @@ The tag name (after the colon) becomes the key in `content.data`.
 
 In a Uniweb workspace, commands run differently at different levels:
 
-| Location | Command | What it does |
-|----------|---------|--------------|
-| Project root | `pnpm build` | Builds all packages (foundation + site) |
-| Project root | `pnpm dev` | Starts dev server for site |
-| `foundation/` | `uniweb build` | Builds just the foundation |
-| `site/` | `uniweb build` | Builds just the site |
+| Location      | Command        | What it does                            |
+| ------------- | -------------- | --------------------------------------- |
+| Project root  | `pnpm build`   | Builds all packages (foundation + site) |
+| Project root  | `pnpm dev`     | Starts dev server for site              |
+| `foundation/` | `uniweb build` | Builds just the foundation              |
+| `site/`       | `uniweb build` | Builds just the site                    |
 
 For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,9 +37,9 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.2.4",
+    "@uniweb/build": "0.3.0",
     "@uniweb/core": "0.2.3",
-    "@uniweb/kit": "0.2.3",
-    "@uniweb/runtime": "0.3.1"
+    "@uniweb/runtime": "0.4.0",
+    "@uniweb/kit": "0.3.0"
   }
 }

package/src/commands/build.js

@@ -407,6 +407,31 @@ async function buildSite(projectDir, options = {}) {
       for (const [locale, path] of Object.entries(outputs)) {
         log(`  ${colors.dim}dist/${locale}/site-content.json${colors.reset}`)
       }
+
+      // Translate collections if they exist
+      try {
+        const { buildLocalizedCollections } = await import('@uniweb/build/i18n')
+
+        const collectionOutputs = await buildLocalizedCollections(projectDir, {
+          locales: i18nConfig.locales,
+          outputDir: join(projectDir, 'dist'),
+          collectionsLocalesDir: join(projectDir, i18nConfig.localesDir, 'collections')
+        })
+
+        // Count collections translated
+        const collectionCount = Object.values(collectionOutputs).reduce(
+          (sum, localeOutputs) => sum + Object.keys(localeOutputs).length, 0
+        )
+
+        if (collectionCount > 0) {
+          success(`Translated collections for ${Object.keys(collectionOutputs).length} locale(s)`)
+        }
+      } catch (err) {
+        // Collection translation is optional, don't fail build
+        if (process.env.DEBUG) {
+          console.error('Collection translation:', err.message)
+        }
+      }
     } catch (err) {
       error(`i18n build failed: ${err.message}`)
       if (process.env.DEBUG) {

package/src/commands/i18n.js

@@ -105,6 +105,9 @@ export async function i18n(args) {
     case 'status':
       await runStatus(siteRoot, config, effectiveArgs)
       break
+    case 'audit':
+      await runAudit(siteRoot, config, effectiveArgs)
+      break
     default:
       error(`Unknown subcommand: ${effectiveSubcommand}`)
       showHelp()
@@ -205,45 +208,92 @@ async function loadSiteConfig(siteRoot) {
  */
 async function runExtract(siteRoot, config, args) {
   const verbose = args.includes('--verbose') || args.includes('-v')
+  const collectionsOnly = args.includes('--collections')
+  const withCollections = args.includes('--with-collections')
 
-  log(`\n${colors.cyan}Extracting translatable content...${colors.reset}\n`)
+  // Extract page content (unless --collections only)
+  if (!collectionsOnly) {
+    log(`\n${colors.cyan}Extracting translatable content...${colors.reset}\n`)
 
-  // Check if site has been built
-  const siteContentPath = join(siteRoot, 'dist', 'site-content.json')
-  if (!existsSync(siteContentPath)) {
-    error('Site content not found. Run "uniweb build" first.')
-    process.exit(1)
-  }
+    // Check if site has been built
+    const siteContentPath = join(siteRoot, 'dist', 'site-content.json')
+    if (!existsSync(siteContentPath)) {
+      error('Site content not found. Run "uniweb build" first.')
+      process.exit(1)
+    }
 
-  try {
-    // Dynamic import to avoid loading at CLI startup
-    const { extractManifest, formatSyncReport } = await import('@uniweb/build/i18n')
+    try {
+      // Dynamic import to avoid loading at CLI startup
+      const { extractManifest, formatSyncReport } = await import('@uniweb/build/i18n')
 
-    const { manifest, report } = await extractManifest(siteRoot, {
-      localesDir: config.localesDir,
-      siteContentPath,
-      verbose,
-    })
+      const { manifest, report } = await extractManifest(siteRoot, {
+        localesDir: config.localesDir,
+        siteContentPath,
+        verbose,
+      })
 
-    // Show results
-    const unitCount = Object.keys(manifest.units).length
-    success(`Extracted ${unitCount} translatable strings`)
+      // Show results
+      const unitCount = Object.keys(manifest.units).length
+      success(`Extracted ${unitCount} translatable strings`)
 
-    if (report) {
-      log('')
-      log(formatSyncReport(report))
+      if (report) {
+        log('')
+        log(formatSyncReport(report))
+      }
+
+      log(`\nManifest written to: ${colors.dim}${config.localesDir}/manifest.json${colors.reset}`)
+
+      if (config.locales.length === 0) {
+        log(`\n${colors.dim}No translation files found in ${config.localesDir}/.`)
+        log(`After translating, create locale files like ${config.localesDir}/es.json${colors.reset}`)
+      }
+    } catch (err) {
+      error(`Extraction failed: ${err.message}`)
+      if (verbose) console.error(err)
+      process.exit(1)
     }
+  }
 
-    log(`\nManifest written to: ${colors.dim}${config.localesDir}/manifest.json${colors.reset}`)
+  // Extract collection content (if --collections or --with-collections)
+  if (collectionsOnly || withCollections) {
+    log(`\n${colors.cyan}Extracting collection content...${colors.reset}\n`)
 
-    if (config.locales.length === 0) {
-      log(`\n${colors.dim}No translation files found in ${config.localesDir}/.`)
-      log(`After translating, create locale files like ${config.localesDir}/es.json${colors.reset}`)
+    // Check if collections exist
+    const dataDir = join(siteRoot, 'public', 'data')
+    if (!existsSync(dataDir)) {
+      if (collectionsOnly) {
+        error('No collections found. Create collection data in public/data/.')
+        process.exit(1)
+      }
+      log(`${colors.dim}No collections found in public/data/.${colors.reset}`)
+      return
+    }
+
+    try {
+      const { extractCollectionManifest, formatSyncReport } = await import('@uniweb/build/i18n')
+
+      const { manifest, report } = await extractCollectionManifest(siteRoot, {
+        localesDir: config.localesDir,
+      })
+
+      const unitCount = Object.keys(manifest.units).length
+      if (unitCount > 0) {
+        success(`Extracted ${unitCount} translatable strings from collections`)
+
+        if (report) {
+          log('')
+          log(formatSyncReport(report))
+        }
+
+        log(`\nManifest written to: ${colors.dim}${config.localesDir}/collections/manifest.json${colors.reset}`)
+      } else {
+        log(`${colors.dim}No translatable content found in collections.${colors.reset}`)
+      }
+    } catch (err) {
+      error(`Collection extraction failed: ${err.message}`)
+      if (verbose) console.error(err)
+      if (collectionsOnly) process.exit(1)
     }
-  } catch (err) {
-    error(`Extraction failed: ${err.message}`)
-    if (verbose) console.error(err)
-    process.exit(1)
   }
 }
 
@@ -301,19 +351,36 @@ async function runSync(siteRoot, config, args) {
  */
 async function runStatus(siteRoot, config, args) {
   const locale = args.find(a => !a.startsWith('-'))
-
-  log(`\n${colors.cyan}Translation Status${colors.reset}\n`)
+  const showMissing = args.includes('--missing')
+  const outputJson = args.includes('--json')
+  const byPage = args.includes('--by-page')
 
   // Check if manifest exists
-  const manifestPath = join(siteRoot, config.localesDir, 'manifest.json')
+  const localesPath = join(siteRoot, config.localesDir)
+  const manifestPath = join(localesPath, 'manifest.json')
   if (!existsSync(manifestPath)) {
     error('No manifest found. Run "uniweb i18n extract" first.')
     process.exit(1)
   }
 
+  // For --missing mode, use auditLocale which returns detailed missing info
+  if (showMissing) {
+    await runStatusMissing(siteRoot, config, locale, { outputJson, byPage })
+    return
+  }
+
+  // Standard status mode
+  if (!outputJson) {
+    log(`\n${colors.cyan}Translation Status${colors.reset}\n`)
+  }
+
   if (config.locales.length === 0) {
-    log(`${colors.dim}No translation files found in ${config.localesDir}/.`)
-    log(`Create locale files like ${config.localesDir}/es.json to add translations.${colors.reset}`)
+    if (outputJson) {
+      log(JSON.stringify({ error: 'No translation files found', locales: [] }, null, 2))
+    } else {
+      log(`${colors.dim}No translation files found in ${config.localesDir}/.`)
+      log(`Create locale files like ${config.localesDir}/es.json to add translations.${colors.reset}`)
+    }
     return
   }
 
@@ -327,13 +394,18 @@ async function runStatus(siteRoot, config, args) {
       locales: localesToCheck,
     })
 
+    if (outputJson) {
+      log(JSON.stringify(status, null, 2))
+      return
+    }
+
     log(formatTranslationStatus(status))
 
     // Show next steps if there are missing translations
     const hasMissing = Object.values(status.locales).some(l => l.missing > 0)
     if (hasMissing) {
       log(`\n${colors.dim}To translate missing strings, edit the locale files in ${config.localesDir}/`)
-      log(`Or use AI tools with the manifest.json as reference.${colors.reset}`)
+      log(`Or use: uniweb i18n status --missing --json > missing.json${colors.reset}`)
     }
   } catch (err) {
     error(`Status check failed: ${err.message}`)
@@ -341,6 +413,202 @@ async function runStatus(siteRoot, config, args) {
   }
 }
 
+/**
+ * Status --missing mode - show detailed missing strings
+ */
+async function runStatusMissing(siteRoot, config, locale, options = {}) {
+  const { outputJson = false, byPage = false } = options
+  const localesPath = join(siteRoot, config.localesDir)
+
+  if (config.locales.length === 0) {
+    if (outputJson) {
+      log(JSON.stringify({ error: 'No translation files found', missing: [] }, null, 2))
+    } else {
+      log(`${colors.dim}No translation files found in ${config.localesDir}/.${colors.reset}`)
+    }
+    return
+  }
+
+  try {
+    const { auditLocale } = await import('@uniweb/build/i18n')
+
+    const localesToCheck = locale ? [locale] : config.locales
+
+    // Collect missing strings from all requested locales
+    const allMissing = []
+    const byLocale = {}
+
+    for (const loc of localesToCheck) {
+      const result = await auditLocale(localesPath, loc)
+      byLocale[loc] = {
+        total: result.total,
+        translated: result.valid.length,
+        missing: result.missing.length,
+        coverage: result.total > 0
+          ? Math.round((result.valid.length / result.total) * 100)
+          : 100
+      }
+
+      // Add locale info to each missing entry
+      for (const entry of result.missing) {
+        allMissing.push({
+          locale: loc,
+          ...entry
+        })
+      }
+    }
+
+    // JSON output
+    if (outputJson) {
+      const output = {
+        locales: byLocale,
+        missing: allMissing
+      }
+      log(JSON.stringify(output, null, 2))
+      return
+    }
+
+    // Human-readable output
+    log(`\n${colors.cyan}Missing Translations${colors.reset}\n`)
+
+    // Show summary per locale
+    for (const [loc, info] of Object.entries(byLocale)) {
+      log(`${loc}: ${info.missing} missing (${info.coverage}% coverage)`)
+    }
+
+    if (allMissing.length === 0) {
+      log(`\n${colors.green}All strings are translated!${colors.reset}`)
+      return
+    }
+
+    log('')
+
+    // Group by page if requested
+    if (byPage) {
+      const grouped = groupByPage(allMissing)
+      for (const [page, entries] of Object.entries(grouped)) {
+        log(`${colors.bright}${page}${colors.reset}`)
+        for (const entry of entries) {
+          const preview = truncateString(entry.source, 50)
+          log(`  ${colors.dim}${entry.hash}${colors.reset} "${preview}"`)
+        }
+        log('')
+      }
+    } else {
+      // Flat list
+      for (const entry of allMissing.slice(0, 20)) {
+        const preview = truncateString(entry.source, 60)
+        const context = entry.contexts?.[0]
+        const location = context ? `${context.page}:${context.section}` : ''
+        log(`  ${colors.dim}${entry.hash}${colors.reset} "${preview}"`)
+        if (location) {
+          log(`    ${colors.dim}→ ${location}${colors.reset}`)
+        }
+      }
+
+      if (allMissing.length > 20) {
+        log(`\n  ${colors.dim}... and ${allMissing.length - 20} more${colors.reset}`)
+      }
+    }
+
+    log(`\n${colors.dim}Use --json to export for translation tools.${colors.reset}`)
+  } catch (err) {
+    error(`Status check failed: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Group missing entries by page
+ */
+function groupByPage(entries) {
+  const grouped = {}
+  for (const entry of entries) {
+    const page = entry.contexts?.[0]?.page || 'unknown'
+    if (!grouped[page]) grouped[page] = []
+    grouped[page].push(entry)
+  }
+  return grouped
+}
+
+/**
+ * Truncate string for display
+ */
+function truncateString(str, maxLen) {
+  if (str.length <= maxLen) return str
+  return str.slice(0, maxLen - 3) + '...'
+}
+
+/**
+ * Audit command - find stale and missing translations
+ */
+async function runAudit(siteRoot, config, args) {
+  const locale = args.find(a => !a.startsWith('-'))
+  const clean = args.includes('--clean')
+  const verbose = args.includes('--verbose') || args.includes('-v')
+
+  log(`\n${colors.cyan}Translation Audit${colors.reset}\n`)
+
+  // Check if manifest exists
+  const localesPath = join(siteRoot, config.localesDir)
+  const manifestPath = join(localesPath, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    error('No manifest found. Run "uniweb i18n extract" first.')
+    process.exit(1)
+  }
+
+  if (config.locales.length === 0) {
+    log(`${colors.dim}No translation files found in ${config.localesDir}/.`)
+    log(`Create locale files like ${config.localesDir}/es.json to add translations.${colors.reset}`)
+    return
+  }
+
+  try {
+    const { auditLocale, cleanLocale, formatAuditReport } = await import('@uniweb/build/i18n')
+
+    const localesToAudit = locale ? [locale] : config.locales
+    const results = []
+
+    for (const loc of localesToAudit) {
+      const result = await auditLocale(localesPath, loc)
+      results.push(result)
+    }
+
+    // Show report
+    log(formatAuditReport(results, { verbose }))
+
+    // Clean if requested
+    if (clean) {
+      log('')
+      let totalRemoved = 0
+
+      for (const result of results) {
+        if (result.stale.length > 0) {
+          const staleHashes = result.stale.map(s => s.hash)
+          const removed = await cleanLocale(localesPath, result.locale, staleHashes)
+          if (removed > 0) {
+            success(`Removed ${removed} stale entries from ${result.locale}.json`)
+            totalRemoved += removed
+          }
+        }
+      }
+
+      if (totalRemoved === 0) {
+        log(`${colors.dim}No stale entries to remove.${colors.reset}`)
+      }
+    } else {
+      // Suggest --clean if there are stale entries
+      const hasStale = results.some(r => r.stale.length > 0)
+      if (hasStale) {
+        log(`\n${colors.dim}Run with --clean to remove stale entries.${colors.reset}`)
+      }
+    }
+  } catch (err) {
+    error(`Audit failed: ${err.message}`)
+    process.exit(1)
+  }
+}
+
 /**
  * Show help for i18n commands
  */
@@ -358,11 +626,18 @@ ${colors.bright}Commands:${colors.reset}
   extract      Extract translatable strings to locales/manifest.json
   sync         Update manifest with content changes (detects moved/changed content)
   status       Show translation coverage per locale
+  audit        Find stale translations (no longer in manifest) and missing ones
 
 ${colors.bright}Options:${colors.reset}
   -t, --target <path>  Site directory (auto-detected if not specified)
   --verbose            Show detailed output
   --dry-run            (sync) Show changes without writing files
+  --clean              (audit) Remove stale entries from locale files
+  --missing            (status) List all missing strings instead of summary
+  --json               (status) Output as JSON for translation tools
+  --by-page            (status --missing) Group missing strings by page
+  --collections        (extract/status/audit) Process only collections
+  --with-collections   (extract/status/audit) Include collections with pages
 
 ${colors.bright}Configuration:${colors.reset}
   Optional site.yml settings:
@@ -390,10 +665,17 @@ ${colors.bright}File Structure:${colors.reset}
 ${colors.bright}Examples:${colors.reset}
   uniweb i18n extract              # Extract all translatable strings
   uniweb i18n extract --verbose    # Show extracted strings
+  uniweb i18n extract --with-collections  # Extract pages + collections
+  uniweb i18n extract --collections       # Extract collections only
   uniweb i18n sync                 # Update manifest after content changes
   uniweb i18n sync --dry-run       # Preview changes without writing
   uniweb i18n status               # Show coverage for all locales
   uniweb i18n status es            # Show coverage for Spanish only
+  uniweb i18n status --missing     # List all missing strings
+  uniweb i18n status es --missing --json  # Export missing for AI translation
+  uniweb i18n status --missing --by-page  # Group missing by page
+  uniweb i18n audit                # Find stale and missing translations
+  uniweb i18n audit --clean        # Remove stale entries
   uniweb i18n --target site        # Specify site directory explicitly
 
 ${colors.bright}Notes:${colors.reset}