@uniweb/build 0.63.4 → 0.64.0

package/src/i18n/records.js

@@ -15,17 +15,25 @@ import { existsSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { DATA_DIR } from '@uniweb/core'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { computeHash } from './hash.js'
 import { loadFreeformRecord } from './freeform.js'
+import { resolveQueriesConfig, resolveRecordSchemas, foundationSchemaJson } from '../site/queries-config.js'
+import { dataKeyTypes, keyOfDefaultRef } from '../uwx/data-key-types.js'
+import { toDataSchemaDeclaration, isProseMirrorField } from '../uwx/data-schema.js'
+import { toDeliveredRecord, contentBodyField, misplacedFields } from '@uniweb/schemas/conform'
+import { resolveDocForLocale } from './merge.js'
+import { extractUnitsFromDoc } from './extract.js'
+import { flatFormRefusal, extractExcerpt } from '../site/query-processor.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 // The heuristic judgement about which strings inside structured data are prose.
 // It lives in its own module because the page lane needs exactly the same
 // answer for a tagged data block's payload — a `label` is prose and an `href`
 // is not, wherever the value came from. Moved rather than copied: two tuned
 // denylists would drift, and drift here is silent.
-import { resolveQueriesConfig, resolveRecordSchemas } from '../site/queries-config.js'
-import { toDeliveredRecord, contentBodyField, misplacedFields } from '@uniweb/schemas/conform'
-import { flatFormRefusal } from '../site/query-processor.js'
-import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import {
   NON_TRANSLATABLE_TYPES,
   HEURISTIC_SKIP_FIELDS,
@@ -156,6 +164,196 @@ function isFieldTranslatable(fieldDef) {
   return 'no'
 }
 
+// ---------------------------------------------------------------------------
+// A record's model — what a push sends it as
+// ---------------------------------------------------------------------------
+
+/**
+ * ⭐ A RECORD WITH A DATA SCHEMA IS TRANSLATED BY THE MODEL A PUSH SENDS IT AS — its schema
+ * lowered by the push's own rule (`uwx/data-schema.js::toDataSchemaDeclaration`), which marks
+ * `localized` exactly the fields that travel per locale: text and rich content — never an enum,
+ * a value format (a URL, an email), a `translatable: false` field, a number, a date, a file or a
+ * reference. So what the static build extracts and translates is what a push carries, field for
+ * field, and what a clone of the site, or the site as a backend serves it, renders.
+ *
+ * ⛔ Until 2026-09-26 the build guessed: a walk over every string, vetoed by the fields of the
+ * schema's single sections — so a `multi` section's enum, and the brief of a record a reference
+ * names, were extracted and translated while a push sent neither.
+ *
+ * @param {Object|null} schema - a normalized data schema
+ * @param {string} ref - the ref it was resolved from
+ * @returns {Object|null} the lowered declaration, or null when there is none
+ */
+function modelOf(schema, ref) {
+  if (!schema) return null
+  try {
+    return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
+  } catch {
+    return null // a schema a push refuses is refused there, and the build keeps its heuristic
+  }
+}
+
+/** The refs of the models a model's references name. */
+function referencedModels(model) {
+  const out = new Set()
+  const walk = (fields) => {
+    for (const field of Object.values(fields || {})) {
+      if (field?.type === 'entity_ref' && typeof field.model === 'string') out.add(field.model)
+      else if (field?.type === 'section') walk(field.fields)
+    }
+  }
+  for (const section of Object.values(model?.sections || {})) walk(section?.fields)
+  return out
+}
+
+/**
+ * Each field of a model that a record holds a value for, in the shape the record is DELIVERED in
+ * (`toDeliveredRecord`): the brief's fields at the top — every field, for a model of one single
+ * section — and each other section under its name, a list of them for a `multiple` one, a nested
+ * section the same way. Calls `visit(holder, name, field, path)` for each.
+ */
+function eachModelField(record, model, visit) {
+  const sections = Object.entries(model?.sections || {})
+  const flat = sections.length === 1 && !sections[0][1]?.multiple
+  for (const [name, section] of sections) {
+    if (flat || section?.brief) eachSectionField(record, section?.fields, '', visit)
+    else eachSectionValue(record?.[name], section, name, visit)
+  }
+}
+
+function eachSectionValue(value, section, path, visit) {
+  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
+  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
+}
+
+function eachSectionField(holder, fields, path, visit) {
+  if (!isPlainObject(holder)) return
+  for (const [name, field] of Object.entries(fields || {})) {
+    if (holder[name] == null || isRecordSystemField(name, !path)) continue
+    const at = path ? `${path}.${name}` : name
+    if (field?.type === 'section') eachSectionValue(holder[name], field, at, visit)
+    else visit(holder, name, field || {}, at)
+  }
+}
+
+/** The fields of a model's brief — what a reference to one of its records is delivered as. */
+function briefFields(model) {
+  const sections = Object.values(model?.sections || {})
+  const brief = sections.find((s) => s?.brief) ?? (sections.length === 1 && !sections[0]?.multiple ? sections[0] : null)
+  return brief?.fields ?? null
+}
+
+/** A markdown string as a ProseMirror document, or null. */
+function parseMarkdown(markdown) {
+  try {
+    const doc = markdownToProseMirror(markdown)
+    return isProseMirrorDoc(doc) ? doc : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A record's units by its model: each localized field's value, a rich one element by element as
+ * a push sends it — and none from a reference, whose record makes its own.
+ *
+ * @param {Set<string>|null} skip - fields of the record's own level to leave out (`EXCERPT`)
+ */
+function extractByModel(item, model, context, units, skip = null) {
+  eachModelField(item, model, (holder, name, field, path) => {
+    if (!field.localized || (holder === item && skip?.has(name))) return
+    const value = holder[name]
+    if (isProseMirrorField(field)) {
+      const doc = typeof value === 'string' ? parseMarkdown(value) : value
+      if (isProseMirrorDoc(doc)) extractFromProseMirrorDoc(doc, context, units, path)
+    } else if (typeof value === 'string') {
+      if (value.trim()) addUnit(units, value, path, context)
+    } else if (Array.isArray(value)) {
+      value.forEach((v, i) => {
+        if (typeof v === 'string' && v.trim()) addUnit(units, v, `${path}[${i}]`, context)
+      })
+    }
+  })
+}
+
+// A reference inside a reference's brief is delivered as its handle, not hydrated — this only bounds the walk.
+const MAX_REFERENCE_DEPTH = 4
+
+/**
+ * A record translated by its model (`extractByModel`'s rule) — and each reference's brief by the
+ * model it names, as the record it names is translated, and served, on its own.
+ */
+function translateByModel(item, model, context, translations, targets, skip = null) {
+  const out = structuredClone(item)
+  eachModelField(out, model, (holder, name, field) => {
+    if (holder === out && skip?.has(name)) return
+    holder[name] = translateFieldValue(holder[name], field, context, translations, targets, 0)
+  })
+  return out
+}
+
+function translateFieldValue(value, field, context, translations, targets, depth) {
+  if (field.type === 'entity_ref') {
+    const fields = briefFields(targets?.get(field.model))
+    if (!fields || depth >= MAX_REFERENCE_DEPTH) return value
+    const one = (ref) => {
+      if (!isPlainObject(ref) || !isPlainObject(ref.brief)) return ref
+      const brief = { ...ref.brief }
+      eachSectionField(brief, fields, '', (holder, name, f) => {
+        holder[name] = translateFieldValue(holder[name], f, context, translations, targets, depth + 1)
+      })
+      return { ...ref, brief }
+    }
+    return Array.isArray(value) ? value.map(one) : one(value)
+  }
+  if (!field.localized) return value
+  if (isProseMirrorField(field)) {
+    if (isProseMirrorDoc(value)) return translateProseMirrorDoc(value, context, translations)
+    // Written as markdown: translated as a push sends it, element by element, and kept markdown.
+    const doc = typeof value === 'string' ? parseMarkdown(value) : null
+    if (!doc) return value
+    const translated = translateProseMirrorDoc(doc, context, translations)
+    return JSON.stringify(translated) === JSON.stringify(doc) ? value : proseMirrorToMarkdown(translated)
+  }
+  if (typeof value === 'string') return lookupTranslation(value, context, translations)
+  if (Array.isArray(value)) return value.map((v) => (typeof v === 'string' ? lookupTranslation(v, context, translations) : v))
+  return value
+}
+
+// ---------------------------------------------------------------------------
+// A derived excerpt
+// ---------------------------------------------------------------------------
+
+/**
+ * ⭐ AN EXCERPT THE BUILD DERIVES IS DERIVED IN EVERY LANGUAGE. A record whose author wrote no
+ * excerpt gets one from its body on the static lane (`site/query-processor.js::extractExcerpt`),
+ * and a push sends none — it is not the author's. So it is no unit to translate: each locale's is
+ * derived again, by the same rule, from that locale's body. ⛔ Until 2026-09-26 it was offered for
+ * translation like authored text — a translation no push carries, so a clone showed it in the
+ * source language — and left untranslated, it summarized a translated body in the source language.
+ */
+const EXCERPT = new Set(['excerpt'])
+
+/** A record's body as a document — where its schema's content body field is, else `content`. */
+function bodyDocOf(record, dataSchema) {
+  const target = dataSchema ? contentBodyField(dataSchema) : null
+  const holder = target?.section ? record?.[target.section] : record
+  const value = target ? holder?.[target.key] : record?.content
+  if (isProseMirrorDoc(value)) return value
+  return typeof value === 'string' && value.trim() ? parseMarkdown(value) : null
+}
+
+/** The excerpt the build derives for a record — from `whole`, the record with its body. */
+function derivedExcerptOf(whole, dataSchema, config) {
+  return extractExcerpt({ ...whole, excerpt: undefined }, bodyDocOf(whole, dataSchema), config)
+}
+
+/** Whether a record's excerpt is the one the build derives, not one its author wrote. */
+function derivesExcerpt(record, whole, dataSchema, config) {
+  if (typeof record?.excerpt !== 'string' || !record.excerpt || !config) return false
+  return derivedExcerptOf(whole ?? record, dataSchema, config) === record.excerpt
+}
+
 /**
  * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
  * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
@@ -293,13 +491,16 @@ function extractFromItemWithSchema(data, fields, pathPrefix, context, units) {
 // ---------------------------------------------------------------------------
 
 /**
- * Extract translatable fields from an item using heuristics.
- * Recursively walks the data, extracting strings that look like human-readable text.
+ * Extract translatable fields from an item using heuristics — a record with no data schema, which
+ * says nothing of its fields. Recursively walks the data, extracting strings that look like
+ * human-readable text.
+ *
+ * @param {Set<string>|null} skip - fields of the record's own level to leave out (`EXCERPT`)
  */
-function extractHeuristic(item, recordDir, units) {
+function extractHeuristic(item, recordDir, units, skip = null) {
   const context = { record: `${recordDir}/${recordHandle(item)}` }
 
-  extractFromItemHeuristic(item, '', context, units, 0)
+  extractFromItemHeuristic(item, '', context, units, 0, skip)
 
   // Also extract the record's ProseMirror documents, wherever it holds them
   for (const { path, doc } of proseMirrorDocs(item)) extractFromProseMirrorDoc(doc, context, units, path)
@@ -308,7 +509,7 @@ function extractHeuristic(item, recordDir, units) {
 /**
  * Recursively extract strings that look translatable.
  */
-function extractFromItemHeuristic(data, pathPrefix, context, units, depth) {
+function extractFromItemHeuristic(data, pathPrefix, context, units, depth, skip = null) {
   if (!data || typeof data !== 'object' || depth > MAX_HEURISTIC_DEPTH) return
 
   const entries = Array.isArray(data)
@@ -323,6 +524,7 @@ function extractFromItemHeuristic(data, pathPrefix, context, units, depth) {
 
     if (value === undefined || value === null) continue
     if (!Array.isArray(data) && isRecordSystemField(key, depth === 0)) continue
+    if (depth === 0 && skip?.has(key)) continue
 
     // Skip a ProseMirror document (handled separately)
     if (isProseMirrorDoc(value)) continue
@@ -405,16 +607,16 @@ function translateItemWithSchema(data, fields, context, translations, topLevel =
 /**
  * Translate item fields using heuristics.
  */
-function translateHeuristic(item, context, translations) {
+function translateHeuristic(item, context, translations, skip = null) {
   const translated = translateDocs(item, context, translations)
-  translateItemHeuristic(translated, context, translations, 0)
+  translateItemHeuristic(translated, context, translations, 0, skip)
   return translated
 }
 
 /**
  * Recursively translate strings that look translatable.
  */
-function translateItemHeuristic(data, context, translations, depth) {
+function translateItemHeuristic(data, context, translations, depth, skip = null) {
   if (!data || typeof data !== 'object' || depth > MAX_HEURISTIC_DEPTH) return
 
   const keys = Array.isArray(data)
@@ -425,6 +627,7 @@ function translateItemHeuristic(data, context, translations, depth) {
     const value = data[key]
     if (value === undefined || value === null) continue
     if (!Array.isArray(data) && isRecordSystemField(key, depth === 0)) continue
+    if (depth === 0 && skip?.has(key)) continue
 
     // Skip a ProseMirror document (translated separately)
     if (isProseMirrorDoc(value)) continue
@@ -463,30 +666,86 @@ async function poolDirsByQuery(siteRoot) {
 }
 
 /**
- * Each query's pool directory (`poolDirsByQuery`) and the data schema its records are
- * delivered in (`resolveRecordSchemas`, null for none) — what a free-form translation
- * needs to put a body and frontmatter where the delivered record holds them.
+ * What the localized build needs to know of each query:
+ *
+ * - `poolDirs` — its pool directory (`poolDirsByQuery`), which a record's translations are keyed by;
+ * - `schemas` — the data schema its records are DELIVERED in (`resolveRecordSchemas`, null for
+ *   none), which says where a free-form body and frontmatter go, and where the body is;
+ * - `models` — the model its records are pushed as (`modelOf`), which says which of their fields
+ *   are translated; `targets` — the model each reference names, by its ref, transitively;
+ * - `excerpts` — its excerpt settings, which derive an excerpt (`EXCERPT`).
+ *
+ * ⭐ THE MODEL IS THE TYPE THE RECORDS ARE OF, which is not always the schema they are delivered
+ * in. A query whose name-defaulted schema (`@/team`) no data schema answers, for a data key the
+ * foundation types (`data: { team: '@/member' }`), holds records of that type — a push sends them
+ * as its entities (`uwx/data-key-types.js`) — while the build delivers them as they are written.
+ * The type is read from the foundation's built `schema.json`, the input a push reads it from.
  *
- * @returns {Promise<{ poolDirs: Map<string, string>, schemas: Map<string, Object|null> }>}
+ * @returns {Promise<{ poolDirs: Map<string, string>, schemas: Map<string, Object|null>, models: Map<string, Object|null>, targets: Map<string, Object|null>, excerpts: Map<string, Object> }>}
  */
 async function recordQueries(siteRoot) {
   const poolDirs = new Map()
   const schemas = new Map()
+  const models = new Map()
+  const targets = new Map()
+  const excerpts = new Map()
   try {
-    const { declarations } = await resolveQueriesConfig(siteRoot)
+    const siteYml = await readSiteYml(siteRoot)
+    const { declarations } = await resolveQueriesConfig(siteRoot, { siteYml })
     const entries = Object.entries(declarations || {})
     for (const [name, decl] of entries) {
       const dirs = decl.schema ? poolDirsForSchema(decl.schema) : null
       poolDirs.set(name, dirs ? dirs.join('/') : name)
+      // As `site/query-processor.js` parses a query's `excerpt:`.
+      excerpts.set(name, { maxLength: decl.excerpt?.maxLength || 160, field: decl.excerpt?.field || null })
     }
-    const refs = entries.filter(([, d]) => d.url === undefined && d.schema).map(([, d]) => d.schema)
-    const resolved = (await resolveRecordSchemas(siteRoot, refs)).schemas
+    const local = entries.filter(([, d]) => d.url === undefined && d.schema)
+    const resolved = (await resolveRecordSchemas(siteRoot, local.map(([, d]) => d.schema), { siteYml })).schemas
     for (const [name, decl] of entries) schemas.set(name, (decl.schema && resolved[decl.schema]) || null)
+
+    const keyTyped = new Map() // query name → the type of the data key it is named for
+    const untyped = local.filter(([, d]) => !d.schemaExplicit && !resolved[d.schema])
+    if (untyped.length) {
+      const keyTypes = dataKeyTypes(foundationSchemaJson(siteRoot, siteYml))
+      for (const [name, d] of untyped) {
+        const type = keyTypes.get(keyOfDefaultRef(d.schema))
+        if (type) keyTyped.set(name, type)
+      }
+    }
+    const types = keyTyped.size ? (await resolveRecordSchemas(siteRoot, keyTyped.values(), { siteYml })).schemas : {}
+    for (const [name, decl] of entries) {
+      const type = keyTyped.get(name)
+      models.set(name, schemas.get(name) ? modelOf(schemas.get(name), decl.schema) : type ? modelOf(types[type], type) : null)
+    }
+
+    // The models the records' references name, and the ones theirs name.
+    let pending = [...new Set([...models.values()].flatMap((m) => [...referencedModels(m)]))]
+    while (pending.length) {
+      const got = (await resolveRecordSchemas(siteRoot, pending, { siteYml })).schemas
+      const next = new Set()
+      for (const ref of pending) {
+        const model = modelOf(got[ref], ref)
+        targets.set(ref, model)
+        for (const r of referencedModels(model)) if (!targets.has(r) && !pending.includes(r)) next.add(r)
+      }
+      pending = [...next]
+    }
   } catch {
     // No resolvable config — every record keys by its query name, which is what
     // the extractor did before records existed.
   }
-  return { poolDirs, schemas }
+  return { poolDirs, schemas, models, targets, excerpts }
+}
+
+/** A site's `site.yml`, or `{}`. */
+async function readSiteYml(siteRoot) {
+  const path = join(siteRoot, 'site.yml')
+  if (!existsSync(path)) return {}
+  try {
+    return yaml.load(await readFile(path, 'utf-8'), YAML_OPTIONS) || {}
+  } catch {
+    return {}
+  }
 }
 
 
@@ -504,7 +763,7 @@ export async function extractRecordContent(siteRoot, options = {}) {
   }
 
   const units = {}
-  const poolDirs = await poolDirsByQuery(siteRoot)
+  const { poolDirs, schemas: dataSchemas, models, excerpts } = await recordQueries(siteRoot)
 
   let files
   try {
@@ -528,28 +787,26 @@ export async function extractRecordContent(siteRoot, options = {}) {
       // Resolve schema once per collection
       const schema = await resolveSchema(queryName, siteRoot)
       const recordDir = poolDirs.get(queryName) ?? queryName
+      const model = models.get(queryName) ?? null
+      // ⭐ AND THE QUERY'S PER-RECORD FILES. A query with `deferred:` fields writes each
+      // record whole beside its lean list, and a deferred field is exactly what the list
+      // does not hold. ⛔ Until 2026-09-14 only the list was read, so a deferred body —
+      // one derived from a schema's brief included — never reached the manifest.
+      const wholes = await wholeRecords(dataDir, queryName)
       const extract = (item) => {
-        if (schema?.fields) {
+        const whole = wholes.get(recordHandle(item))
+        const skip = derivesExcerpt(item, whole, dataSchemas.get(queryName), excerpts.get(queryName)) ? EXCERPT : null
+        if (model) {
+          extractByModel(item, model, { record: `${recordDir}/${recordHandle(item)}` }, units, skip)
+        } else if (schema?.fields) {
           extractWithSchema(item, schema, recordDir, units)
         } else {
-          extractHeuristic(item, recordDir, units)
+          extractHeuristic(item, recordDir, units, skip)
         }
       }
 
       for (const item of items) extract(item)
-
-      // ⭐ AND THE QUERY'S PER-RECORD FILES. A query with `deferred:` fields writes each
-      // record whole beside its lean list, and a deferred field is exactly what the list
-      // does not hold. ⛔ Until 2026-09-14 only the list was read, so a deferred body —
-      // one derived from a schema's brief included — never reached the manifest.
-      for (const name of await recordFileNames(dataDir, queryName)) {
-        try {
-          const item = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
-          if (item && typeof item === 'object' && !Array.isArray(item)) extract(item)
-        } catch (err) {
-          console.warn(`[i18n] Skipping ${queryName}/${name}: ${err.message}`)
-        }
-      }
+      for (const item of wholes.values()) extract(item)
     } catch (err) {
       // Skip files that can't be parsed
       console.warn(`[i18n] Skipping ${file}: ${err.message}`)
@@ -585,6 +842,24 @@ async function recordFileNames(dataDir, queryName) {
   }
 }
 
+/**
+ * A query's per-record files (`recordFileNames`), each record whole, by its handle.
+ *
+ * @returns {Promise<Map<string, Object>>}
+ */
+async function wholeRecords(dataDir, queryName) {
+  const out = new Map()
+  for (const name of await recordFileNames(dataDir, queryName)) {
+    try {
+      const record = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+      if (isPlainObject(record)) out.set(recordHandle(record), record)
+    } catch (err) {
+      console.warn(`[i18n] Skipping ${queryName}/${name}: ${err.message}`)
+    }
+  }
+  return out
+}
+
 /** Is `path` strictly inside `dir`? A name read off disk must not lead out of it. */
 function isInside(path, dir) {
   return resolve(path).startsWith(resolve(dir) + sep)
@@ -614,61 +889,12 @@ async function pruneRecordFiles(recordsDir, dataDir, keep) {
  * (`content`, `article_body.content`), which each unit's `field` starts with.
  */
 function extractFromProseMirrorDoc(doc, context, units, field = 'content') {
-  if (!doc.content) return
-
-  let headingIndex = 0
-  let paragraphIndex = 0
-
-  for (const node of doc.content) {
-    if (node.type === 'heading') {
-      const text = extractTextFromNode(node)
-      if (text) {
-        addUnit(units, text, `${field}.heading.${headingIndex}`, context)
-        headingIndex++
-      }
-    } else if (node.type === 'paragraph') {
-      const text = extractTextFromNode(node)
-      if (text) {
-        addUnit(units, text, `${field}.paragraph.${paragraphIndex}`, context)
-        paragraphIndex++
-      }
-    } else if (node.type === 'bulletList' || node.type === 'orderedList') {
-      extractFromList(node, context, units, field)
-    }
-  }
+  // The units a page section's body makes (`extract.js::extractUnitsFromDoc`) — the keys translation
+  // looks up — each under the field the record holds the body in.
+  for (const unit of Object.values(extractUnitsFromDoc(doc))) addUnit(units, unit.source, `${field}.${unit.field}`, context)
 }
 
-/**
- * Extract from list nodes
- */
-function extractFromList(listNode, context, units, field = 'content') {
-  if (!listNode.content) return
-
-  listNode.content.forEach((listItem, index) => {
-    if (listItem.type === 'listItem' && listItem.content) {
-      for (const child of listItem.content) {
-        if (child.type === 'paragraph') {
-          const text = extractTextFromNode(child)
-          if (text) {
-            addUnit(units, text, `${field}.list.${index}`, context)
-          }
-        }
-      }
-    }
-  })
-}
 
-/**
- * Extract text content from a node
- */
-function extractTextFromNode(node) {
-  if (!node.content) return ''
-  return node.content
-    .filter(n => n.type === 'text')
-    .map(n => n.text || '')
-    .join('')
-    .trim()
-}
 
 // ---------------------------------------------------------------------------
 // Unit accumulator
@@ -743,7 +969,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
   // simply miss and every string falls back to its source. (This was missing for
   // a while and the failure was swallowed by the per-file catch below — the build
   // stayed green while nothing was translated.)
-  const { poolDirs, schemas: dataSchemas } = await recordQueries(siteRoot)
+  const { poolDirs, schemas: dataSchemas, models, targets, excerpts } = await recordQueries(siteRoot)
 
   const outputs = {}
   // Reported rather than only logged — see the catch below.
@@ -790,23 +1016,15 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         // Resolve schema once per collection
         const schema = await resolveSchema(queryName, siteRoot)
         const recordDir = poolDirs.get(queryName) ?? queryName
-        const dataSchema = dataSchemas.get(queryName) ?? null
-
-        // Translate each item (with free-form support)
-        const translatedItems = await Promise.all(
-          items.map(item =>
-            translateItemAsync(item, recordDir, translations, schema, {
-              locale,
-              localesDir,
-              freeformEnabled: hasFreeform,
-              dataSchema
-            })
-          )
-        )
-
-        const destPath = join(localeDataDir, file)
-        await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
-        outputs[locale][queryName] = destPath
+        const recordOptions = {
+          locale,
+          localesDir,
+          freeformEnabled: hasFreeform,
+          dataSchema: dataSchemas.get(queryName) ?? null,
+          model: models.get(queryName) ?? null,
+          targets,
+          excerpt: excerpts.get(queryName),
+        }
 
         // ⭐ AND THE QUERY'S PER-RECORD FILES, beside the translated list and with the
         // same translations — `/<locale>/data/<query>/<slug>.json`. A query with
@@ -814,14 +1032,18 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         // its record from that file. ⛔ Until 2026-09-14 they were not written for any
         // locale, so a localized site's records showed their deferred fields — an
         // article's body — in the source language under a translated list.
+        // They are translated first: a lean list's derived excerpt is derived from its record's
+        // translated body (`EXCERPT`).
         const localeRecordsDir = join(localeDataDir, queryName)
         const recordNames = await recordFileNames(dataDir, queryName)
+        const wholes = new Map() // handle → { source, translated }
         for (const name of recordNames) {
           try {
             const record = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
-            const translatedRecord = record && typeof record === 'object' && !Array.isArray(record)
-              ? await translateItemAsync(record, recordDir, translations, schema, { locale, localesDir, freeformEnabled: hasFreeform, dataSchema })
+            const translatedRecord = isPlainObject(record)
+              ? await translateItemAsync(record, recordDir, translations, schema, recordOptions)
               : record
+            if (isPlainObject(record)) wholes.set(recordHandle(record), { source: record, translated: translatedRecord })
             await mkdir(localeRecordsDir, { recursive: true })
             await writeFile(join(localeRecordsDir, name), JSON.stringify(translatedRecord, null, 2))
           } catch (err) {
@@ -831,6 +1053,17 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         }
         // A record file the source no longer has is not left behind, translated, in the locale.
         await pruneRecordFiles(localeRecordsDir, localeDataDir, new Set(recordNames))
+
+        // Translate each item (with free-form support)
+        const translatedItems = await Promise.all(
+          items.map((item) =>
+            translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) })
+          )
+        )
+
+        const destPath = join(localeDataDir, file)
+        await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
+        outputs[locale][queryName] = destPath
       } catch (err) {
         // ⛔ A FAILURE HERE USED TO BE A `console.warn` AND NOTHING ELSE, and it
         // hid a real bug for the length of a session: a `ReferenceError` in this
@@ -859,17 +1092,29 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
  * Apply translations to a collection item (async, with free-form support)
  *
  * The hash-based translations apply first — every field and every ProseMirror document
- * (schema-guided or heuristic) — and a free-form translation then replaces what it
- * states (`applyFreeform`): its frontmatter, its body, or both.
+ * the record's model says is translated (`translateItemSync`) — and a free-form translation
+ * then replaces what it states (`applyFreeform`): its frontmatter, its body, or both. A
+ * derived excerpt is then derived from the translated body (`EXCERPT`).
  *
  * @param {Object} [options.dataSchema] - the data schema the record is delivered in
  *   (`recordQueries`), which says where a free-form body and frontmatter go
+ * @param {Object} [options.model] - the model the record is pushed as, and `targets`, the models
+ *   its references name (`recordQueries`) — which fields are translated
+ * @param {Object} [options.excerpt] - the query's excerpt settings (`EXCERPT`)
+ * @param {{ source: Object, translated: Object }} [options.whole] - for an item of a lean list, its
+ *   record whole and translated, whose body a derived excerpt is derived from
  */
 async function translateItemAsync(item, recordDir, translations, schema, options = {}) {
-  const { locale, localesDir, freeformEnabled, dataSchema = null } = options
-  const translated = translateItemSync(item, recordDir, translations, schema)
-  if (!freeformEnabled || !locale || !localesDir) return translated
+  const { locale, localesDir, freeformEnabled, dataSchema = null, model = null, targets = null, excerpt = null, whole = null } = options
+  const derived = derivesExcerpt(item, whole?.source, dataSchema, excerpt)
+  let translated = translateItemSync(item, recordDir, translations, schema, { model, targets, skip: derived ? EXCERPT : null })
+  if (freeformEnabled && locale && localesDir) translated = await applyFreeformFile(translated, item, recordDir, locale, localesDir, dataSchema)
+  if (!derived) return translated
+  return { ...translated, excerpt: derivedExcerptOf(whole ? whole.translated : translated, dataSchema, excerpt) }
+}
 
+/** The record with its free-form translation for `locale` applied, if it has one. */
+async function applyFreeformFile(translated, item, recordDir, locale, localesDir, dataSchema) {
   // ⛔ The loader takes the record's SCHEMA ref and derives the pool path from it
   // (`buildFreeformRecordPath`); handed the pool directory itself (`article`), it
   // derived nothing and found no file — so until 2026-09-14 no free-form record
@@ -922,16 +1167,18 @@ function isPlainObject(value) {
 }
 
 /**
- * Apply translations to a collection item (sync, hash-based only)
+ * Apply translations to a collection item (sync, hash-based only) — by the model it is pushed as
+ * when it has one (`translateByModel`), else a companion schema's fields, else the heuristic.
  */
-function translateItemSync(item, recordDir, translations, schema) {
-  const translated = { ...item }
+function translateItemSync(item, recordDir, translations, schema, { model = null, targets = null, skip = null } = {}) {
   const context = { record: `${recordDir}/${recordHandle(item)}` }
 
+  if (model) return translateByModel(item, model, context, translations, targets, skip)
+  const translated = { ...item }
   if (schema?.fields) {
     return translateWithSchema(translated, schema, context, translations)
   }
-  return translateHeuristic(translated, context, translations)
+  return translateHeuristic(translated, context, translations, skip)
 }
 
 // ---------------------------------------------------------------------------
@@ -942,35 +1189,11 @@ function translateItemSync(item, recordDir, translations, schema) {
  * Translate a ProseMirror document
  */
 function translateProseMirrorDoc(doc, context, translations) {
-  if (!doc.content) return doc
-
-  const translated = { ...doc, content: [] }
-
-  for (const node of doc.content) {
-    translated.content.push(translateNode(node, context, translations))
-  }
-
-  return translated
-}
-
-/**
- * Recursively translate a node
- */
-function translateNode(node, context, translations) {
-  if (!node.content) return node
-
-  const translated = { ...node, content: [] }
-
-  for (const child of node.content) {
-    if (child.type === 'text' && child.text) {
-      const translatedText = lookupTranslation(child.text, context, translations)
-      translated.content.push({ ...child, text: translatedText })
-    } else {
-      translated.content.push(translateNode(child, context, translations))
-    }
-  }
-
-  return translated
+  // ⭐ Element by element, by the rule a page section is translated by (`merge.js`) — keyed by the
+  // record's identity for an override. ⛔ Until 2026-09-26 a record's rich text was looked up text node
+  // by text node, so a paragraph holding a link or an emphasis — several text nodes — never matched its
+  // translation, which is keyed by the whole paragraph, and rendered untranslated.
+  return resolveDocForLocale(doc, translations, { key: context.record }) ?? doc
 }
 
 /**
@@ -1041,23 +1264,28 @@ export async function translateRecordData(items, queryName, siteRoot, options =
   const records = one ? [items] : items
 
   const schema = await resolveSchema(queryName, siteRoot)
-  const { poolDirs, schemas: dataSchemas } = await recordQueries(siteRoot)
+  const { poolDirs, schemas: dataSchemas, models, targets, excerpts } = await recordQueries(siteRoot)
   const recordDir = poolDirs.get(queryName) ?? queryName
+  const recordOptions = {
+    locale,
+    localesDir,
+    freeformEnabled,
+    dataSchema: dataSchemas.get(queryName) ?? null,
+    model: models.get(queryName) ?? null,
+    targets,
+    excerpt: excerpts.get(queryName),
+  }
 
-  const translated = freeformEnabled
-    ? await Promise.all(
-        records.map(item =>
-          translateItemAsync(item, recordDir, translations, schema, {
-            locale,
-            localesDir,
-            freeformEnabled,
-            dataSchema: dataSchemas.get(queryName) ?? null
-          })
-        )
-      )
-    : records.map(item =>
-        translateItemSync(item, recordDir, translations, schema)
-      )
+  // A lean list's derived excerpt is derived from its record's translated body (`EXCERPT`).
+  const wholes = new Map()
+  if (!one) {
+    for (const [handle, record] of await wholeRecords(join(siteRoot, 'public', DATA_DIR), queryName)) {
+      wholes.set(handle, { source: record, translated: await translateItemAsync(record, recordDir, translations, schema, recordOptions) })
+    }
+  }
+  const translated = await Promise.all(
+    records.map((item) => translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) }))
+  )
 
   return one ? translated[0] : translated
 }