@uniweb/build 0.75.0 → 0.75.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.75.0",
+  "version": "0.75.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.8",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.13",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/content-reader": "^1.2.8",
     "@uniweb/schemas": "^0.10.2",
-    "@uniweb/theming": "^0.2.0",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.28.10"
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.36.0",
-    "@uniweb/runtime": "^0.28.10"
+    "@uniweb/runtime": "^0.28.10",
+    "@uniweb/core": "^0.36.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/data-models.js

@@ -0,0 +1,77 @@
+/**
+ * ⭐ WHAT A SECTION TYPE SAYS ITS DATA BLOCKS ARE. A tagged data block (```yaml:logos) feeds the
+ * data key of its tag, and the section's type declares that key in its `meta.js` `data:` — a data
+ * schema ref (`'@/member'`), an inline field map (`{ name: 'string', style: { type: 'string', enum:
+ * [...] } }`), or nothing said (`{}`). The foundation's `main.js` `data:` reaches every section, and
+ * a key both declare is the section type's (`@uniweb/core/data-keys::declaredKeys`).
+ *
+ * This is the model of each declared shape, lowered by the push's own rule (`records.js::modelOf`),
+ * so the fields a block translates are the ones its model marks `localized`
+ * (`data-strings.js::visitDataBlockStrings`). Every form of a declaration is read by the one
+ * normalizer (`@uniweb/schemas/foundation::normalizeData`); a ref resolves as a query's records
+ * resolve theirs (`resolveRecordSchemas`). A key with no shape, or a ref that does not resolve, has
+ * no model, and its blocks keep the heuristic.
+ */
+import { normalizeData } from '@uniweb/schemas/foundation'
+import { foundationSections, resolveRecordSchemas } from '../site/queries-config.js'
+import { modelOf } from './records.js'
+
+/** The lookup when there is no foundation to ask: every block keeps the heuristic. */
+export const NO_DATA_MODELS = () => null
+
+/**
+ * The lookup for a site: `(sectionType, tag) => model | null`.
+ *
+ * @param {string} siteRoot
+ * @param {object} [siteYml] - an already-read site.yml
+ * @returns {Promise<(type: string, tag: string) => object|null>}
+ */
+export async function dataBlockModels(siteRoot, siteYml = null) {
+  let sections
+  try {
+    sections = await foundationSections(siteRoot, siteYml)
+  } catch {
+    return NO_DATA_MODELS
+  }
+  if (!sections || typeof sections !== 'object') return NO_DATA_MODELS
+
+  // Each declared key, by who declares it: a section type by name, the foundation as ''.
+  const declared = new Map()
+  const declare = (owner, data) => {
+    const normalized = normalizeData(data, { strict: false })
+    for (const [key, decl] of Object.entries(normalized || {})) declared.set(at(owner, key), decl)
+  }
+  for (const [name, entry] of Object.entries(sections)) {
+    if (!entry || typeof entry !== 'object' || name === 'dataSchemas' || name === '_layouts') continue
+    if (name === '_self') declare('', entry.data)
+    else if (!name.startsWith('_')) declare(name, entry.data)
+  }
+  if (!declared.size) return NO_DATA_MODELS
+
+  const refs = [...declared.values()].filter((d) => d.kind === 'schema').map((d) => d.schema)
+  let resolved = {}
+  if (refs.length) {
+    try {
+      resolved = (await resolveRecordSchemas(siteRoot, refs, { siteYml })).schemas || {}
+    } catch {
+      resolved = {}
+    }
+  }
+
+  const models = new Map()
+  for (const [where, decl] of declared) {
+    if (decl.kind === 'schema') models.set(where, modelOf(resolved[decl.schema] || null, decl.schema))
+    else if (decl.kind === 'fields') {
+      const { kind: _kind, problems: _problems, ...schema } = decl
+      models.set(where, modelOf(schema, '@/inline'))
+    } else models.set(where, null)
+  }
+
+  return (type, tag) => {
+    if (!tag) return null
+    if (type && models.has(at(type, tag))) return models.get(at(type, tag)) || null
+    return models.get(at('', tag)) || null
+  }
+}
+
+const at = (owner, key) => `${owner}\u0000${key}`

package/src/i18n/data-strings.js

@@ -19,6 +19,8 @@
  * missed field shows up as untranslated content nobody notices.
  */
 
+import { visitModelStrings } from './model-fields.js'
+
 /** Types that are never translatable regardless of schema. */
 export const NON_TRANSLATABLE_TYPES = new Set([
   'number', 'boolean', 'date', 'datetime', 'url', 'email', 'image'
@@ -112,3 +114,28 @@ export function visitDataStrings(data, visit, path = '', depth = 0) {
     // numbers and booleans are never prose
   }
 }
+
+/**
+ * ⭐ A TAGGED DATA BLOCK'S STRINGS, BY ITS DECLARED SHAPE WHEN IT HAS ONE. A section type that
+ * declares the shape of the key a block is tagged with — `data: { logos: { name: 'string', style:
+ * { type: 'string', enum: [...] } } }`, or a data schema ref — says which of its fields are text,
+ * and that is what is walked: the fields its model marks `localized`, the push's own rule
+ * (`model-fields.js`). An enum, a URL, a `translatable: false` field is never offered, whatever its
+ * name. A block whose key declares no shape (`{}`, or no declaration) keeps the heuristic above.
+ *
+ * ⛔ Until 2026-10-02 every block was walked by the heuristic, so a field the heuristic does not know
+ * — a `style: display-black` naming one of a component's looks — was offered for translation, and
+ * a translated one quietly fell back to the component's default look.
+ *
+ * One rule for the four places that walk a block — extraction, the build's merge, the push and the
+ * pull — so a string extracted is a string translated, and a translation pushed is one read back.
+ *
+ * @param {object|Array} data - the block's value: a list of items, or one
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {object|null} [model] - the block's lowered model (`data-models.js`), or null
+ */
+export function visitDataBlockStrings(data, visit, model = null) {
+  if (!model) return visitDataStrings(data, visit)
+  if (Array.isArray(data)) data.forEach((item, i) => visitModelStrings(item, model, visit, `[${i}]`))
+  else visitModelStrings(data, model, visit)
+}

package/src/i18n/extract.js

@@ -7,7 +7,7 @@
 
 import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
-import { visitDataStrings } from './data-strings.js'
+import { visitDataBlockStrings } from './data-strings.js'
 
 // ProseMirror inline fragment → inline markdown, for the TRANSLATOR-FACING half of
 // a unit. Same lazy-import-with-fallback pattern as merge.js, so the synchronous
@@ -25,9 +25,13 @@ try {
 /**
  * Extract all translatable units from site content
  * @param {Object} siteContent - Parsed site-content.json
+ * @param {Object} [options]
+ * @param {(type: string, tag: string) => Object|null} [options.dataModel] - what each section type
+ *   declares its data blocks are (`data-models.js::dataBlockModels`); without it, every block is
+ *   walked by the heuristic
  * @returns {Object} Manifest with translation units
  */
-export function extractTranslatableContent(siteContent) {
+export function extractTranslatableContent(siteContent, { dataModel = null } = {}) {
   const units = {}
 
   // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
@@ -41,7 +45,7 @@ export function extractTranslatableContent(siteContent) {
 
     // Extract section content
     for (const section of page.sections || []) {
-      extractFromSection(section, pageRoute, units)
+      extractFromSection(section, pageRoute, units, dataModel)
     }
   }
 
@@ -51,7 +55,7 @@ export function extractTranslatableContent(siteContent) {
     const pageRoute = notFoundPage.route || '/404'
     extractFromPageMeta(notFoundPage, pageRoute, units)
     for (const section of notFoundPage.sections || []) {
-      extractFromSection(section, pageRoute, units)
+      extractFromSection(section, pageRoute, units, dataModel)
     }
   }
 
@@ -64,7 +68,7 @@ export function extractTranslatableContent(siteContent) {
         if (layoutPage?.sections) {
           const pageRoute = layoutPage.route || `/layout/${layoutName === 'default' ? '' : layoutName + '/'}${areaKey}`
           for (const section of layoutPage.sections) {
-            extractFromSection(section, pageRoute, units)
+            extractFromSection(section, pageRoute, units, dataModel)
           }
         }
       }
@@ -169,7 +173,7 @@ export function translationContext(section, pageRoute) {
  * @param {string} pageRoute - Parent page route
  * @param {Object} units - Units accumulator
  */
-function extractFromSection(section, pageRoute, units) {
+function extractFromSection(section, pageRoute, units, dataModel = null) {
   const context = translationContext(section, pageRoute)
 
   // Extract from parsed semantic content if available
@@ -179,12 +183,12 @@ function extractFromSection(section, pageRoute, units) {
 
   if (section.content?.type === 'doc') {
     extractFromProseMirrorDoc(section.content, context, units)
-    extractFromDataBlocks(section.content, context, units)
+    extractFromDataBlocks(section.content, context, units, (tag) => dataModel?.(section.type, tag) ?? null)
   }
 
   // Recursively process subsections
   for (const subsection of section.subsections || []) {
-    extractFromSection(subsection, pageRoute, units)
+    extractFromSection(subsection, pageRoute, units, dataModel)
   }
 }
 
@@ -214,14 +218,14 @@ function extractFromSection(section, pageRoute, units) {
  * as the same per-string entries this lane writes — the block-element keying
  * contract is untouched.
  */
-function extractFromDataBlocks(doc, context, units) {
+function extractFromDataBlocks(doc, context, units, modelFor = () => null) {
   for (const node of dataBlockNodes(doc)) {
     const { tag, data } = node.attrs || {}
     if (!tag || !data || typeof data !== 'object') continue
 
-    visitDataStrings(data, (value, fieldPath) => {
+    visitDataBlockStrings(data, (value, fieldPath) => {
       addUnit(units, value, `data.${tag}.${fieldPath}`, context)
-    })
+    }, modelFor(tag))
   }
 }
 

package/src/i18n/index.js

@@ -14,6 +14,7 @@ import { join, dirname } from 'node:path'
 import { computeHash, normalizeText } from './hash.js'
 import { availableLocales, resolveLocaleList } from './locales.js'
 import { extractTranslatableContent } from './extract.js'
+import { dataBlockModels } from './data-models.js'
 import { syncManifests, formatSyncReport } from './sync.js'
 import { mergeTranslations, generateAllLocales } from './merge.js'
 import { auditLocale, cleanLocale, formatAuditReport } from './audit.js'
@@ -160,8 +161,8 @@ export async function extractManifest(siteRoot, siteContent, options = {}) {
     dryRun = false
   } = options
 
-  // Extract translatable content
-  const manifest = extractTranslatableContent(siteContent)
+  // Extract translatable content — a data block by what its section type declares it is
+  const manifest = extractTranslatableContent(siteContent, { dataModel: await dataBlockModels(siteRoot) })
 
   // Ensure locales directory exists
   const localesPath = join(siteRoot, localesDir)
@@ -372,6 +373,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
   const defaultLocale = resolveDefaultLocale(siteContent.config)
 
   const outputs = {}
+  // What each section type declares its data blocks are, so a block translates what extraction offered.
+  const dataModel = await dataBlockModels(siteRoot)
 
   // ⭐ The DEFAULT locale's payload needs the same stamp. It is not written in
   // this loop — it is the source this function reads — but a visitor landing on
@@ -420,7 +423,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
         fallbackToSource,
         locale,
         localesDir: localesPath,
-        freeformEnabled: true
+        freeformEnabled: true,
+        dataModel
       })
 
       // Check for stale/orphaned free-form translations and warn
@@ -428,7 +432,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
     } else {
       // Use sync merge (original behavior)
       translated = mergeTranslations(siteContent, translations, {
-        fallbackToSource
+        fallbackToSource,
+        dataModel
       })
     }
 

package/src/i18n/merge.js

@@ -15,7 +15,7 @@
 import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
 import { elementText, blockElements, translationContext, SITE_META_CONTEXT } from './extract.js'
-import { visitDataStrings } from './data-strings.js'
+import { visitDataBlockStrings } from './data-strings.js'
 
 // Inline-markdown → ProseMirror inline fragment, for resolving a whole-element
 // translation VALUE (which carries marks/links/icons as inline markdown). Same
@@ -42,6 +42,9 @@ try {
  * @param {string} [options.locale] - Locale code for free-form lookups
  * @param {string} [options.localesDir] - Path to locales directory
  * @param {boolean} [options.freeformEnabled=false] - Enable free-form translation lookup
+ * @param {(type: string, tag: string) => Object|null} [options.dataModel] - what each section type
+ *   declares its data blocks are (`data-models.js::dataBlockModels`), so a block translates the
+ *   fields extraction offered; without it, every block is walked by the heuristic
  * @returns {Object|Promise<Object>} Translated site content (async if freeformEnabled)
  */
 export function mergeTranslations(siteContent, translations, options = {}) {
@@ -49,7 +52,8 @@ export function mergeTranslations(siteContent, translations, options = {}) {
     fallbackToSource = true,
     locale = null,
     localesDir = null,
-    freeformEnabled = false
+    freeformEnabled = false,
+    dataModel = null
   } = options
 
   // If free-form is enabled, use async version
@@ -57,18 +61,19 @@ export function mergeTranslations(siteContent, translations, options = {}) {
     return mergeTranslationsAsync(siteContent, translations, {
       fallbackToSource,
       locale,
-      localesDir
+      localesDir,
+      dataModel
     })
   }
 
   // Sync version (original behavior)
-  return mergeTranslationsSync(siteContent, translations, fallbackToSource)
+  return mergeTranslationsSync(siteContent, translations, fallbackToSource, dataModel)
 }
 
 /**
  * Synchronous merge (original behavior, no free-form)
  */
-function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
+function mergeTranslationsSync(siteContent, translations, fallbackToSource, dataModel = null) {
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
   translateSiteMeta(translated.config, translations, fallbackToSource)
@@ -81,7 +86,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
 
     // Translate section content
     for (const section of page.sections || []) {
-      translateSectionSync(section, pageRoute, translations, fallbackToSource)
+      translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
     }
   }
 
@@ -90,7 +95,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
     const pageRoute = translated.notFound.route || '/404'
     translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource)
     for (const section of translated.notFound.sections || []) {
-      translateSectionSync(section, pageRoute, translations, fallbackToSource)
+      translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
     }
   }
 
@@ -103,7 +108,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
         if (layoutPage?.sections) {
           const pageRoute = layoutPage.route || `/layout/${layoutName === 'default' ? '' : layoutName + '/'}${areaKey}`
           for (const section of layoutPage.sections) {
-            translateSectionSync(section, pageRoute, translations, fallbackToSource)
+            translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
           }
         }
       }
@@ -117,7 +122,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
  * Asynchronous merge with free-form support
  */
 async function mergeTranslationsAsync(siteContent, translations, options) {
-  const { fallbackToSource, locale, localesDir } = options
+  const { fallbackToSource, locale, localesDir, dataModel } = options
 
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
@@ -134,7 +139,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
       await translateSectionAsync(section, page, translations, {
         fallbackToSource,
         locale,
-        localesDir
+        localesDir,
+        dataModel
       })
     }
   }
@@ -147,7 +153,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
       await translateSectionAsync(section, translated.notFound, translations, {
         fallbackToSource,
         locale,
-        localesDir
+        localesDir,
+        dataModel
       })
     }
   }
@@ -164,7 +171,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
             await translateSectionAsync(section, layoutPage, translations, {
               fallbackToSource,
               locale,
-              localesDir
+              localesDir,
+              dataModel
             })
           }
         }
@@ -281,17 +289,17 @@ function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
 /**
  * Translate a section's content (synchronous, hash-based only)
  */
-function translateSectionSync(section, pageRoute, translations, fallbackToSource) {
+function translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel = null) {
   const context = translationContext(section, pageRoute)
 
   if (section.content?.type === 'doc') {
     translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
-    translateDataBlocks(section.content, context, translations, fallbackToSource)
+    translateDataBlocks(section.content, context, translations, fallbackToSource, (tag) => dataModel?.(section.type, tag) ?? null)
   }
 
   // Recursively translate subsections
   for (const subsection of section.subsections || []) {
-    translateSectionSync(subsection, pageRoute, translations, fallbackToSource)
+    translateSectionSync(subsection, pageRoute, translations, fallbackToSource, dataModel)
   }
 }
 
@@ -303,7 +311,7 @@ function translateSectionSync(section, pageRoute, translations, fallbackToSource
  * 2. Fall back to hash-based translation (element-by-element)
  */
 async function translateSectionAsync(section, page, translations, options) {
-  const { fallbackToSource, locale, localesDir } = options
+  const { fallbackToSource, locale, localesDir, dataModel } = options
   const pageRoute = page.route || '/'
   const context = translationContext(section, pageRoute)
 
@@ -318,7 +326,7 @@ async function translateSectionAsync(section, page, translations, options) {
     // Fall back to hash-based translation
     if (section.content?.type === 'doc') {
       translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
-      translateDataBlocks(section.content, context, translations, fallbackToSource)
+      translateDataBlocks(section.content, context, translations, fallbackToSource, (tag) => dataModel?.(section.type, tag) ?? null)
     }
   }
 
@@ -496,9 +504,15 @@ function withMarks(node, marks) {
  * silently; it now does (`uwx/locale-sync.js::deriveStructuralMap`), so the two
  * halves travel together.
  *
+ * ⭐ A block whose key its section type declares the shape of translates the fields that shape says
+ * are text, and only those (`data-strings.js::visitDataBlockStrings`) — the fields extraction
+ * offered, so a translation of an enum's value that happens to share its words with prose elsewhere
+ * is never applied to it.
+ *
+ * @param {(tag: string) => Object|null} [modelFor] - the model of a block's key, by its tag
  * @returns {boolean} whether any value was translated
  */
-function translateDataBlocks(doc, context, translations, fallbackToSource) {
+function translateDataBlocks(doc, context, translations, fallbackToSource, modelFor = () => null) {
   let changed = false
   const walk = (nodes) => {
     for (const node of nodes || []) {
@@ -506,11 +520,11 @@ function translateDataBlocks(doc, context, translations, fallbackToSource) {
       if (node.type === 'dataBlock') {
         const data = node.attrs?.data
         if (data && typeof data === 'object') {
-          visitDataStrings(data, (value) => {
+          visitDataBlockStrings(data, (value) => {
             const translated = lookupTranslation(value, context, translations, fallbackToSource)
             if (translated !== value) changed = true
             return translated
-          })
+          }, modelFor(node.attrs?.tag))
         }
       } else if (Array.isArray(node.content)) {
         walk(node.content)
@@ -529,12 +543,15 @@ function translateDataBlocks(doc, context, translations, fallbackToSource) {
  * (so the caller can omit an untranslated locale — it falls back to the source
  * locale). Lets the sync producer emit a self-contained per-locale DOC instead of a
  * source-keyed map (which a consumer would otherwise resolve against the source).
+ *
+ * `modelFor` is the section's data-block models by tag — `(tag) => dataModel(section.type, tag)` —
+ * so a push translates a block as the build does; without it, blocks are walked by the heuristic.
  */
-export function resolveDocForLocale(sourceDoc, table, context = { page: '', section: '' }) {
+export function resolveDocForLocale(sourceDoc, table, context = { page: '', section: '' }, modelFor = () => null) {
   if (!sourceDoc || sourceDoc.type !== 'doc' || !table) return null
   const doc = JSON.parse(JSON.stringify(sourceDoc))
   const elements = translateProseMirrorDoc(doc, context, table, true)
-  const data = translateDataBlocks(doc, context, table, true)
+  const data = translateDataBlocks(doc, context, table, true, modelFor)
   return elements || data ? doc : null
 }
 

package/src/i18n/model-fields.js

@@ -0,0 +1,97 @@
+/**
+ * ⭐ A RECORD'S FIELDS, WALKED BY ITS MODEL — the shape a push sends it in, lowered by the push's
+ * own rule (`uwx/data-schema.js::toDataSchemaDeclaration`), which marks `localized` exactly the
+ * fields that travel per locale: text — never an enum, a value format (a URL, an email), a
+ * `translatable: false` field, a number, a date, a file or a reference.
+ *
+ * One walk for two things a model describes: a record (`records.js`), and a tagged data block whose
+ * key a section type declares the shape of (`data-strings.js::visitDataBlockStrings`).
+ */
+import { isOpenMapSection } from '../uwx/data-schema.js'
+
+export function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * ⛔ 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
+ * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
+ * record under), and a top-level `slug` is how a record's reader hands the file's name
+ * on. Until 2026-09-14 they became translation units, and a translation whose source
+ * happened to equal one rewrote it, so a record's page stopped matching its URL.
+ * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
+ * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
+ *
+ * @param {string|number} key - a field name (an array index is never one)
+ * @param {boolean} topLevel - whether the key sits at the record's own level
+ * @returns {boolean}
+ */
+export function isRecordSystemField(key, topLevel) {
+  if (typeof key !== 'string') return false
+  return key.startsWith('$') || (topLevel && key === 'slug')
+}
+
+/**
+ * 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.
+ */
+export 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))
+  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
+  else if (isOpenMapSection(section) && isPlainObject(value)) {
+    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
+  }
+}
+
+export 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)
+  }
+}
+
+/**
+ * Each string a record's model marks `localized` — a text field's value, or each string of a list
+ * of them — handed to `visit(value, path)`; a different string returned replaces it, in place, as
+ * `data-strings.js::visitDataStrings` does. A rich field is one string here: a data block holds its
+ * markdown as written.
+ *
+ * @param {object} record
+ * @param {object} model - a lowered data schema (`toDataSchemaDeclaration`)
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {string} [prefix] - prepended to each path (`[0]` for a list's first item)
+ */
+export function visitModelStrings(record, model, visit, prefix = '') {
+  const pathOf = (path) => (prefix ? (path.startsWith('[') ? `${prefix}${path}` : `${prefix}.${path}`) : path)
+  eachModelField(record, model, (holder, name, field, path) => {
+    if (!field.localized) return
+    const value = holder[name]
+    if (typeof value === 'string') {
+      if (!value.trim()) return
+      const next = visit(value, pathOf(path))
+      if (typeof next === 'string' && next !== value) holder[name] = next
+    } else if (Array.isArray(value)) {
+      value.forEach((item, i) => {
+        if (typeof item !== 'string' || !item.trim()) return
+        const next = visit(item, pathOf(`${path}[${i}]`))
+        if (typeof next === 'string' && next !== item) value[i] = next
+      })
+    }
+  })
+}

package/src/i18n/records.js

@@ -23,7 +23,8 @@ 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, isOpenMapSection } from '../uwx/data-schema.js'
+import { toDataSchemaDeclaration, isProseMirrorField } from '../uwx/data-schema.js'
+import { eachModelField, eachSectionField, isRecordSystemField, isPlainObject } from './model-fields.js'
 import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored, storedFromMerged } from '@uniweb/schemas/conform'
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
@@ -186,7 +187,7 @@ function isFieldTranslatable(fieldDef) {
  * @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) {
+export function modelOf(schema, ref) {
   if (!schema) return null
   try {
     return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
@@ -208,40 +209,6 @@ function referencedModels(model) {
   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))
-  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
-  else if (isOpenMapSection(section) && isPlainObject(value)) {
-    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, 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 || {})
@@ -360,25 +327,6 @@ function derivesExcerpt(record, whole, dataSchema, config) {
   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
- * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
- * record under), and a top-level `slug` is how a record's reader hands the file's name
- * on. Until 2026-09-14 they became translation units, and a translation whose source
- * happened to equal one rewrote it, so a record's page stopped matching its URL.
- * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
- * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
- *
- * @param {string|number} key - a field name (an array index is never one)
- * @param {boolean} topLevel - whether the key sits at the record's own level
- * @returns {boolean}
- */
-function isRecordSystemField(key, topLevel) {
-  if (typeof key !== 'string') return false
-  return key.startsWith('$') || (topLevel && key === 'slug')
-}
-
 /**
  * A record's handle — `$name`, which the build sets from the record's file (`slug:` or
  * its name). ⭐ Not `slug` alone: a record of a schema whose brief declares a `slug`
@@ -1208,10 +1156,6 @@ function applyFreeform(record, freeform, dataSchema, schemaRef) {
   return out
 }
 
-function isPlainObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value)
-}
-
 /**
  * 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.

package/src/site/plugin.js

@@ -251,6 +251,7 @@ async function processDevSectionFetches(sections, fetchOptions, resolve) {
 }
 import { generateSearchIndex, getSearchIndexFilename } from '@uniweb/projections'
 import { mergeTranslations } from '../i18n/merge.js'
+import { dataBlockModels, NO_DATA_MODELS } from '../i18n/data-models.js'
 import { searchDeclaredOn } from './search-declared.js'
 import { mountDevApi } from '../dev/api-mount.js'
 
@@ -654,6 +655,9 @@ export function siteContentPlugin(options = {}) {
   }
 
   let siteContent = null
+  // What each section type declares its data blocks are — read once per collection of the site.
+  let dataModelPromise = null
+  const dataModels = () => (dataModelPromise ||= dataBlockModels(resolvedSitePath).catch(() => NO_DATA_MODELS))
   let resolvedSitePath = null
   let resolvedPublicDir = null
   let resolvedOutDir = null
@@ -791,7 +795,8 @@ export function siteContentPlugin(options = {}) {
     return mergeTranslations(siteContent, translations || {}, {
       locale,
       localesDir: join(resolvedSitePath, localesDir),
-      freeformEnabled: hasFreeform
+      freeformEnabled: hasFreeform,
+      dataModel: await dataModels()
     })
   }
 
@@ -951,6 +956,7 @@ export function siteContentPlugin(options = {}) {
         // strict on a production build: a mount that contributes no pages is a
         // warning while you author and a broken deploy once you ship.
         siteContent = await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction })
+        dataModelPromise = null
         headHtml = await loadHeadHtml()
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
 
@@ -1020,6 +1026,7 @@ export function siteContentPlugin(options = {}) {
             console.log('[site-content] Content changed, rebuilding...')
             try {
               siteContent = await collectForBundle(resolvedSitePath, { foundationPath, base: basePath })
+              dataModelPromise = null
               headHtml = await loadHeadHtml()
               if (materialize) {
                 queriesConfig = siteContent.config?.queries

package/src/uwx/index.js

@@ -78,6 +78,8 @@ export { matchStoredRecords } from './record-identity.js'
 // The scope a site's `@/x` refs resolve into — its foundation's. A pull resolves it
 // up front and hands it to the synchronous projections above.
 export { siteSelfScope } from './self-scope.js'
+// What each section type declares its data blocks are — a pull reads a translated block back by it.
+export { dataBlockModels } from '../i18n/data-models.js'
 export {
   siteInfoToConfig,
   sectionRecordToFile,

package/src/uwx/locale-sync.js

@@ -23,7 +23,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-writer'
 import { computeHash } from '../i18n/hash.js'
 import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
-import { visitDataStrings } from '../i18n/data-strings.js'
+import { visitDataBlockStrings } from '../i18n/data-strings.js'
 import { resolveDocForLocale } from '../i18n/merge.js'
 import { computeSourceHash } from '../i18n/freeform-manifest.js'
 import { sameMarkdownDocument, canonicalJson } from './same-content.js'
@@ -167,8 +167,11 @@ export function loadLocaleTranslations(siteRoot, locales, subdir = '') {
  * @param {string} sourceLocale
  * @param {string[]} [targetLocales]
  * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
+ * @param {object} [context] - the section's translation context
+ * @param {(tag: string) => object|null} [modelFor] - the section's data-block models by tag
+ *   (`i18n/data-models.js`), so a block is translated as the build translates it
  */
-export function localizeContentDoc(doc, sourceLocale, targetLocales, translations, context = undefined) {
+export function localizeContentDoc(doc, sourceLocale, targetLocales, translations, context = undefined, modelFor = () => null) {
   // Non-docs (null, an already-localized map) pass through untouched.
   if (!isProseMirrorDoc(doc)) return doc
 
@@ -178,7 +181,7 @@ export function localizeContentDoc(doc, sourceLocale, targetLocales, translation
       const table = translations[locale]
       if (!table) continue
       // With the section's context, so a context-specific override resolves as the build resolves it.
-      const resolved = resolveDocForLocale(doc, table, context)
+      const resolved = resolveDocForLocale(doc, table, context, modelFor)
       if (resolved) result[locale] = resolved
     }
   }
@@ -363,7 +366,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null } = {
  * per-locale link hrefs survive. Keyed by the source element's cleaned text, so
  * `computeHash(key)` matches the extractor's unit hash — closing the round trip.
  */
-function deriveStructuralMap(sourceDoc, targetDoc) {
+function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null) {
   if (!isProseMirrorDoc(sourceDoc) || !isProseMirrorDoc(targetDoc)) return null
   const src = blockElements(sourceDoc)
   const tgt = blockElements(targetDoc)
@@ -383,15 +386,18 @@ function deriveStructuralMap(sourceDoc, targetDoc) {
     // a mark we can't serialize → don't risk a lossy map; store as free-form
     return null
   }
-  return addDataBlockStrings(map, sourceDoc, targetDoc)
+  return addDataBlockStrings(map, sourceDoc, targetDoc, modelFor)
 }
 
 // ⭐ A TAGGED DATA BLOCK's translated strings, read pairwise — the strings the build translates
-// (`visitDataStrings`, the extractor's judgement), keyed by their source text as the build keys them.
+// (`visitDataBlockStrings`: a block's declared shape, else the extractor's heuristic), keyed by their
+// source text as the build keys them. ⭐ Walked by the same model the push translated with — the pairing
+// is by position, so a declared text field the heuristic skips (a `status`) would otherwise read a
+// faithful translation as another shape.
 // A target that is not the source with only those strings changed — another shape, another `href` —
 // cannot be said per string, and the whole translation is free-form. ⛔ Until 2026-09-26 a data block
 // was not read here at all, and its translations were not sent (`merge.js::translateDataBlocks`).
-function addDataBlockStrings(map, sourceDoc, targetDoc) {
+function addDataBlockStrings(map, sourceDoc, targetDoc, modelFor = () => null) {
   const srcBlocks = dataBlockNodes(sourceDoc)
   const tgtBlocks = dataBlockNodes(targetDoc)
   if (srcBlocks.length !== tgtBlocks.length) return null
@@ -405,7 +411,7 @@ function addDataBlockStrings(map, sourceDoc, targetDoc) {
     }
     const strings = (data) => {
       const out = []
-      visitDataStrings(JSON.parse(JSON.stringify(data ?? null)), (value) => void out.push(value))
+      visitDataBlockStrings(JSON.parse(JSON.stringify(data ?? null)), (value) => void out.push(value), modelFor(s.tag))
       return out
     }
     const from = strings(s.data)
@@ -418,7 +424,7 @@ function addDataBlockStrings(map, sourceDoc, targetDoc) {
       pairs.set(from[j], to[j])
     }
     const rebuilt = JSON.parse(JSON.stringify(s.data))
-    visitDataStrings(rebuilt, (value) => pairs.get(value) ?? value)
+    visitDataBlockStrings(rebuilt, (value) => pairs.get(value) ?? value, modelFor(s.tag))
     if (canonicalJson(rebuilt) !== canonicalJson(t.data)) return null
     for (const [from, to] of pairs) map[from.trim()] = to
   }
@@ -436,7 +442,7 @@ function addDataBlockStrings(map, sourceDoc, targetDoc) {
  * reserved `@` (and `$`-prefixed) key is opaque metadata — NEVER a locale. A bare
  * doc (no locale wrap) is returned unchanged.
  */
-export function unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates = null, context = null) {
+export function unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates = null, context = null, modelFor = () => null) {
   if (!isLocalizedContent(content)) return content
   const source = content[sourceLocale]
   for (const [locale, value] of Object.entries(content)) {
@@ -445,7 +451,7 @@ export function unwrapLocalizedContent(content, sourceLocale, collector, freefor
     if (isProseMirrorDoc(value)) {
       // A translation the site keeps as a free-form file stays one, even when it lines up.
       const kept = collector?.keptFreeform?.(locale, freeformCandidates || freeformRelPath) || null
-      const map = kept ? null : deriveStructuralMap(source, value)
+      const map = kept ? null : deriveStructuralMap(source, value, modelFor)
       if (map) collector?.addStructuralMap?.(locale, map, context)
       else collector?.noteFreeform?.(locale, value, source, kept || freeformRelPath)
     } else {

package/src/uwx/site-project.js

@@ -403,7 +403,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
  *        structural maps on a localized `content` field are captured into it
  * @returns {'updated'|'unchanged'}
  */
-export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null }) {
+export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null }) {
   // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
   // would only warn about it (2026-09-27).
   // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
@@ -416,7 +416,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
   // target-locale structural maps are captured into the locales/ collector, and any
   // free-form target body is captured with `freeformRelPath` for writing under
   // locales/freeform/. A bare doc (source-only / pre-localization) passes through.
-  const sourceContent = unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates, context)
+  // A data block is read back by what the section's type declares it is, as the push translated it.
+  const sourceContent = unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates, context, (tag) => dataModel?.(type, tag) ?? null)
 
   const { hidden: paramHidden, fetch: paramFetch, ...paramsRest } = params && typeof params === 'object' ? params : {}
   const frontmatter = {}
@@ -556,6 +557,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
         record,
         sourceLocale: ctx?.sourceLocale,
         collector: ctx?.collector,
+        dataModel: ctx?.dataModel,
         freeformRelPath,
         freeformCandidates,
         writeId: fileSectionName(filePath) !== stableId,
@@ -1081,6 +1083,7 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
       record,
       sourceLocale: ctx?.sourceLocale,
       collector: ctx?.collector,
+      dataModel: ctx?.dataModel,
       writeId: fileSectionName(filePath) !== stableId,
       freeformRelPath: stableId ? buildFreeformPath({ stableId }, page) : null,
       freeformCandidates: stableId ? freeformPathsFor({ stableId }, page) : null,
@@ -1116,7 +1119,7 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  *        `declarationsToQueriesYml`, whose default it overrides.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
@@ -1145,7 +1148,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   // rename detection, build a fresh one as we project, then persist it. Items not
   // re-projected (deleted) drop out naturally. `collector` rides along to capture
   // localized scalars during the page walk.
-  const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map() }
+  const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map(), dataModel }
   // Where the site keeps its localized URLs — `site.yml`'s map, when it has one (`pageSlugToYml`).
   const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
   ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }

package/src/uwx/site.js

@@ -45,6 +45,7 @@
 // (favicon/assets — carried out of band).
 
 import { readdir, readFile } from 'node:fs/promises'
+import { dataBlockModels } from '../i18n/data-models.js'
 import { existsSync } from 'node:fs'
 import { join, parse, relative } from 'node:path'
 import {
@@ -245,6 +246,8 @@ export function buildRouteOf(record, parentRoute, sourceLocale) {
 // hits the filesystem.
 async function localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot) {
   const freeformBase = localesDir(siteRoot)
+  // What each section type declares its data blocks are, so a block is pushed as the build translates it.
+  const dataModel = await dataBlockModels(siteRoot)
 
   const localizeSection = async (record, page) => {
     if (!record.content) return
@@ -252,7 +255,7 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
     // Resolved in the section's context, as the build resolves it (`translationContext`): a
     // context-specific override applies here and nowhere else. ⛔ Until 2026-09-26 every section was
     // resolved with none, so an override never reached a backend.
-    let localized = localizeContentDoc(record.content, sourceLocale, targetLocales, translations, translationContext({ stableId }, page?.route))
+    let localized = localizeContentDoc(record.content, sourceLocale, targetLocales, translations, translationContext({ stableId }, page?.route), (tag) => dataModel(record.type, tag))
     if (page) {
       const section = { stableId }
       for (const locale of targetLocales) {