@uniweb/build 0.1.4 → 0.1.6

package/src/i18n/index.js

@@ -0,0 +1,301 @@
+/**
+ * @uniweb/build i18n module
+ *
+ * Site content internationalization utilities.
+ *
+ * Usage:
+ *   import { extractManifest, syncManifest, mergeLocale } from '@uniweb/build/i18n'
+ */
+
+import { readFile, writeFile, mkdir, readdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join, dirname } from 'path'
+
+import { computeHash, normalizeText } from './hash.js'
+import { extractTranslatableContent } from './extract.js'
+import { syncManifests, formatSyncReport } from './sync.js'
+import { mergeTranslations, generateAllLocales } from './merge.js'
+
+export {
+  // Hash utilities
+  computeHash,
+  normalizeText,
+
+  // Core functions
+  extractTranslatableContent,
+  syncManifests,
+  formatSyncReport,
+  mergeTranslations,
+  generateAllLocales,
+
+  // Locale resolution
+  getAvailableLocales,
+  resolveLocales
+}
+
+/**
+ * Default paths
+ */
+const DEFAULTS = {
+  localesDir: 'locales',
+  manifestFile: 'manifest.json',
+  memoryFile: '_memory.json'
+}
+
+/**
+ * Reserved files in the locales directory (not locale translation files)
+ */
+const RESERVED_FILES = new Set(['manifest.json', '_memory.json'])
+
+/**
+ * Get available locales by scanning the locales directory for *.json files
+ * @param {string} localesPath - Path to locales directory
+ * @returns {Promise<string[]>} Array of locale codes found
+ */
+async function getAvailableLocales(localesPath) {
+  if (!existsSync(localesPath)) {
+    return []
+  }
+
+  try {
+    const files = await readdir(localesPath)
+    return files
+      .filter(f => f.endsWith('.json') && !RESERVED_FILES.has(f))
+      .map(f => f.replace('.json', ''))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Resolve locales configuration to actual locale list
+ *
+ * Handles:
+ * - undefined → all available locales (from locales/*.json)
+ * - '*' → explicitly all available locales
+ * - ['es', 'fr'] → only those specific locales
+ *
+ * @param {string[]|string|undefined} configLocales - Locales from config
+ * @param {string} localesPath - Path to locales directory
+ * @returns {Promise<string[]>} Resolved array of locale codes
+ */
+async function resolveLocales(configLocales, localesPath) {
+  // Explicit list of locales
+  if (Array.isArray(configLocales) && configLocales.length > 0) {
+    // Check for '*' in array (e.g., locales: ['*'])
+    if (configLocales.includes('*')) {
+      return getAvailableLocales(localesPath)
+    }
+    return configLocales
+  }
+
+  // String value '*' means all available
+  if (configLocales === '*') {
+    return getAvailableLocales(localesPath)
+  }
+
+  // undefined, null, or empty array → all available
+  return getAvailableLocales(localesPath)
+}
+
+/**
+ * Extract manifest from site content and write to file
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Object} { manifest, report }
+ */
+export async function extractManifest(siteRoot, options = {}) {
+  const {
+    localesDir = DEFAULTS.localesDir,
+    siteContentPath = join(siteRoot, 'dist', 'site-content.json'),
+    verbose = false
+  } = options
+
+  // Load site content
+  const siteContentRaw = await readFile(siteContentPath, 'utf-8')
+  const siteContent = JSON.parse(siteContentRaw)
+
+  // Extract translatable content
+  const manifest = extractTranslatableContent(siteContent)
+
+  // Ensure locales directory exists
+  const localesPath = join(siteRoot, localesDir)
+  if (!existsSync(localesPath)) {
+    await mkdir(localesPath, { recursive: true })
+  }
+
+  // Load previous manifest for comparison
+  const manifestPath = join(localesPath, DEFAULTS.manifestFile)
+  let previousManifest = null
+  if (existsSync(manifestPath)) {
+    const prevRaw = await readFile(manifestPath, 'utf-8')
+    previousManifest = JSON.parse(prevRaw)
+  }
+
+  // Generate sync report
+  const report = syncManifests(previousManifest, manifest)
+
+  // Write new manifest
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+
+  if (verbose) {
+    console.log(formatSyncReport(report))
+    console.log(`\nManifest written to: ${manifestPath}`)
+    console.log(`Total units: ${Object.keys(manifest.units).length}`)
+  }
+
+  return { manifest, report }
+}
+
+/**
+ * Get translation status for all configured locales
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Object} Status per locale
+ */
+export async function getTranslationStatus(siteRoot, options = {}) {
+  const {
+    localesDir = DEFAULTS.localesDir,
+    locales = []
+  } = options
+
+  const localesPath = join(siteRoot, localesDir)
+  const manifestPath = join(localesPath, DEFAULTS.manifestFile)
+
+  if (!existsSync(manifestPath)) {
+    throw new Error('Manifest not found. Run extract first.')
+  }
+
+  const manifestRaw = await readFile(manifestPath, 'utf-8')
+  const manifest = JSON.parse(manifestRaw)
+  const totalUnits = Object.keys(manifest.units).length
+
+  const status = {}
+
+  for (const locale of locales) {
+    const localePath = join(localesPath, `${locale}.json`)
+
+    if (!existsSync(localePath)) {
+      status[locale] = {
+        exists: false,
+        translated: 0,
+        missing: totalUnits,
+        coverage: 0
+      }
+      continue
+    }
+
+    const localeRaw = await readFile(localePath, 'utf-8')
+    const translations = JSON.parse(localeRaw)
+    const translatedHashes = new Set(Object.keys(translations))
+
+    let translated = 0
+    let missing = 0
+
+    for (const hash of Object.keys(manifest.units)) {
+      if (translatedHashes.has(hash)) {
+        translated++
+      } else {
+        missing++
+      }
+    }
+
+    status[locale] = {
+      exists: true,
+      translated,
+      missing,
+      coverage: totalUnits > 0 ? Math.round((translated / totalUnits) * 100) : 100
+    }
+  }
+
+  return {
+    totalUnits,
+    locales: status
+  }
+}
+
+/**
+ * Build translated site content for all locales
+ * @param {string} siteRoot - Site root directory
+ * @param {Object} options - Options
+ * @returns {Object} Map of locale to output path
+ */
+export async function buildLocalizedContent(siteRoot, options = {}) {
+  const {
+    localesDir = DEFAULTS.localesDir,
+    locales = [],
+    outputDir = join(siteRoot, 'dist'),
+    fallbackToSource = true
+  } = options
+
+  const localesPath = join(siteRoot, localesDir)
+
+  // Load source site content
+  const siteContentPath = join(outputDir, 'site-content.json')
+  const siteContentRaw = await readFile(siteContentPath, 'utf-8')
+  const siteContent = JSON.parse(siteContentRaw)
+
+  const outputs = {}
+
+  for (const locale of locales) {
+    const localePath = join(localesPath, `${locale}.json`)
+
+    // Load translations (or empty object if not exists)
+    let translations = {}
+    if (existsSync(localePath)) {
+      const localeRaw = await readFile(localePath, 'utf-8')
+      translations = JSON.parse(localeRaw)
+    }
+
+    // Merge translations
+    const translated = mergeTranslations(siteContent, translations, {
+      fallbackToSource
+    })
+
+    // Write to locale subdirectory
+    const localeOutputDir = join(outputDir, locale)
+    if (!existsSync(localeOutputDir)) {
+      await mkdir(localeOutputDir, { recursive: true })
+    }
+
+    const outputPath = join(localeOutputDir, 'site-content.json')
+    await writeFile(outputPath, JSON.stringify(translated, null, 2))
+
+    outputs[locale] = outputPath
+  }
+
+  return outputs
+}
+
+/**
+ * Format translation status for console output
+ * @param {Object} status - Status from getTranslationStatus
+ * @returns {string} Formatted status
+ */
+export function formatTranslationStatus(status) {
+  const lines = [`Translation status (${status.totalUnits} total strings):\n`]
+
+  for (const [locale, info] of Object.entries(status.locales)) {
+    if (!info.exists) {
+      lines.push(`  ${locale}: No translation file`)
+    } else {
+      const bar = createProgressBar(info.coverage, 20)
+      lines.push(`  ${locale}: ${bar} ${info.coverage}% (${info.translated}/${status.totalUnits})`)
+      if (info.missing > 0) {
+        lines.push(`       ${info.missing} strings missing`)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Create ASCII progress bar
+ */
+function createProgressBar(percent, width) {
+  const filled = Math.round((percent / 100) * width)
+  const empty = width - filled
+  return '[' + '█'.repeat(filled) + '░'.repeat(empty) + ']'
+}

package/src/i18n/merge.js

@@ -0,0 +1,192 @@
+/**
+ * Merge translations into site content
+ *
+ * Takes site-content.json and locale translations,
+ * produces translated site-content for each locale.
+ */
+
+import { computeHash } from './hash.js'
+
+/**
+ * Merge translations into site content for a specific locale
+ * @param {Object} siteContent - Original site-content.json
+ * @param {Object} translations - Locale translations (hash -> translation)
+ * @param {Object} options - Merge options
+ * @returns {Object} Translated site content
+ */
+export function mergeTranslations(siteContent, translations, options = {}) {
+  const { fallbackToSource = true } = options
+
+  // Deep clone to avoid mutating original
+  const translated = JSON.parse(JSON.stringify(siteContent))
+
+  for (const page of translated.pages || []) {
+    const pageRoute = page.route || '/'
+
+    // Translate page metadata
+    translatePageMeta(page, pageRoute, translations, fallbackToSource)
+
+    // Translate section content
+    for (const section of page.sections || []) {
+      translateSection(section, pageRoute, translations, fallbackToSource)
+    }
+  }
+
+  return translated
+}
+
+/**
+ * Translate page metadata (title, description, keywords, etc.)
+ */
+function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
+  const context = { page: pageRoute, section: '_meta' }
+
+  // Translate title
+  if (page.title && typeof page.title === 'string') {
+    page.title = lookupTranslation(page.title, context, translations, fallbackToSource)
+  }
+
+  // Translate description
+  if (page.description && typeof page.description === 'string') {
+    page.description = lookupTranslation(page.description, context, translations, fallbackToSource)
+  }
+
+  // Translate SEO fields
+  if (page.seo) {
+    if (page.seo.ogTitle && typeof page.seo.ogTitle === 'string') {
+      page.seo.ogTitle = lookupTranslation(page.seo.ogTitle, context, translations, fallbackToSource)
+    }
+    if (page.seo.ogDescription && typeof page.seo.ogDescription === 'string') {
+      page.seo.ogDescription = lookupTranslation(page.seo.ogDescription, context, translations, fallbackToSource)
+    }
+  }
+
+  // Translate keywords
+  if (page.keywords) {
+    if (Array.isArray(page.keywords)) {
+      page.keywords = page.keywords.map(keyword => {
+        if (keyword && typeof keyword === 'string') {
+          return lookupTranslation(keyword, context, translations, fallbackToSource)
+        }
+        return keyword
+      })
+    } else if (typeof page.keywords === 'string') {
+      page.keywords = lookupTranslation(page.keywords, context, translations, fallbackToSource)
+    }
+  }
+}
+
+/**
+ * Translate a section's content
+ */
+function translateSection(section, pageRoute, translations, fallbackToSource) {
+  const sectionId = section.id || 'unknown'
+  const context = { page: pageRoute, section: sectionId }
+
+  if (section.content?.type === 'doc') {
+    translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
+  }
+
+  // Recursively translate subsections
+  for (const subsection of section.subsections || []) {
+    translateSection(subsection, pageRoute, translations, fallbackToSource)
+  }
+}
+
+/**
+ * Translate text nodes in a ProseMirror document
+ */
+function translateProseMirrorDoc(doc, context, translations, fallbackToSource) {
+  if (!doc.content) return
+
+  for (const node of doc.content) {
+    translateNode(node, context, translations, fallbackToSource)
+  }
+}
+
+/**
+ * Recursively translate a node and its children
+ */
+function translateNode(node, context, translations, fallbackToSource) {
+  // Translate text content
+  if (node.content) {
+    for (const child of node.content) {
+      if (child.type === 'text' && child.text) {
+        const translated = lookupTranslation(
+          child.text,
+          context,
+          translations,
+          fallbackToSource
+        )
+        if (translated !== child.text) {
+          child.text = translated
+        }
+      } else {
+        // Recurse into child nodes
+        translateNode(child, context, translations, fallbackToSource)
+      }
+    }
+  }
+}
+
+/**
+ * Look up translation for a piece of text
+ * @param {string} source - Source text
+ * @param {Object} context - Current context (page, section)
+ * @param {Object} translations - Translation map
+ * @param {boolean} fallbackToSource - Return source if no translation
+ * @returns {string} Translated text or source
+ */
+function lookupTranslation(source, context, translations, fallbackToSource) {
+  const trimmed = source.trim()
+  if (!trimmed) return source
+
+  const hash = computeHash(trimmed)
+  const translation = translations[hash]
+
+  if (!translation) {
+    return fallbackToSource ? source : source
+  }
+
+  // Handle simple string translation
+  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
+  }
+
+  // Handle translation with overrides
+  if (typeof translation === 'object') {
+    const contextKey = `${context.page}:${context.section}`
+
+    // Check for context-specific override
+    if (translation.overrides?.[contextKey]) {
+      return translation.overrides[contextKey]
+    }
+
+    // Fall back to default
+    if (translation.default) {
+      return translation.default
+    }
+  }
+
+  return fallbackToSource ? source : source
+}
+
+/**
+ * Generate translated site content for all configured locales
+ * @param {Object} siteContent - Original site-content.json
+ * @param {Object} localeFiles - Map of locale code to translations
+ * @param {Object} options - Merge options
+ * @returns {Object} Map of locale code to translated content
+ */
+export function generateAllLocales(siteContent, localeFiles, options = {}) {
+  const results = {}
+
+  for (const [locale, translations] of Object.entries(localeFiles)) {
+    results[locale] = mergeTranslations(siteContent, translations, options)
+  }
+
+  return results
+}

package/src/i18n/sync.js

@@ -0,0 +1,174 @@
+/**
+ * Sync detection for i18n manifests
+ *
+ * Compares current extracted content with previous manifest
+ * to detect moved, changed, new, and removed content.
+ */
+
+/**
+ * Compare two manifests and generate a sync report
+ * @param {Object} previous - Previous manifest (or null if first run)
+ * @param {Object} current - Newly extracted manifest
+ * @returns {Object} Sync report with changes
+ */
+export function syncManifests(previous, current) {
+  const report = {
+    unchanged: [],
+    moved: [],
+    changed: [],
+    added: [],
+    removed: []
+  }
+
+  const previousUnits = previous?.units || {}
+  const currentUnits = current.units || {}
+
+  const previousHashes = new Set(Object.keys(previousUnits))
+  const currentHashes = new Set(Object.keys(currentUnits))
+
+  // Check each current unit
+  for (const hash of currentHashes) {
+    const currentUnit = currentUnits[hash]
+
+    if (previousHashes.has(hash)) {
+      // Hash exists in both - check if contexts changed
+      const prevUnit = previousUnits[hash]
+      const contextsChanged = !contextsEqual(prevUnit.contexts, currentUnit.contexts)
+
+      if (contextsChanged) {
+        report.moved.push({
+          hash,
+          source: currentUnit.source,
+          previousContexts: prevUnit.contexts,
+          currentContexts: currentUnit.contexts
+        })
+      } else {
+        report.unchanged.push({ hash, source: currentUnit.source })
+      }
+    } else {
+      // New hash - could be new content or changed content
+      // Check if any previous context now has this new hash
+      const matchingContext = findMatchingContext(currentUnit.contexts, previousUnits)
+
+      if (matchingContext) {
+        // Same context, different hash = content changed
+        report.changed.push({
+          hash,
+          previousHash: matchingContext.hash,
+          source: currentUnit.source,
+          previousSource: matchingContext.source,
+          contexts: currentUnit.contexts
+        })
+      } else {
+        // Completely new content
+        report.added.push({
+          hash,
+          source: currentUnit.source,
+          field: currentUnit.field,
+          contexts: currentUnit.contexts
+        })
+      }
+    }
+  }
+
+  // Check for removed content
+  for (const hash of previousHashes) {
+    if (!currentHashes.has(hash)) {
+      const prevUnit = previousUnits[hash]
+      // Only mark as removed if not detected as changed above
+      const wasChanged = report.changed.some(c => c.previousHash === hash)
+      if (!wasChanged) {
+        report.removed.push({
+          hash,
+          source: prevUnit.source,
+          contexts: prevUnit.contexts
+        })
+      }
+    }
+  }
+
+  return report
+}
+
+/**
+ * Check if two context arrays are equal
+ */
+function contextsEqual(contexts1, contexts2) {
+  if (contexts1.length !== contexts2.length) return false
+
+  const set1 = new Set(contexts1.map(c => `${c.page}:${c.section}`))
+  const set2 = new Set(contexts2.map(c => `${c.page}:${c.section}`))
+
+  if (set1.size !== set2.size) return false
+  for (const key of set1) {
+    if (!set2.has(key)) return false
+  }
+  return true
+}
+
+/**
+ * Find if any context in the current unit matches a context in previous units
+ * Returns the previous unit info if found
+ */
+function findMatchingContext(currentContexts, previousUnits) {
+  for (const context of currentContexts) {
+    const contextKey = `${context.page}:${context.section}`
+
+    for (const [hash, unit] of Object.entries(previousUnits)) {
+      const hasContext = unit.contexts.some(
+        c => `${c.page}:${c.section}` === contextKey
+      )
+      if (hasContext) {
+        return { hash, source: unit.source, contexts: unit.contexts }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Format sync report for console output
+ * @param {Object} report - Sync report from syncManifests
+ * @returns {string} Formatted report
+ */
+export function formatSyncReport(report) {
+  const lines = ['i18n sync results:']
+
+  if (report.unchanged.length > 0) {
+    lines.push(`  ✓ ${report.unchanged.length} strings unchanged`)
+  }
+
+  if (report.moved.length > 0) {
+    lines.push(`  ↻ ${report.moved.length} strings moved (contexts updated)`)
+  }
+
+  if (report.changed.length > 0) {
+    lines.push(`  ⚠ ${report.changed.length} strings changed (need re-translation)`)
+    for (const item of report.changed.slice(0, 5)) {
+      const prevPreview = truncate(item.previousSource, 30)
+      const currPreview = truncate(item.source, 30)
+      lines.push(`    - ${item.previousHash}: "${prevPreview}" → "${currPreview}"`)
+    }
+    if (report.changed.length > 5) {
+      lines.push(`    ... and ${report.changed.length - 5} more`)
+    }
+  }
+
+  if (report.added.length > 0) {
+    lines.push(`  + ${report.added.length} new strings`)
+  }
+
+  if (report.removed.length > 0) {
+    lines.push(`  - ${report.removed.length} strings removed`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Truncate string for display
+ */
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) return str
+  return str.slice(0, maxLength - 3) + '...'
+}

package/src/index.js

@@ -40,5 +40,11 @@ export {
   prerenderSite,
 } from './prerender.js'
 
+// Documentation generation
+export {
+  generateDocs,
+  generateDocsFromSchema,
+} from './docs.js'
+
 // Default export is the combined Vite plugin
 export { default } from './vite-foundation-plugin.js'