slicejs-web-framework 4.1.0 → 4.2.0

package/api/framework/content.js

@@ -0,0 +1,73 @@
+// api/framework/content.js — read and resolve the app's content documents on the server.
+//
+// Content lives in `<translator.path>/content/<name>.json` (the same files the browser
+// fetches through `slice.t.content()`). The resolver is the runtime's pure helper, so the
+// server and the browser cannot disagree about `copy` branches or fallbacks.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { localize } from '../../Slice/Components/Structural/Translator/localized.js';
+import { resolveContent } from '../../Slice/Components/Structural/Translator/content.js';
+
+/**
+ * The folder that holds the content documents for a deployed app.
+ * @param {string} projectRoot
+ * @param {{ deployedFolder?: string, translator?: { path?: string } }} [options]
+ * @returns {string}
+ */
+export function contentDirectory(projectRoot, options = {}) {
+   const deployedFolder = options.deployedFolder || 'src';
+   const configured = typeof options.translator?.path === 'string' && options.translator.path.trim()
+      ? options.translator.path
+      : '/locales';
+   const folder = configured.replace(/^\/+|\/+$/g, '') || 'locales';
+   return path.join(projectRoot, deployedFolder, folder, 'content');
+}
+
+/**
+ * Validate a document name before turning it into a path: `experience` or `teaching/pr2`,
+ * never an absolute path or a `..` segment.
+ * @param {string} name
+ * @returns {string}
+ */
+export function normalizeContentName(name) {
+   const value = String(name ?? '').trim().replace(/^\/+|\/+$/g, '');
+   const valid = value && /^[a-z0-9][a-z0-9/_-]*$/i.test(value) && !value.split('/').some((segment) => !segment || segment === '.' || segment === '..');
+   if (!valid) throw new Error(`[slice.content] invalid content document name "${name}"`);
+   return value;
+}
+
+/**
+ * Read a content document from `<deployedFolder>/<translator.path>/content/<name>.json`.
+ * Throws with the full path when it cannot be read or parsed.
+ * @param {string} projectRoot
+ * @param {string} name
+ * @param {{ deployedFolder?: string, translator?: { path?: string } }} [options]
+ * @returns {Record<string, any>}
+ */
+export function readContent(projectRoot, name, options = {}) {
+   const document = normalizeContentName(name);
+   const file = path.join(contentDirectory(projectRoot, options), `${document}.json`);
+   try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+   } catch (error) {
+      throw new Error(`[slice.content] could not read "${document}" (${file}): ${error.message}`);
+   }
+}
+
+/**
+ * Resolve a content document for one locale (`copy` branches replaced, nested nodes flat).
+ * @param {any} document
+ * @param {{ defaultLocale?: string, fallbackLocale?: string|null, locales?: string[] }} [translator]
+ * @param {string} [locale]
+ * @returns {any}
+ */
+export function resolveContentFor(document, translator = {}, locale = translator.defaultLocale || 'en') {
+   const defaultLocale = translator.defaultLocale || 'en';
+   return resolveContent(document, (value) => localize(value, {
+      locale: locale || defaultLocale,
+      fallbackLocale: translator.fallbackLocale || null,
+      defaultLocale,
+      locales: Array.isArray(translator.locales) && translator.locales.length ? translator.locales : [defaultLocale],
+   }));
+}

package/api/framework/seo.js

@@ -9,6 +9,19 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  IntlCache,
+  directionOf,
+  formatMessage,
+  isPluralMessage,
+  lookup as lookupMessage
+} from '../../Slice/Components/Structural/Translator/messages.js';
+import {
+  localeOfUrl,
+  localizePath,
+  normalizeLocalePrefix,
+  splitLocalePath
+} from '../../Slice/Components/Structural/Translator/localePath.js';
 
 export const SEO_VERSION = 1;
 
@@ -40,6 +53,136 @@ export function matchPathPattern(pattern, pathname) {
 
 const isPattern = (value) => /\$\{[^}]+\}/.test(String(value));
 
+/**
+ * The translator as the server needs it: which locales exist, how a URL carries one, and
+ * `t()` for `{ t: 'key' }` fields. Same lookup order as the browser (locale → fallback →
+ * the key itself), using the dictionaries the client already downloads.
+ *
+ * @param {object|null} config the `translator` block from sliceConfig.json
+ * @param {Record<string, object>} [dictionaries] locale → messages
+ */
+export function buildTranslatorContext(config, dictionaries = {}) {
+  const clean = (value) => (typeof value === 'string' && value.trim() ? value.trim() : '');
+  const enabled = config?.enabled === true && clean(config.defaultLocale) !== '';
+  const defaultLocale = enabled ? clean(config.defaultLocale) : null;
+  const declared = Array.isArray(config?.locales) ? config.locales.map(clean).filter(Boolean) : [];
+  const seen = new Map();
+  for (const locale of enabled ? [defaultLocale, ...declared] : []) {
+    const key = locale.toLowerCase();
+    if (!seen.has(key)) seen.set(key, locale);
+  }
+  const fallbackLocale = enabled && clean(config.fallbackLocale)
+    && clean(config.fallbackLocale).toLowerCase() !== defaultLocale.toLowerCase()
+    ? clean(config.fallbackLocale)
+    : null;
+  // The fallback is a real locale: the client lists it (setLocale accepts it), so the
+  // server must too or it would emit URLs it then treats as unknown prefixes.
+  if (fallbackLocale && !seen.has(fallbackLocale.toLowerCase())) seen.set(fallbackLocale.toLowerCase(), fallbackLocale);
+  const locales = enabled ? [...seen.values()] : [];
+  const localePrefix = enabled ? normalizeLocalePrefix(config.localePrefix) : false;
+  const intl = new IntlCache();
+
+  const entry = (locale, key) => {
+    const value = lookupMessage(dictionaries[locale], key);
+    if (value === undefined && fallbackLocale && locale !== fallbackLocale) {
+      return lookupMessage(dictionaries[fallbackLocale], key);
+    }
+    return value;
+  };
+
+  const t = (locale, key, params) => {
+    if (!enabled || typeof key !== 'string') return key;
+    const value = entry(locale, key);
+    if (value === undefined) return key;
+    return formatMessage(value, params, locale, intl) ?? key;
+  };
+
+  const localize = (pathname, locale) => (enabled
+    ? localizePath(pathname, locale || defaultLocale, { localePrefix, defaultLocale })
+    : pathname);
+
+  return {
+    enabled,
+    localePrefix,
+    defaultLocale,
+    fallbackLocale,
+    locales,
+    t,
+    has: (locale, key) => {
+      if (!enabled) return false;
+      const value = entry(locale, key);
+      return typeof value === 'string' || isPluralMessage(value);
+    },
+    localize,
+    split: (pathname) => (enabled && localePrefix
+      ? splitLocalePath(pathname, locales)
+      : { locale: null, path: pathname }),
+    localeOf: (pathname) => (enabled
+      ? localeOfUrl(pathname, { localePrefix, defaultLocale, locales })
+      : null),
+    direction: (locale) => directionOf(locale || defaultLocale || 'en'),
+    ogLocale: (locale) => String(locale || '').replace('-', '_')
+  };
+}
+
+/**
+ * Read `{ locale: messages }` from `<folderDeployed>/<translator.path>/<locale>.json`.
+ * Missing files are tolerated (the key shows, as in the browser); a malformed one is an
+ * error the server cannot silently ignore.
+ */
+export function loadTranslatorDictionaries(projectRoot, folderDeployed, config) {
+  if (config?.enabled !== true) return {};
+  const folder = String(config.path || '/locales').replace(/^\/+|\/+$/g, '') || 'locales';
+  const declared = [
+    config.defaultLocale,
+    ...(Array.isArray(config.locales) ? config.locales : []),
+    config.fallbackLocale
+  ].filter((value) => typeof value === 'string' && value);
+
+  const dictionaries = {};
+  for (const locale of [...new Set(declared)]) {
+    const base = path.join(projectRoot, folderDeployed, folder);
+    const file = path.join(base, `${locale}.json`);
+    let messages = null;
+    if (fs.existsSync(file)) {
+      try {
+        messages = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch (error) {
+        throw new Error(`seo: invalid translator dictionary ${locale}.json: ${error.message}`);
+      }
+    }
+    // Namespaced dictionaries (`<path>/<locale>/<ns>.json`, loaded by translator.load())
+    // are part of the same locale; the browser merges them under the file name.
+    const namespaceDir = path.join(base, locale);
+    if (fs.existsSync(namespaceDir) && fs.statSync(namespaceDir).isDirectory()) {
+      messages = messages && typeof messages === 'object' ? messages : {};
+      for (const name of fs.readdirSync(namespaceDir)) {
+        if (!name.endsWith('.json')) continue;
+        const namespace = name.slice(0, -5);
+        try {
+          messages[namespace] = JSON.parse(fs.readFileSync(path.join(namespaceDir, name), 'utf8'));
+        } catch (error) {
+          throw new Error(`seo: invalid translator dictionary ${locale}/${name}: ${error.message}`);
+        }
+      }
+    }
+    if (messages) dictionaries[locale] = messages;
+  }
+  return dictionaries;
+}
+
+/**
+ * `{ t: 'key', params? }` → text. Anything else is returned untouched, so plain strings
+ * keep working in every locale. Exported for the server, the CLI and the tests.
+ */
+export function resolveSeoText(value, translate) {
+  if (value && typeof value === 'object' && typeof value.t === 'string') {
+    return translate ? translate(value.t, value.params) : value.t;
+  }
+  return value;
+}
+
+
 /**
  * The most specific manifest entry for a path: an exact key first, then the
  * longest matching pattern, then nothing.
@@ -105,21 +248,65 @@ const robotsDirectives = (robots) => {
 
 /**
  * Resolve one route's metadata: defaults -> manifest entry (literal or pattern)
- * -> inline `metadata` from routes.js (most specific, wins).
+ * -> inline `metadata` from routes.js (most specific, wins). With `translate`, every
+ * documented text field may be `{ t: 'key', params? }` (translator feature 0003).
  */
-export function resolveMetadata({ pathname, routeMetadata, manifest = {}, origin }) {
+export function resolveMetadata({ pathname, routeMetadata, manifest = {}, origin, translate = null, url = pathname, routerConfig = {} }) {
+  const inline = routeMetadata && typeof routeMetadata === 'object' ? { ...routeMetadata } : null;
+  // `titleKey` / `descriptionKey` are the shorthand for `{ t: 'key' }`; they win
+  // over the literal `title` / `description`.
+  if (inline) {
+    if (typeof inline.titleKey === 'string' && inline.titleKey.trim()) {
+      inline.title = { t: inline.titleKey.trim() };
+    }
+    if (typeof inline.descriptionKey === 'string' && inline.descriptionKey.trim()) {
+      inline.description = { t: inline.descriptionKey.trim() };
+    }
+  }
+  const text = (value) => resolveSeoText(value, translate);
+  const defaultTitle = text(manifest.defaults?.title);
   const merged = mergeDeep(
     mergeDeep(manifest.defaults || {}, pickRouteEntry(pathname, manifest)?.entry),
-    routeMetadata
+    inline
   );
 
-  const title = merged.title ?? null;
-  const template = merged.titleTemplate;
-  const finalTitle = title && template && template !== '%s' ? template.replace('%s', title) : title;
+  // `titleKey` / `descriptionKey` may come from routes.js OR from a seo.json entry;
+  // normalise the merged object so both work (the manifest path was previously ignored).
+  if (typeof merged.titleKey === 'string' && merged.titleKey.trim()) merged.title = { t: merged.titleKey.trim() };
+  if (typeof merged.descriptionKey === 'string' && merged.descriptionKey.trim()) {
+    merged.description = { t: merged.descriptionKey.trim() };
+  }
+
+  // Always map `{ t }`: with no translate (translator off) the key is the honest output,
+  // never "[object Object]".
+  merged.title = text(merged.title);
+  merged.description = text(merged.description);
+  merged.imageAlt = text(merged.imageAlt);
+  if (merged.openGraph) {
+    merged.openGraph = {
+      ...merged.openGraph,
+      title: text(merged.openGraph.title),
+      description: text(merged.openGraph.description),
+      siteName: text(merged.openGraph.siteName)
+    };
+  }
+  if (merged.twitter) {
+    merged.twitter = {
+      ...merged.twitter,
+      title: text(merged.twitter.title),
+      description: text(merged.twitter.description)
+    };
+  }
+
+  const title = merged.title || defaultTitle || null;
+  const affix = (own, fallback) => (own === false ? '' : typeof own === 'string' ? own : typeof fallback === 'string' ? fallback : '');
+  const prefix = affix(text(merged.titlePrefix), routerConfig?.titlePrefix);
+  const suffix = affix(text(merged.titleSuffix), routerConfig?.titleSuffix);
+  const finalTitle = title ? `${prefix}${title}${suffix}` : null;
 
   const canonical = merged.canonical
     ? absolute(merged.canonical, origin)
-    : `${origin}${pathname === '/' ? '/' : pathname}`;
+    : `${origin}${url === '/' ? '/' : url}`;
 
   const image = absolute(merged.image ?? merged.openGraph?.image ?? merged.openGraph?.images?.[0]?.url, origin);
 
@@ -151,24 +338,32 @@ export function serializeJsonLd(list) {
 }
 
 /** The `<head>` block for one route. Pure: no shell, no injection. */
-export function renderHead(meta, { siteName = null, locale = null } = {}) {
+export function renderHead(meta, { siteName = null, locale = null, alternates = null } = {}) {
   const tags = [];
   if (meta.title) tags.push(`<title>${escapeHtml(meta.title)}</title>`);
   if (meta.description) tags.push(`<meta name="description" content="${escapeHtml(meta.description)}" />`);
   if (meta.canonical) tags.push(`<link rel="canonical" href="${escapeHtml(meta.canonical)}" />`);
+  if (Array.isArray(alternates)) {
+    for (const alternate of alternates) {
+      if (!alternate?.href || !alternate?.hreflang) continue;
+      tags.push(`<link rel="alternate" hreflang="${escapeHtml(alternate.hreflang)}" href="${escapeHtml(alternate.href)}" />`);
+    }
+  }
   tags.push(`<meta name="robots" content="${escapeHtml(meta.robots)}" />`);
 
-  const ogType = meta.openGraph.type || 'website';
-  const ogTitle = meta.openGraph.title || meta.title;
-  const ogDescription = meta.openGraph.description || meta.description;
+  const openGraph = meta.openGraph || {};
+  const twitter = meta.twitter || {};
+  const ogType = openGraph.type || 'website';
+  const ogTitle = openGraph.title || meta.title;
+  const ogDescription = openGraph.description || meta.description;
 
   tags.push(`<meta property="og:type" content="${escapeHtml(ogType)}" />`);
   if (ogTitle) tags.push(`<meta property="og:title" content="${escapeHtml(ogTitle)}" />`);
   if (ogDescription) tags.push(`<meta property="og:description" content="${escapeHtml(ogDescription)}" />`);
   if (meta.canonical) tags.push(`<meta property="og:url" content="${escapeHtml(meta.canonical)}" />`);
-  const ogSiteName = meta.openGraph.siteName || siteName;
+  const ogSiteName = openGraph.siteName || siteName;
   if (ogSiteName) tags.push(`<meta property="og:site_name" content="${escapeHtml(ogSiteName)}" />`);
-  const ogLocale = meta.openGraph.locale || locale;
+  const ogLocale = openGraph.locale || locale;
   if (ogLocale) tags.push(`<meta property="og:locale" content="${escapeHtml(ogLocale)}" />`);
   if (meta.image) {
     tags.push(`<meta property="og:image" content="${escapeHtml(meta.image)}" />`);
@@ -178,11 +373,11 @@ export function renderHead(meta, { siteName = null, locale = null } = {}) {
     if (meta.imageAlt) tags.push(`<meta property="og:image:alt" content="${escapeHtml(meta.imageAlt)}" />`);
   }
 
-  const card = meta.twitter.card
+  const card = twitter.card
     || (meta.image ? 'summary_large_image' : 'summary');
   tags.push(`<meta name="twitter:card" content="${escapeHtml(card)}" />`);
-  if (meta.twitter.site) tags.push(`<meta name="twitter:site" content="${escapeHtml(meta.twitter.site)}" />`);
-  if (meta.twitter.creator) tags.push(`<meta name="twitter:creator" content="${escapeHtml(meta.twitter.creator)}" />`);
+  if (twitter.site) tags.push(`<meta name="twitter:site" content="${escapeHtml(twitter.site)}" />`);
+  if (twitter.creator) tags.push(`<meta name="twitter:creator" content="${escapeHtml(twitter.creator)}" />`);
   if (ogTitle) tags.push(`<meta name="twitter:title" content="${escapeHtml(ogTitle)}" />`);
   if (ogDescription) tags.push(`<meta name="twitter:description" content="${escapeHtml(ogDescription)}" />`);
   if (meta.image) tags.push(`<meta name="twitter:image" content="${escapeHtml(meta.image)}" />`);
@@ -203,9 +398,28 @@ const OWNED_HEAD = [
   /<script\s+type="application\/ld\+json"[^>]*>[\s\S]*?<\/script>/gi
 ];
 
+/** Replace `<html lang|dir>` (or add them) in a shell. No-op when both are null. */
+export function setDocumentLanguage(html, { lang = null, dir = null } = {}) {
+  if (!lang && !dir) return String(html);
+  return String(html).replace(/<html\b([^>]*)>/i, (match, attributes) => {
+    let next = attributes;
+    if (lang) {
+      next = /\slang="/i.test(next)
+        ? next.replace(/\slang="[^"]*"/i, ` lang="${lang}"`)
+        : `${next} lang="${lang}"`;
+    }
+    if (dir) {
+      next = /\sdir="/i.test(next)
+        ? next.replace(/\sdir="[^"]*"/i, ` dir="${dir}"`)
+        : `${next} dir="${dir}"`;
+    }
+    return `<html${next}>`;
+  });
+}
+
 /** Replace this module's tags in a shell with the route's own block. */
-export function injectHead(html, headTags) {
-  let output = String(html);
+export function injectHead(html, headTags, options = {}) {
+  let output = setDocumentLanguage(html, options);
   for (const pattern of OWNED_HEAD) output = output.replace(pattern, '');
   const block = `    ${headTags}\n  `;
   if (/<\/head>/i.test(output)) return output.replace(/<\/head>/i, `${block}</head>`);
@@ -222,40 +436,98 @@ const xmlEscape = (value) => String(value ?? '')
 /**
  * `sitemap.xml` from the manifest. Only literal routes that are indexable and
  * not explicitly excluded: a `${param}` pattern cannot be enumerated.
+ *
+ * With a translator context and `localePrefix`, every route appears once per locale and
+ * each `<url>` carries the `xhtml:link` alternates (plus `x-default`), so the
+ * sitemap and the `hreflang` in the head cannot disagree.
  */
-export function buildSitemap({ manifest, origin }) {
+/**
+ * Expand a `${param}` sitemap entry into concrete paths.
+ * `values` are strings (single parameter) or objects (`{ slug: 'pr2' }`).
+ * @param {string} key
+ * @param {any[]} values
+ * @returns {string[]}
+ */
+function expandPatternPaths(key, values) {
+   const names = [...key.matchAll(/\$\{([^}]+)\}/g)].map((match) => match[1]);
+   if (names.length === 0 || !Array.isArray(values)) return [];
+   const paths = [];
+   for (const value of values) {
+      const params = typeof value === 'string' ? { [names[0]]: value } : value;
+      if (!params || typeof params !== 'object') continue;
+      if (names.some((name) => params[name] === undefined || params[name] === null || params[name] === '')) continue;
+      paths.push(key.replace(/\$\{([^}]+)\}/g, (_, name) => encodeURIComponent(String(params[name]))));
+   }
+   return paths;
+}
+
+export function buildSitemap({ manifest, origin, translator = null }) {
   const base = normalizeOrigin(origin);
   if (!base) throw new Error('seo: buildSitemap needs an absolute origin');
 
+  const active = translator?.enabled ? translator : null;
+  // Without a locale prefix the URL does not identify a locale, so the sitemap has one
+  // URL per route (the default locale) and no alternates.
+  const locales = active
+    ? (active.localePrefix ? active.locales : [active.defaultLocale])
+    : [null];
   const urls = [];
+  const seen = new Set();
+
   for (const [key, entry] of Object.entries(manifest?.routes || {})) {
-    if (isPattern(key)) continue;
     if (entry?.sitemap === false) continue;
     if (entry?.robots === false || entry?.robots?.index === false) continue;
     if (entry?.noindex) continue;
 
-    const loc = `${base}${key === '/' ? '/' : key}`;
+    // A pattern cannot be enumerated by itself; it opts in with `sitemap.paths`.
+    const concretePaths = isPattern(key)
+      ? expandPatternPaths(key, entry?.sitemap?.paths)
+      : [key];
+    if (concretePaths.length === 0) continue;
+
     const sitemap = entry?.sitemap && typeof entry.sitemap === 'object' ? entry.sitemap : {};
     const lastmod = sitemap.lastmod || entry?.lastmod;
     const changefreq = sitemap.changefreq || entry?.changefreq;
     const priority = sitemap.priority || entry?.priority;
 
-    // One field per line: a <lastmod> update is a one-line diff in review.
-    const block = [
-      '  <url>',
-      `    <loc>${xmlEscape(loc)}</loc>`,
-      lastmod ? `    <lastmod>${xmlEscape(lastmod)}</lastmod>` : '',
-      changefreq ? `    <changefreq>${xmlEscape(changefreq)}</changefreq>` : '',
-      priority ? `    <priority>${xmlEscape(priority)}</priority>` : '',
-      '  </url>'
-    ].filter(Boolean);
-    urls.push({ loc, body: block.join('\n') });
+    for (const concrete of concretePaths) {
+      const paths = locales.map((locale) => (active ? active.localize(concrete, locale) : concrete));
+      const alternates = active?.localePrefix && locales.length > 1
+        ? locales
+          .map((locale, index) => ({
+            hreflang: locale,
+            href: `${base}${paths[index] === '/' ? '/' : paths[index]}`
+          }))
+          .concat([{
+            hreflang: 'x-default',
+            href: `${base}${active.localize(concrete, active.defaultLocale)}`
+          }])
+        : [];
+
+      for (const pathname of paths) {
+        const loc = `${base}${pathname === '/' ? '/' : pathname}`;
+        if (seen.has(loc)) continue;
+        seen.add(loc);
+        // One field per line: a <lastmod> update is a one-line diff in review.
+        const block = [
+          '  <url>',
+          `    <loc>${xmlEscape(loc)}</loc>`,
+          ...alternates.map((alternate) =>
+            `    <xhtml:link rel="alternate" hreflang="${xmlEscape(alternate.hreflang)}" href="${xmlEscape(alternate.href)}" />`),
+          lastmod ? `    <lastmod>${xmlEscape(lastmod)}</lastmod>` : '',
+          changefreq ? `    <changefreq>${xmlEscape(changefreq)}</changefreq>` : '',
+          priority ? `    <priority>${xmlEscape(priority)}</priority>` : '',
+          '  </url>'
+        ].filter(Boolean);
+        urls.push({ loc, body: block.join('\n') });
+      }
+    }
   }
 
   urls.sort((a, b) => a.loc.localeCompare(b.loc));
   return [
     '<?xml version="1.0" encoding="UTF-8"?>',
-    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${active ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : ''}>`,
     ...urls.map((url) => url.body),
     '</urlset>',
     ''
@@ -265,10 +537,24 @@ export function buildSitemap({ manifest, origin }) {
 /** Route paths from `routes.js`, normalised (leading slash, no trailing slash). */
 export function routePaths(routes) {
   const list = Array.isArray(routes) ? routes : [];
-  return list
-    .map((route) => (typeof route === 'string' ? route : route?.path))
-    .filter(Boolean)
-    .map((value) => String(value).replace(/\/+$/, '') || '/');
+  const normalize = (base, value) => {
+    const merged = `${base || ''}${value || ''}`.replace(/\/+/g, '/');
+    return merged.length > 1 ? merged.replace(/\/+$/, '') || '/' : '/';
+  };
+  const paths = [];
+  const walk = (entries, base = '') => {
+    for (const route of Array.isArray(entries) ? entries : []) {
+      if (typeof route === 'string') {
+        paths.push(normalize(base, route));
+        continue;
+      }
+      const full = normalize(base, route?.path);
+      if (route?.path) paths.push(full);
+      if (Array.isArray(route?.children)) walk(route.children, full);
+    }
+  };
+  walk(list);
+  return paths;
 }
 
 /**
@@ -281,13 +567,51 @@ export function validateSeoManifest(manifest, options = {}) {
     fileExists = (file) => fs.existsSync(file),
     publicDir = null,
     titleLimit = DEFAULT_TITLE_LIMIT,
-    descriptionLimit = DEFAULT_DESCRIPTION_LIMIT
+    descriptionLimit = DEFAULT_DESCRIPTION_LIMIT,
+    translator = null
   } = options;
 
   const errors = [];
   const warnings = [];
   const add = (list, message) => list.push(message);
 
+  /** `{ t: 'key' }` references in the fields a translator may fill. */
+  const keyRefsOf = (entry, where) => {
+    const refs = [];
+    const scan = (value, field) => {
+      if (value && typeof value === 'object' && !Array.isArray(value) && typeof value.t === 'string') {
+        refs.push({ key: value.t, where: `${where}.${field}` });
+      }
+    };
+    for (const field of ['title', 'description', 'imageAlt']) scan(entry?.[field], field);
+    for (const field of ['titleKey', 'descriptionKey']) {
+      if (typeof entry?.[field] === 'string' && entry[field].trim()) {
+        refs.push({ key: entry[field].trim(), where: `${where}.${field}` });
+      }
+    }
+    for (const group of ['openGraph', 'twitter']) {
+      for (const field of ['title', 'description', 'siteName']) scan(entry?.[group]?.[field], `${group}.${field}`);
+    }
+    return refs;
+  };
+
+  /**
+   * A `{ t }` key missing in one locale would ship the key as a title, so it blocks.
+   * The browser resolves the same way (locale → fallback → key).
+   */
+  const checkTranslations = (entry, where) => {
+    if (!translator?.enabled) return;
+    const refs = keyRefsOf(entry, where);
+    if (!refs.length) return;
+    for (const locale of translator.locales) {
+      for (const ref of refs) {
+        if (!translator.has(locale, ref.key)) {
+          add(errors, `missing translation "${ref.key}" for "${locale}" (${ref.where})`);
+        }
+      }
+    }
+  };
+
   if (!manifest || typeof manifest !== 'object') {
     return { errors: ['manifest is not an object'], warnings };
   }
@@ -306,6 +630,7 @@ export function validateSeoManifest(manifest, options = {}) {
   }
 
   const seen = new Map();
+  checkTranslations(manifest.defaults, 'defaults');
   for (const [key, entry] of Object.entries(manifest.routes || {})) {
     if (!key.startsWith('/')) add(errors, `route key must start with "/": ${key}`);
     if (key.length > 1 && key.endsWith('/')) add(errors, `route key must not end with "/": ${key}`);
@@ -316,10 +641,12 @@ export function validateSeoManifest(manifest, options = {}) {
       continue;
     }
 
-    if (entry.title && String(entry.title).length > titleLimit) {
+    checkTranslations(entry, key);
+
+    if (typeof entry.title === 'string' && entry.title.length > titleLimit) {
       add(warnings, `title longer than ${titleLimit} chars: ${key}`);
     }
-    if (entry.description && String(entry.description).length > descriptionLimit) {
+    if (typeof entry.description === 'string' && entry.description.length > descriptionLimit) {
       add(warnings, `description longer than ${descriptionLimit} chars: ${key}`);
     }
 
@@ -335,6 +662,22 @@ export function validateSeoManifest(manifest, options = {}) {
     if (indexable && entry.sitemap === false) {
       add(warnings, `indexable page excluded from the sitemap: ${key}`);
     }
+
+    if (isPattern(key) && entry.sitemap && typeof entry.sitemap === 'object' && Array.isArray(entry.sitemap.paths)) {
+      const names = [...key.matchAll(/\$\{([^}]+)\}/g)].map((match) => match[1]);
+      for (const value of entry.sitemap.paths) {
+        const params = typeof value === 'string' ? { [names[0]]: value } : value;
+        if (!params || typeof params !== 'object') {
+          add(errors, `sitemap.paths entry must be a string or an object: ${key}`);
+          continue;
+        }
+        for (const name of names) {
+          if (params[name] === undefined || params[name] === null || params[name] === '') {
+            add(errors, `sitemap.paths entry is missing "${name}": ${key}`);
+          }
+        }
+      }
+    }
   }
 
   if (routes) {
@@ -357,16 +700,24 @@ export function validateSeoManifest(manifest, options = {}) {
     // sends for the same path, the tab title changes after hydration — and a
     // crawler that runs JS sees the shorter one. Catch it here, not in production.
     const origin = normalizeOrigin(manifest.origin) || '';
+    const translate = translator?.enabled
+      ? (key, params) => translator.t(translator.defaultLocale, key, params)
+      : null;
     for (const route of (Array.isArray(routes) ? routes : [])) {
       const pathname = typeof route === 'string' ? route : route?.path;
       const metadata = typeof route === 'object' ? route?.metadata : null;
-      if (!pathname || !metadata?.title) continue;
-      const served = resolveMetadata({ pathname, manifest, origin });
-      const client = resolveMetadata({ pathname, manifest: {}, origin, routeMetadata: metadata });
+      if (!pathname || !metadata) continue;
+      checkTranslations(metadata, `routes.js ${pathname}`);
+      if (!metadata.title && !metadata.titleKey) continue;
+      if (metadata.title && typeof metadata.title !== 'string') continue;
+      // A missing titleKey is already an error; comparing it to seo.json would only add noise.
+      if (metadata.titleKey && translator?.enabled && !translator.has(translator.defaultLocale, metadata.titleKey)) continue;
+      const served = resolveMetadata({ pathname, manifest, origin, translate });
+      const client = resolveMetadata({ pathname, manifest: {}, origin, routeMetadata: metadata, translate });
       if (served.title && client.title && served.title !== client.title) {
         add(
           warnings,
-          `route title differs from seo.json: ${pathname} ("${metadata.title}" vs "${served.title}")`
+          `route title differs from seo.json: ${pathname} ("${client.title}" vs "${served.title}")`
         );
       }
     }