slicejs-web-framework 4.1.1 → 4.2.0

package/api/framework/server.js

@@ -15,8 +15,10 @@ import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import zlib from 'node:zlib';
 import {
+  buildTranslatorContext,
   injectHead,
   loadSeoManifest,
+  loadTranslatorDictionaries,
   matchPathPattern,
   normalizeOrigin,
   pickRouteEntry,
@@ -53,6 +55,54 @@ function readComponentPrefixes(projectRoot) {
   return [];
 }
 
+/** The `translator` block from the deployed config (`dist` wins in production). */
+function readTranslatorConfig(projectRoot, folderDeployed) {
+  for (const folder of [folderDeployed, 'src']) {
+    const file = path.join(projectRoot, folder, 'sliceConfig.json');
+    if (!fs.existsSync(file)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8')).translator || null;
+    } catch {
+      // unreadable config: SEO stays single-language, as before
+    }
+  }
+  return null;
+}
+
+/** The `router` block from the deployed config (`dist` wins in production). */
+function readRouterConfig(projectRoot, folderDeployed) {
+  for (const folder of [folderDeployed, 'src']) {
+    const file = path.join(projectRoot, folder, 'sliceConfig.json');
+    if (!fs.existsSync(file)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8')).router || {};
+    } catch {
+      // unreadable config: no title affixes, as before
+    }
+  }
+  return {};
+}
+
+/**
+ * Folder holding the translator dictionaries, from the deployed config (`translator.path`,
+ * `/locales` by default). Null when the translator is off or the path is unusable, so no
+ * extra mount is added. `slice build` copies `src/<path>` into `dist/<path>`; without this
+ * mount production answers the SPA shell for every dictionary and the runtime shows keys.
+ */
+function readTranslatorFolder(projectRoot, folderDeployed) {
+  const file = path.join(projectRoot, folderDeployed, 'sliceConfig.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    const translator = JSON.parse(fs.readFileSync(file, 'utf8')).translator;
+    if (!translator?.enabled) return null;
+    const value = typeof translator.path === 'string' && translator.path.trim() ? translator.path : '/locales';
+    const folder = value.replace(/^\/+|\/+$/g, '');
+    return folder && !folder.includes('..') ? folder : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * True for `/Components/<Category>/<Name>/<Name>.css` when the component's `.js`
  * exists but it has no stylesheet. JS-only Visual components (MultiRoute,
@@ -145,8 +195,16 @@ export function sliceFallback(options = {}) {
     // With SEO configured the route set is known, so this is also where the
     // 200-vs-404 decision happens.
     if (seo) {
-      const { status, page } = seo.resolve(pathname);
-      return sendRendered(req, res, page, status);
+      const result = seo.resolve(pathname);
+      if (result.location) {
+        const query = req.originalUrl.includes('?') ? req.originalUrl.slice(req.originalUrl.indexOf('?')) : '';
+        const location = result.location.includes('?') ? result.location : `${result.location}${query}`;
+        // A locale redirect depends on the current default locale and prefix mode; do not
+        // let a browser keep it for an hour after a config change.
+        res.setHeader('Cache-Control', 'no-cache');
+        return res.redirect(result.status, location);
+      }
+      return sendRendered(req, res, result.page, result.status);
     }
 
     return sendShell(req, res);
@@ -187,14 +245,24 @@ async function loadRouteDefinitions(projectRoot, folderDeployed) {
     path.join(projectRoot, folderDeployed, 'routes.js'),
     path.join(projectRoot, 'src', 'routes.js')
   ];
+  const normalize = (base, value) => {
+    const merged = `${base || ''}${value || ''}`.replace(/\/+/g, '/');
+    return merged.length > 1 ? merged.replace(/\/+$/, '') || '/' : '/';
+  };
+  const flatten = (list, base = '') => {
+    const entries = [];
+    for (const route of Array.isArray(list) ? list : []) {
+      const full = normalize(base, route?.path);
+      if (full) entries.push({ path: full, metadata: route?.metadata || {} });
+      if (Array.isArray(route?.children)) entries.push(...flatten(route.children, full));
+    }
+    return entries;
+  };
   for (const candidate of candidates) {
     if (!fs.existsSync(candidate)) continue;
     const module = await import(pathToFileURL(candidate).href);
     const routes = module.default ?? module.routes ?? [];
-    return (Array.isArray(routes) ? routes : []).map((route) => ({
-      path: String(route?.path ?? '').replace(/\/+$/, '') || '/',
-      metadata: route?.metadata || {}
-    })).filter((route) => route.path);
+    return flatten(routes).filter((route) => route.path);
   }
   return [];
 }
@@ -244,15 +312,35 @@ export async function prepareSeo(options = {}) {
   const siteName = config.siteName || manifest.defaults?.siteName || null;
   const locale = config.locale || manifest.defaults?.locale || null;
   const routes = await loadRouteDefinitions(projectRoot, folderDeployed);
+  if (!routes.length) {
+    throw new Error('seo: routes.js is missing or empty; every page would answer 404');
+  }
 
-  const render = (pathname, routeMetadata) => {
-    const meta = resolveMetadata({ pathname, routeMetadata, manifest, origin });
+  // Multilingual SEO (translator feature 0003, phase 5). Without a translator this is
+  // one `null` locale and every rule below collapses to the old single-language path.
+  const translatorConfig = config.translator || readTranslatorConfig(projectRoot, folderDeployed);
+  const routerConfig = readRouterConfig(projectRoot, folderDeployed);
+  const translator = buildTranslatorContext(
+    translatorConfig,
+    loadTranslatorDictionaries(projectRoot, folderDeployed, translatorConfig)
+  );
+  const locales = translator.enabled
+    ? (translator.localePrefix ? translator.locales : [translator.defaultLocale])
+    : [null];
+  const ogLocaleConfig = manifest.locales && typeof manifest.locales === 'object' ? manifest.locales : {};
+
+  const render = (activeLocale, pathname, routeMetadata) => {
+    const translate = activeLocale
+      ? (key, params) => translator.t(activeLocale, key, params)
+      : null;
+    const url = translator.enabled ? translator.localize(pathname, activeLocale) : pathname;
+    const meta = resolveMetadata({ pathname, routeMetadata, manifest, origin, translate, url, routerConfig });
 
     // Precedence: an image declared on the route entry wins, then the generated
     // card, then `defaults.image` (the generic banner). Comparing against the raw
     // entry keeps the framework from guessing where the image came from.
     const explicitImage = pickRouteEntry(pathname, manifest)?.entry?.image;
-    const card = cards[pathname];
+    const card = cards[url] || cards[pathname];
     if (card && !explicitImage && !routeMetadata?.image) {
       meta.image = /^https?:\/\//i.test(card.path) ? card.path : `${origin}${card.path}`;
       meta.imageWidth = card.width ?? null;
@@ -261,7 +349,26 @@ export async function prepareSeo(options = {}) {
       meta.imageAlt = meta.imageAlt || meta.title;
     }
 
-    return encodeSeoPage(injectHead(shell, renderHead(meta, { siteName, locale })));
+    const alternates = translator.enabled && translator.localePrefix && activeLocale && translator.locales.length > 1
+      ? translator.locales
+        .map((code) => ({
+          hreflang: code,
+          href: `${origin}${translator.localize(pathname, code)}`
+        }))
+        .concat([{
+          hreflang: 'x-default',
+          href: `${origin}${translator.localize(pathname, translator.defaultLocale)}`
+        }])
+      : null;
+
+    const ogLocale = translator.enabled && activeLocale
+      ? (ogLocaleConfig[activeLocale]?.ogLocale || translator.ogLocale(activeLocale))
+      : locale;
+
+    const head = renderHead(meta, { siteName, locale: ogLocale, alternates });
+    return encodeSeoPage(injectHead(shell, head, translator.enabled && activeLocale
+      ? { lang: activeLocale, dir: translator.direction(activeLocale) }
+      : {}));
   };
 
   const pages = new Map();
@@ -271,44 +378,100 @@ export async function prepareSeo(options = {}) {
       patterns.push(route);
       continue;
     }
-    pages.set(route.path, render(route.path, route.metadata));
+    for (const activeLocale of locales) {
+      const url = translator.enabled ? translator.localize(route.path, activeLocale) : route.path;
+      pages.set(url, render(activeLocale, route.path, route.metadata));
+    }
   }
   // Longest pattern first so `/p/${id}/detail` wins over `/p/${id}`.
   patterns.sort((a, b) => b.path.length - a.path.length);
 
-  const notFound = encodeSeoPage(injectHead(
-    shell,
-    '<title>Not found</title>\n    <meta name="robots" content="noindex, nofollow" />'
-  ));
+  const notFound = new Map();
+  const notFoundPrefix = typeof routerConfig.titlePrefix === 'string' ? routerConfig.titlePrefix : '';
+  const notFoundSuffix = typeof routerConfig.titleSuffix === 'string' ? routerConfig.titleSuffix : '';
+  for (const activeLocale of locales) {
+    const key = 'seo.notFound.title';
+    const translated = translator.enabled && activeLocale ? translator.t(activeLocale, key) : key;
+    const title = `${notFoundPrefix}${translated === key ? 'Not found' : translated}${notFoundSuffix}`;
+    const descriptionKey = 'seo.notFound.description';
+    const description = translator.enabled && activeLocale ? translator.t(activeLocale, descriptionKey) : descriptionKey;
+    const head = renderHead(
+      {
+        title,
+        description: description === descriptionKey ? null : description,
+        robots: 'noindex, nofollow'
+      },
+      { locale: translator.enabled && activeLocale ? translator.ogLocale(activeLocale) : null }
+    );
+    notFound.set(activeLocale, encodeSeoPage(injectHead(
+      shell,
+      head,
+      translator.enabled && activeLocale
+        ? { lang: activeLocale, dir: translator.direction(activeLocale) }
+        : {}
+    )));
+  }
 
   // A `${param}` route cannot be enumerated, so it is rendered per path. The
   // cache keeps repeated visits of the same product from recompressing.
   const dynamicPages = new Map();
   const DYNAMIC_LIMIT = 200;
 
+  /** The page for an app path in one locale: prerendered, cached dynamic, or 404. */
+  const settle = (appPath, activeLocale) => {
+    const url = translator.enabled ? translator.localize(appPath, activeLocale) : appPath;
+    const exact = pages.get(url);
+    if (exact) return { status: 200, page: exact };
+
+    const dynamic = dynamicPages.get(url);
+    if (dynamic) return { status: 200, page: dynamic };
+
+    for (const route of patterns) {
+      if (!matchPathPattern(route.path, appPath)) continue;
+      const page = render(activeLocale, appPath, route.metadata);
+      if (dynamicPages.size >= DYNAMIC_LIMIT) {
+        dynamicPages.delete(dynamicPages.keys().next().value);
+      }
+      dynamicPages.set(url, page);
+      return { status: 200, page };
+    }
+
+    return { status: 404, page: notFound.get(activeLocale) || notFound.get(null) };
+  };
+
   return {
     origin,
     manifest,
     routes,
+    translator,
     prerendered: pages.size,
     resolve(pathname) {
-      const exact = pages.get(pathname);
-      if (exact) return { status: 200, page: exact };
+      if (!translator.enabled || !translator.localePrefix) {
+        return settle(pathname, translator.defaultLocale);
+      }
 
-      const dynamic = dynamicPages.get(pathname);
-      if (dynamic) return { status: 200, page: dynamic };
+      const { locale: urlLocale, path: appPath } = translator.split(pathname);
 
-      for (const route of patterns) {
-        if (!matchPathPattern(route.path, pathname)) continue;
-        const page = render(pathname, route.metadata);
-        if (dynamicPages.size >= DYNAMIC_LIMIT) {
-          dynamicPages.delete(dynamicPages.keys().next().value);
+      if (urlLocale) {
+        // `/es/pricing` under "prefix-except-default": the canonical URL is `/pricing`.
+        if (translator.localePrefix === 'except-default' && urlLocale === translator.defaultLocale) {
+          return { status: 301, location: appPath };
         }
-        dynamicPages.set(pathname, page);
-        return { status: 200, page };
+        return settle(appPath, urlLocale);
       }
 
-      return { status: 404, page: notFound };
+      // With "always" every page has a locale in the URL. `/` picks the default (the
+      // client may then apply the saved/browser choice). A known unprefixed path is a
+      // 302 to its prefixed URL, not a 404: the client can render it and search engines
+      // must see the canonical URL.
+      if (translator.localePrefix === 'always') {
+        if (pathname === '/' || settle(pathname, translator.defaultLocale).status === 200) {
+          return { status: 302, location: translator.localize(pathname, translator.defaultLocale) };
+        }
+        return { status: 404, page: notFound.get(translator.defaultLocale) };
+      }
+
+      return settle(pathname, translator.defaultLocale);
     }
   };
 }
@@ -654,6 +817,19 @@ export function createSliceServer(options = {}) {
     app.use('/dist/', express.static(path.join(projectRoot, 'dist')));
   }
 
+  // Translator dictionaries (`translator.path`, `/locales` by default): app data copied
+  // into dist by `slice build`. Mounted in both modes so the path is explicit; without it
+  // production answered the SPA shell for every dictionary and the runtime showed keys.
+  const translatorFolder = readTranslatorFolder(projectRoot, folderDeployed);
+  if (translatorFolder) {
+    app.use(
+      `/${translatorFolder}`,
+      express.static(path.join(projectRoot, folderDeployed, translatorFolder), {
+        setHeaders: (res) => res.setHeader('Cache-Control', 'public, max-age=300, stale-while-revalidate=86400')
+      })
+    );
+  }
+
   // ==============================================
   // RUTAS DE API
   // ==============================================
@@ -737,7 +913,8 @@ export function createSliceServer(options = {}) {
     if (options.seo) {
       seo = await prepareSeo({ ...options, port });
       if (seo) {
-        console.log(`🔎 SEO: ${seo.prerendered} routes prerendered (${seo.origin})`);
+        const localeCount = seo.translator?.enabled ? seo.translator.locales.length : 0;
+        console.log(`🔎 SEO: ${seo.prerendered} pages prerendered${localeCount ? ` (${localeCount} locales)` : ''} (${seo.origin})`);
       } else {
         console.warn('[slice] seo options were given but no manifest was found; SEO is off.');
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "",
   "engines": {
     "node": ">=20"
@@ -31,6 +31,7 @@
     "./api/framework/express.js": "./api/framework/express.js",
     "./api/framework/server.js": "./api/framework/server.js",
     "./api/framework/seo.js": "./api/framework/seo.js",
+    "./api/framework/content.js": "./api/framework/content.js",
     "./api/framework/devDepsOptimizer.js": "./api/framework/devDepsOptimizer.js"
   },
   "types": "./types/index.d.ts",

package/sliceConfig.schema.json

@@ -1,122 +1,150 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://slicejs.local/sliceConfig.schema.json",
-  "title": "Slice.js Config",
-  "type": "object",
-  "additionalProperties": true,
-  "properties": {
-    "debugger": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" },
-        "click": { "type": "string", "enum": ["right", "left"] },
-        "leakInspector": {
-          "type": "object",
-          "additionalProperties": true,
-          "description": "Dev-only memory-leak panel. Disabled in production regardless of this flag.",
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "shortcut": { "type": "string" }
-          }
-        }
-      }
-    },
-    "stylesManager": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "requestedStyles": { "type": "array", "items": { "type": "string" } }
-      }
-    },
-    "themeManager": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" },
-        "defaultTheme": { "type": "string" },
-        "saveThemeLocally": { "type": "boolean" },
-        "useBrowserTheme": { "type": "boolean" }
-      }
-    },
-    "logger": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" },
-        "showLogs": { "type": "object", "additionalProperties": true },
-        "ui": {
-          "type": "object",
-          "additionalProperties": true,
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "shortcut": { "type": "string" }
-          }
-        }
-      }
-    },
-    "events": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" },
-        "ui": {
-          "type": "object",
-          "additionalProperties": true,
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "shortcut": { "type": "string" }
-          }
-        }
-      }
-    },
-    "context": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" },
-        "ui": {
-          "type": "object",
-          "additionalProperties": true,
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "shortcut": { "type": "string" }
-          }
-        }
-      }
-    },
-    "paths": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "components": { "type": "object", "additionalProperties": true },
-        "themes": { "type": "string" },
-        "styles": { "type": "string" },
-        "routesFile": { "type": "string" }
-      },
-      "required": ["components", "themes", "styles", "routesFile"]
-    },
-    "router": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "defaultRoute": { "type": "string" }
-      }
-    },
-    "loading": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "enabled": { "type": "boolean" }
-      }
-    },
-    "server": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "port": { "type": "number" },
-        "host": { "type": "string" }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://slicejs.local/sliceConfig.schema.json",
+  "title": "Slice.js Config",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "debugger": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "click": { "type": "string", "enum": ["right", "left"] },
+        "leakInspector": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Dev-only memory-leak panel. Disabled in production regardless of this flag.",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "shortcut": { "type": "string" }
+          }
+        }
+      }
+    },
+    "stylesManager": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "requestedStyles": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "themeManager": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "defaultTheme": { "type": "string" },
+        "saveThemeLocally": { "type": "boolean" },
+        "useBrowserTheme": { "type": "boolean" }
+      }
+    },
+    "logger": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "showLogs": { "type": "object", "additionalProperties": true },
+        "ui": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "shortcut": { "type": "string" }
+          }
+        }
+      }
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "ui": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "shortcut": { "type": "string" }
+          }
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "ui": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "shortcut": { "type": "string" }
+          }
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "components": { "type": "object", "additionalProperties": true },
+        "themes": { "type": "string" },
+        "styles": { "type": "string" },
+        "routesFile": { "type": "string" }
+      },
+      "required": ["components", "themes", "styles", "routesFile"]
+    },
+    "router": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "defaultRoute": { "type": "string" },
+        "updateTitles": { "type": "boolean", "description": "Write document.title and the description from route metadata. Default true." },
+        "titlePrefix": { "type": "string", "description": "Text before every route title. The separator is part of the string (\"Acme · \")." },
+        "titleSuffix": { "type": "string", "description": "Text after every route title. The separator is part of the string (\" · Acme\")." }
+      }
+    },
+    "translator": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "slice.translator: dictionaries in <path>/<locale>.json, data-t in templates, slice.t() for text and slice.t.ref() for props.",
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Off: slice.t() returns the key and nothing is loaded." },
+        "defaultLocale": { "type": "string", "minLength": 1 },
+        "fallbackLocale": { "type": ["string", "null"], "description": "Asked when the active locale lacks a key." },
+        "locales": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "path": { "type": "string", "description": "Where dictionaries are served from. Default /locales." },
+        "saveLocally": { "type": "boolean", "description": "Remember the user's choice in localStorage." },
+        "useBrowserLocale": { "type": "boolean", "description": "First visit: the browser's language when supported." },
+        "localePrefix": {
+          "enum": [false, "always", "except-default"],
+          "description": "Locale in the URL. false keeps it out; always puts it in every URL; except-default leaves the default locale unprefixed."
+        },
+        "ui": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": { "enabled": { "type": "boolean" }, "shortcut": { "type": "string" } }
+        }
+      },
+      "if": { "properties": { "enabled": { "const": true } }, "required": ["enabled"] },
+      "then": { "required": ["defaultLocale"] }
+    },
+    "loading": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" }
+      }
+    },
+    "server": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "port": { "type": "number" },
+        "host": { "type": "string" }
+      }
+    }
+  }
+}