@uniweb/build 0.63.3 → 0.64.0

package/src/site/content-collector.js

@@ -26,7 +26,7 @@ import { readFile, readdir, stat } from 'node:fs/promises'
 import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
-import { readLayoutFolder, DEFAULT_LAYOUT } from './layout-folder.js'
+import { readLayoutFolder, DEFAULT_LAYOUT, layoutAreaRoute } from './layout-folder.js'
 import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
@@ -2419,7 +2419,7 @@ async function collectLayouts(layoutDir, siteRoot) {
       assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
       iconCollection = mergeIconCollections(iconCollection, result.iconCollection)
     }
-    const route = area.layout === DEFAULT_LAYOUT ? `/layout/${area.area}` : `/layout/${area.layout}/${area.area}`
+    const route = layoutAreaRoute(area.layout, area.area)
     layouts[area.layout] ??= {}
     layouts[area.layout][area.area] = {
       route,
@@ -2693,6 +2693,11 @@ export async function collectSiteContent(sitePath, options = {}) {
   for (const { message } of langValidation.warnings) {
     console.warn(`[content-collector] ${message}`)
   }
+  // Errors stop a publish build (below); in dev they are said, so the author meets them here
+  // rather than first at a push.
+  if (!dropUnpublished) {
+    for (const { message } of langValidation.errors) console.warn(`[content-collector] ${message}`)
+  }
   // Publish filter (the sync format's "Per-locale publish
   // readiness"): on published build paths, only the publishable intersection
   // (publishLanguages ∩ languages; absent field = all declared) ships — in
@@ -2956,9 +2961,35 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
   return Object.keys(result).length > 0 ? result : null
 }
 
+/**
+ * One level's pages in the order a push walks them, and a pull reproduces: explicit `order:`, then
+ * numeric-prefix filename order, then the parent config's `pages:` list. Shared by the push's walk
+ * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so the two cannot
+ * disagree on what a level's order is.
+ *
+ * ⚠️ The build's own page-folder sort (`collectPagesRecursive`) is not this function: it compares
+ * folder names whole, as strings. The two differ only for numbered page folders — see the note at
+ * `orderedSubfolders`.
+ *
+ * @param {Array<{ dirName: string, name: string, order?: number }>} folders
+ * @param {Array} [parentPages] - the parent config's `pages:`
+ * @returns {Array} the folders, ordered
+ */
+function orderFolders(folders, parentPages) {
+  const sorted = [...folders].sort(
+    (a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || compareFilenames(a.dirName, b.dirName)
+  )
+  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
+  return parsed && parsed.mode !== 'all' ? applyWildcardOrder(sorted, parsed) : sorted
+}
+
 export {
   assertRouteFolder,
   buildRouteTranslations,
+  composeLocalizedRoute,
+  isValidSlugSegment,
+  declaredHomepage,
+  orderFolders,
   extractItemName,
   parseWildcardArray,
   applyWildcardOrder,

package/src/site/layout-folder.js

@@ -40,6 +40,21 @@ import { layoutNameKey } from '@uniweb/core/layout-name'
 /** The key the default layout's areas are held under, on every lane. */
 export const DEFAULT_LAYOUT = 'default'
 
+/**
+ * The route a layout area renders at — `/layout/<area>` in the default layout,
+ * `/layout/<layout>/<area>` in a named one. A layout area's free-form translations are
+ * addressed by it (`i18n/freeform.js`), so the build, the push and the pull must all use
+ * this one rule: the push said "layout sections have no free-form home" until 2026-09-26,
+ * and a translation the build rendered never left the author's machine.
+ *
+ * @param {string} [layoutName]
+ * @param {string} area
+ * @returns {string}
+ */
+export function layoutAreaRoute(layoutName, area) {
+  return !layoutName || layoutName === DEFAULT_LAYOUT ? `/layout/${area}` : `/layout/${layoutName}/${area}`
+}
+
 /**
  * Area names a layout folder is most likely to have been meant as. A folder under
  * `layout/` named like one of them was, before this convention, an area of the

package/src/site/query-processor.js

@@ -186,23 +186,34 @@ function extractPlainText(node) {
   if (node.type === 'text') {
     return node.text || ''
   }
+  if (node.type === 'hardBreak' || node.type === 'hard_break') return ' '
 
   if (Array.isArray(node.content)) {
-    return node.content.map(extractPlainText).join('')
+    // A textblock's inline children join as written; blocks are separated by a space. ⛔ Until
+    // 2026-09-26 blocks joined with nothing too, so an excerpt ran one paragraph into the next
+    // ("…in 1816.The river…").
+    const inline = node.content.every((child) => child?.type === 'text' || INLINE_NODES.has(child?.type))
+    return node.content.map(extractPlainText).join(inline ? '' : ' ')
   }
 
   return ''
 }
 
+// The inline nodes a textblock holds beside text.
+const INLINE_NODES = new Set(['hardBreak', 'hard_break', 'image', 'inset_ref', 'inset_placeholder', 'icon'])
+
 /**
  * Extract excerpt from content
  *
+ * Exported for the localized build (`i18n/records.js`), which derives each locale's
+ * excerpt from that locale's body by this same rule.
+ *
  * @param {Object} frontmatter - Parsed frontmatter
  * @param {Object} content - ProseMirror content
  * @param {Object} excerptConfig - Excerpt configuration
  * @returns {string} Excerpt text
  */
-function extractExcerpt(frontmatter, content, excerptConfig) {
+export function extractExcerpt(frontmatter, content, excerptConfig) {
   const { maxLength = 160, field = null } = excerptConfig || {}
 
   // Check for explicit excerpt in frontmatter

package/src/uwx/asset-map.js

@@ -70,9 +70,14 @@ export function servedFingerprint(url) {
  * that works, not a local path to a file that is not there. Filling those in is
  * the download's job, not this one.
  *
- * `assetId` itself is not removed: it is not a markdown attribute, so the
- * serializer drops it on the way to disk, and leaving it lets a caller project
- * the same document twice without the second pass losing identity.
+ * ⭐ **And the identity goes with the URL it stood beside.** A restored reference is
+ * the author's path again, and that path's id is kept in `sync.json`, which the next
+ * push stamps from (`rewriteEntityAssets`). ⛔ Until 2026-09-26 `assetId` was left in
+ * place, on the ground that the markdown serializer drops it — true of a body, and of
+ * nothing else: a pull into the copy that pushed wrote `assetId`/`assetExt` into the
+ * frontmatter of every section whose background it restored, and a body holding a
+ * pushed image never compared as unchanged, since the author's markdown parses with
+ * no id. An id the map does not know keeps its identity, with its URL.
  *
  * @param {object} document - the site-content document (mutated in place)
  * @param {Record<string, { id: string, ext: string }>} map - readAssetMap()
@@ -98,6 +103,8 @@ export function restoreAssetRefs(document, map) {
       if (!ref) { stats.unknown++; continue }
       const urlAttr = slot.urls.find((k) => typeof node[k] === 'string') || slot.urls[0]
       node[urlAttr] = ref
+      delete node[slot.id]
+      delete node[slot.ext]
       stats.restored++
     }
     for (const v of Object.values(node)) visit(v)

package/src/uwx/backfill.js

@@ -254,7 +254,7 @@ const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArr
  *        it has no name for is written as the uuid.
  * @returns {string} the source-file text
  */
-export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName }) {
+export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName, context = null }) {
   const layout = recordFileLayout(declaration)
   if (layout.sections.length === 0) {
     throw new Error('uwx/render: the data schema declares no sections')
@@ -267,7 +267,7 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   }
   // Markdown: the content body field, wherever its single section is, becomes the body.
   const { target } = contentBodyTarget(declaration)
-  const dec = { sourceLocale, collector, freeformRelPath, refName, bodyAt: format === 'md' ? target : null, body: '' }
+  const dec = { sourceLocale, collector, freeformRelPath, refName, context, bodyAt: format === 'md' ? target : null, body: '' }
 
   const record = {}
   if (document?.$uuid) record.$uuid = document.$uuid
@@ -338,16 +338,16 @@ function decodeLeaf(raw, field, dec, isBody) {
   if (field?.type === 'entity_ref') return decodeReference(raw, field, dec)
   if (isProseMirrorField(field)) {
     const sourceDoc = field.localized
-      ? unwrapLocalizedContent(raw, dec.sourceLocale, dec.collector, isBody ? dec.freeformRelPath : undefined)
+      ? unwrapLocalizedContent(raw, dec.sourceLocale, dec.collector, isBody ? dec.freeformRelPath : undefined, null, dec.context)
       : raw
     return sourceDoc ? proseMirrorToMarkdown(sourceDoc) : ''
   }
   if (!field?.localized) return raw
   if (Array.isArray(raw)) {
-    if (!isBody) for (const item of raw) dec.collector?.add(item)
+    if (!isBody) for (const item of raw) dec.collector?.add(item, dec.context)
     return unwrapLocalizedList(raw, dec.sourceLocale)
   }
-  if (!isBody) dec.collector?.add(raw)
+  if (!isBody) dec.collector?.add(raw, dec.context)
   return unwrapLocalized(raw, dec.sourceLocale)
 }
 

package/src/uwx/index.js

@@ -71,7 +71,10 @@ export {
   declarationsToQueriesYml,
   folderToFolderYml,
   findRecordFileByUuid,
+  indexFolder,
 } from './records-project.js'
+// Which stored record each of a copy's records is, when its map lost the answer.
+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'

package/src/uwx/locale-sync.js

@@ -16,22 +16,52 @@
 // surface, used by the projector (pull → files) and, later, the producer
 // (files → push).
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-writer'
 import { computeHash } from '../i18n/hash.js'
-import { blockElements, elementText } from '../i18n/extract.js'
+import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
+import { visitDataStrings } 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'
 
 const FREEFORM_MANIFEST = '.manifest.json'
 
-// The `locales/` directory for a site (the i18n localesDir default; `paths` can
-// override it, but the default is `locales` — keep this the single place to change).
-// `subdir` scopes a lane: '' → site-content (locales/), 'records' → record
-// translations (locales/records/), matching the i18n manifest layout.
+// The directory a site keeps its translations in — `site.yml`'s `i18n.localesDir`, else `locales`,
+// the rule the build and `uniweb i18n` read it by — for the push and the pull alike. `subdir` scopes a
+// lane: '' → site-content (locales/), 'records' → record translations (locales/records/), matching the
+// i18n manifest layout.
+// ⛔ It was `locales/` whatever the site said until 2026-09-26: a site keeping its translations in
+// `translations/` pushed its source language alone, and a pull wrote into a directory it never read.
 export function localesDir(siteRoot, subdir = '') {
-  return subdir ? join(siteRoot, 'locales', subdir) : join(siteRoot, 'locales')
+  const base = join(siteRoot, localesDirName(siteRoot))
+  return subdir ? join(base, subdir) : base
+}
+
+// `i18n.localesDir`, read once per version of the file — every translation a pull writes asks for it.
+const localesDirCache = new Map() // siteRoot → { mtimeMs, name }
+function localesDirName(siteRoot) {
+  const file = join(siteRoot, 'site.yml')
+  let mtimeMs = null
+  try {
+    mtimeMs = statSync(file).mtimeMs
+  } catch {
+    return 'locales'
+  }
+  const cached = localesDirCache.get(siteRoot)
+  if (cached && cached.mtimeMs === mtimeMs) return cached.name
+  let name = 'locales'
+  try {
+    const dir = yaml.load(readFileSync(file, 'utf8'), YAML_OPTIONS)?.i18n?.localesDir
+    if (typeof dir === 'string' && dir.trim()) name = dir.trim()
+  } catch {
+    // unreadable — the default
+  }
+  localesDirCache.set(siteRoot, { mtimeMs, name })
+  return name
 }
 
 export function localeFilePath(siteRoot, locale, subdir = '') {
@@ -138,7 +168,7 @@ export function loadLocaleTranslations(siteRoot, locales, subdir = '') {
  * @param {string[]} [targetLocales]
  * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
  */
-export function localizeContentDoc(doc, sourceLocale, targetLocales, translations) {
+export function localizeContentDoc(doc, sourceLocale, targetLocales, translations, context = undefined) {
   // Non-docs (null, an already-localized map) pass through untouched.
   if (!isProseMirrorDoc(doc)) return doc
 
@@ -147,7 +177,8 @@ export function localizeContentDoc(doc, sourceLocale, targetLocales, translation
     for (const locale of targetLocales) {
       const table = translations[locale]
       if (!table) continue
-      const resolved = resolveDocForLocale(doc, table)
+      // With the section's context, so a context-specific override resolves as the build resolves it.
+      const resolved = resolveDocForLocale(doc, table, context)
       if (resolved) result[locale] = resolved
     }
   }
@@ -164,20 +195,46 @@ export function localizeContentDoc(doc, sourceLocale, targetLocales, translation
  * @param {string} sourceLocale
  * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
  */
-export function localizeScalar(value, sourceLocale, translations) {
+export function localizeScalar(value, sourceLocale, translations, context = null) {
   if (value == null) return undefined
   if (typeof value === 'object') return value // already a { lang: value } map
   const out = { [sourceLocale]: value }
   if (translations && typeof value === 'string') {
     const hash = computeHash(value)
     for (const [locale, table] of Object.entries(translations)) {
-      const tgt = table?.[hash]
+      const tgt = translationFor(table?.[hash], context)
       if (typeof tgt === 'string') out[locale] = tgt
     }
   }
   return out
 }
 
+/**
+ * A translation entry's text in one place: a string as it is; `{ default, overrides }` — a
+ * string that reads differently in some places — by the place's key (`contextKey`), else its
+ * default. ⛔ Until 2026-09-26 a scalar's entry in that form was dropped whole, its default too:
+ * the build rendered it, and a push carried the source alone.
+ *
+ * @param {*} entry - a translation file's entry
+ * @param {{ key?: string, page?: string, section?: string }|null} context - where the value is
+ * @returns {string|undefined}
+ */
+export function translationFor(entry, context) {
+  if (typeof entry === 'string') return entry
+  if (!entry || typeof entry !== 'object') return undefined
+  const override = context ? entry.overrides?.[contextKey(context)] : undefined
+  return typeof override === 'string' ? override : typeof entry.default === 'string' ? entry.default : undefined
+}
+
+/**
+ * The key an override names a place by: a record's identity (`<pool>/<handle>`, as `key`), or
+ * a page section's `<route>:<id>` (`i18n/extract.js::translationContext`) — as `i18n/merge.js`
+ * reads it.
+ */
+export function contextKey(context) {
+  return context?.key ?? `${context?.page}:${context?.section}`
+}
+
 /**
  * Wrap a `multiple: true` + `localized: true` field (e.g. page `keywords` — "array
  * of localized strings") into per-locale form by localizing each element. Container
@@ -189,10 +246,10 @@ export function localizeScalar(value, sourceLocale, translations) {
  * @param {string} sourceLocale
  * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
  */
-export function localizeScalarList(value, sourceLocale, translations) {
+export function localizeScalarList(value, sourceLocale, translations, context = null) {
   if (value == null) return undefined
-  if (!Array.isArray(value)) return localizeScalar(value, sourceLocale, translations)
-  return value.map((item) => localizeScalar(item, sourceLocale, translations))
+  if (!Array.isArray(value)) return localizeScalar(value, sourceLocale, translations, context)
+  return value.map((item) => localizeScalar(item, sourceLocale, translations, context))
 }
 
 // True for a ProseMirror document node (`{ type: 'doc', content: [...] }`).
@@ -217,12 +274,14 @@ export function isLocalizedContent(value) {
  * (source text hashed exactly as `i18n extract` keys it). Non-string or missing
  * values are skipped (only hashable scalars belong in the hash manifest).
  */
-export function createTranslationCollector(sourceLocale) {
+export function createTranslationCollector(sourceLocale, { siteRoot = null } = {}) {
   const byLocale = {} // { locale: { hash: target } }
   const freeformPending = [] // [{ locale, content }] — target-locale free-form bodies
 
-  // Record a localized SCALAR field's target locales (hash of the source scalar).
-  function add(localizedValue) {
+  // Record a localized SCALAR field's target locales (hash of the source scalar). ⭐ With `context`
+  // — the record it was read in (`{ key: '<pool>/<handle>' }`) — a translation that differs from one
+  // record to another comes back as the author's `{ default, overrides }`, as a page section's does.
+  function add(localizedValue, context = null) {
     if (!isLocalizedMap(localizedValue)) return
     const source = localizedValue[sourceLocale]
     if (typeof source !== 'string' || source.length === 0) return
@@ -230,17 +289,38 @@ export function createTranslationCollector(sourceLocale) {
     for (const [locale, value] of Object.entries(localizedValue)) {
       if (locale === sourceLocale) continue
       if (typeof value !== 'string') continue
-      ;(byLocale[locale] ||= {})[hash] = value
+      const table = (byLocale[locale] ||= {})
+      if (!context) {
+        if (table[hash] instanceof SeenInContexts) table[hash].plain = value
+        else table[hash] = value
+        continue
+      }
+      const seen = table[hash] instanceof SeenInContexts ? table[hash] : new SeenInContexts(table[hash])
+      seen.values[contextKey(context)] = value
+      table[hash] = seen
     }
   }
 
   // Record a structural translation MAP for one target locale: `{ src-text: target }`
   // keyed by the source text exactly as `i18n extract` keys it (hash of the source).
-  function addStructuralMap(locale, map) {
+  // ⭐ With `context` — where the map was read (`translationContext`) — a translation that differs
+  // from one section to another is kept per section, and comes back as the author's
+  // context-specific overrides (`writeLocaleTranslations`). ⛔ Until 2026-09-26 the last section
+  // read won, and a pull wrote that one string over the author's `{ default, overrides }`.
+  function addStructuralMap(locale, map, context = null) {
     if (locale === sourceLocale || !map || typeof map !== 'object' || Array.isArray(map)) return
+    const table = (byLocale[locale] ||= {})
     for (const [src, target] of Object.entries(map)) {
       if (typeof src !== 'string' || typeof target !== 'string') continue
-      ;(byLocale[locale] ||= {})[computeHash(src)] = target
+      const hash = computeHash(src)
+      if (!context) {
+        if (table[hash] instanceof SeenInContexts) table[hash].plain = target
+        else table[hash] = target
+        continue
+      }
+      const seen = table[hash] instanceof SeenInContexts ? table[hash] : new SeenInContexts(table[hash])
+      seen.values[contextKey(context)] = target
+      table[hash] = seen
     }
   }
 
@@ -253,7 +333,21 @@ export function createTranslationCollector(sourceLocale) {
     freeformPending.push({ locale, target, source, relpath: relpath || null })
   }
 
-  return { add, addStructuralMap, noteFreeform, byLocale, freeformPending }
+  // ⭐ The FREE-FORM file the site keeps for this translation, if any — the first of `relpaths` (the
+  // order the renderer looks them up in, `freeformPathsFor`) that exists for `locale`. A pulled
+  // translation goes back into that file, whatever its shape. ⛔ Until 2026-09-25 a free-form body
+  // whose paragraphs lined up with its source's was read as a structural translation, and a pull into
+  // the author's copy wrote its text over their `locales/{locale}.json` entries for those paragraphs —
+  // measured on the `international` template's `about/story`, in Spanish and French.
+  function keptFreeform(locale, relpaths) {
+    if (!siteRoot) return null
+    for (const rel of [].concat(relpaths || [])) {
+      if (rel && existsSync(join(localesDir(siteRoot), 'freeform', locale, rel))) return rel
+    }
+    return null
+  }
+
+  return { add, addStructuralMap, noteFreeform, keptFreeform, byLocale, freeformPending }
 }
 
 /**
@@ -289,6 +383,45 @@ 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)
+}
+
+// ⭐ 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.
+// 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) {
+  const srcBlocks = dataBlockNodes(sourceDoc)
+  const tgtBlocks = dataBlockNodes(targetDoc)
+  if (srcBlocks.length !== tgtBlocks.length) return null
+  for (let i = 0; i < srcBlocks.length; i++) {
+    const s = srcBlocks[i].attrs || {}
+    const t = tgtBlocks[i].attrs || {}
+    if (s.tag !== t.tag) return null
+    if (!s.data || typeof s.data !== 'object') {
+      if (canonicalJson(s.data) !== canonicalJson(t.data)) return null
+      continue
+    }
+    const strings = (data) => {
+      const out = []
+      visitDataStrings(JSON.parse(JSON.stringify(data ?? null)), (value) => void out.push(value))
+      return out
+    }
+    const from = strings(s.data)
+    const to = strings(t.data)
+    if (from.length !== to.length) return null
+    const pairs = new Map()
+    for (let j = 0; j < from.length; j++) {
+      if (from[j] === to[j]) continue
+      if (pairs.has(from[j]) && pairs.get(from[j]) !== to[j]) return null // one string, two translations
+      pairs.set(from[j], to[j])
+    }
+    const rebuilt = JSON.parse(JSON.stringify(s.data))
+    visitDataStrings(rebuilt, (value) => pairs.get(value) ?? value)
+    if (canonicalJson(rebuilt) !== canonicalJson(t.data)) return null
+    for (const [from, to] of pairs) map[from.trim()] = to
+  }
   return map
 }
 
@@ -303,23 +436,62 @@ function deriveStructuralMap(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) {
+export function unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates = null, context = null) {
   if (!isLocalizedContent(content)) return content
   const source = content[sourceLocale]
   for (const [locale, value] of Object.entries(content)) {
     if (locale === sourceLocale) continue
     if (locale === '@' || locale.startsWith('$')) continue // reserved metadata, not a locale
     if (isProseMirrorDoc(value)) {
-      const map = deriveStructuralMap(source, value)
-      if (map) collector?.addStructuralMap?.(locale, map)
-      else collector?.noteFreeform?.(locale, value, source, freeformRelPath)
+      // 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)
+      if (map) collector?.addStructuralMap?.(locale, map, context)
+      else collector?.noteFreeform?.(locale, value, source, kept || freeformRelPath)
     } else {
-      collector?.addStructuralMap?.(locale, value)
+      collector?.addStructuralMap?.(locale, value, context)
     }
   }
   return source
 }
 
+// A translation read in several sections: what each section's context says, and what a place with
+// no context (a page title) says. Reconciled with the author's entry when the file is written.
+class SeenInContexts {
+  constructor(plain) {
+    this.plain = typeof plain === 'string' ? plain : undefined
+    this.values = {} // a place's key (`contextKey`) → translation
+  }
+}
+
+// ⭐ A translation seen in several places comes back as the author keeps it: one string where every
+// place agrees, else `{ default, overrides }` — their default and their overrides kept wherever they
+// still hold. The default is what the places without an override of their own say (the most of
+// them; the author's default when tied, else the first read). An override for a place this pull did
+// not see is kept, and one that now says the default is dropped.
+function reconcileTranslation(existing, seen) {
+  const own = existing && typeof existing === 'object' && existing.overrides && typeof existing.overrides === 'object' ? existing.overrides : {}
+  const authoredDefault = typeof existing === 'string' ? existing : existing && typeof existing === 'object' ? existing.default : undefined
+  const contexts = Object.entries(seen.values)
+  const candidates = [...(seen.plain !== undefined ? [seen.plain] : []), ...contexts.filter(([k]) => !(k in own)).map(([, v]) => v)]
+  let def = authoredDefault
+  if (candidates.length) {
+    const counts = new Map()
+    for (const v of candidates) counts.set(v, (counts.get(v) || 0) + 1)
+    const most = Math.max(...counts.values())
+    const top = [...counts].filter(([, n]) => n === most).map(([v]) => v)
+    def = top.includes(authoredDefault) ? authoredDefault : top[0]
+  } else if (def === undefined) {
+    def = contexts[0]?.[1]
+  }
+  const overrides = { ...own }
+  for (const [k, v] of contexts) {
+    if (v === def) delete overrides[k]
+    else overrides[k] = v
+  }
+  return Object.keys(overrides).length ? { default: def, overrides } : def
+}
+
 /**
  * Write captured target-locale FREE-FORM bodies to `locales/freeform/{locale}/<relpath>`
  * (markdown, body-only) and record each one's SOURCE hash in that locale's
@@ -368,7 +540,9 @@ export function writeFreeformTranslations(siteRoot, freeformPending) {
       } catch {
         // absent
       }
-      if (current !== text) {
+      // ⭐ A file whose markdown already says this is left as the author wrote it — the writer's
+      // markdown is not theirs (blank lines, line breaks), as for a section body (`writeSectionFile`).
+      if (current !== text && !(current !== null && sameMarkdownDocument(current.trim(), target))) {
         mkdirSync(dirname(filePath), { recursive: true })
         writeFileSync(filePath, text)
         report.written.push(filePath)
@@ -391,34 +565,91 @@ export function writeFreeformTranslations(siteRoot, freeformPending) {
   return report
 }
 
+/**
+ * The keys of a JSON object's top level, in the order its text writes them.
+ *
+ * ⛔ NOT `Object.keys(JSON.parse(text))`: a JavaScript object puts every integer-like key
+ * first, and a translation's key is a hash — `19544096` is one, as about one in fifty are.
+ * Until 2026-09-26 a pull that changed one translation also moved each such entry to the top
+ * of the author's file.
+ *
+ * @param {string} text - a JSON object
+ * @returns {string[]}
+ */
+function topLevelKeyOrder(text) {
+  const keys = []
+  let depth = 0
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (c === '"') {
+      let end = i + 1
+      while (end < text.length && text[end] !== '"') end += text[end] === '\\' ? 2 : 1
+      if (depth === 1 && /^\s*:/.test(text.slice(end + 1, end + 64))) keys.push(JSON.parse(text.slice(i, end + 1)))
+      i = end
+    } else if (c === '{' || c === '[') depth++
+    else if (c === '}' || c === ']') depth--
+  }
+  return keys
+}
+
+/** `JSON.stringify(object, null, 2)` of these entries, in their order — see `topLevelKeyOrder`. */
+function jsonObjectText(entries) {
+  if (entries.length === 0) return '{}\n'
+  const lines = entries.map(([key, value]) => `  ${JSON.stringify(key)}: ${JSON.stringify(value, null, 2).replace(/\n/g, '\n  ')}`)
+  return `{\n${lines.join(',\n')}\n}\n`
+}
+
 /**
  * Merge `{ locale: { hash: target } }` into each `locales/{locale}.json`,
  * preserving existing entries (translations for strings not in this projection are
- * kept — `uniweb i18n audit --clean` removes genuine orphans). Keys are sorted so
- * the output is byte-stable / idempotent. Creates `locales/` if absent.
+ * kept — `uniweb i18n audit --clean` removes genuine orphans). An entry keeps its place
+ * in the file, and new ones follow it, sorted, so a pull that changes nothing writes
+ * nothing. Creates `locales/` if absent.
  *
  * @returns {{ [locale: string]: 'updated' | 'unchanged' }}
  */
 export function writeLocaleTranslations(siteRoot, byLocale, subdir = '') {
   const report = {}
-  for (const [locale, entries] of Object.entries(byLocale || {})) {
+  for (let [locale, entries] of Object.entries(byLocale || {})) {
     if (!entries || Object.keys(entries).length === 0) continue
     const filePath = localeFilePath(siteRoot, locale, subdir)
 
     let existing = {}
+    let order = []
     if (existsSync(filePath)) {
       try {
-        const parsed = JSON.parse(readFileSync(filePath, 'utf8'))
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) existing = parsed
+        const text = readFileSync(filePath, 'utf8')
+        const parsed = JSON.parse(text)
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          existing = parsed
+          order = topLevelKeyOrder(text).filter((key) => key in parsed)
+        }
       } catch {
         // unreadable / invalid → start fresh
       }
     }
 
-    const merged = { ...existing, ...entries }
-    const sorted = {}
-    for (const key of Object.keys(merged).sort()) sorted[key] = merged[key]
-    const next = JSON.stringify(sorted, null, 2) + '\n'
+    // ⭐ A FILE THE PULL ADDS NOTHING TO IS LEFT AS IT IS, and one it does keeps its order: an entry
+    // changes in its place, and new ones follow, sorted. ⛔ Until 2026-09-26 every pull re-sorted the
+    // whole file by hash — measured on the `international` template, whose `es.json` runs in page
+    // order: a pull that changed no translation rewrote all 77 lines.
+    // A translation read in several sections becomes the string or the `{ default, overrides }` the
+    // author keeps (`reconcileTranslation`).
+    entries = Object.fromEntries(
+      Object.entries(entries).map(([key, value]) => [key, value instanceof SeenInContexts ? reconcileTranslation(existing[key], value) : value])
+    )
+    const fresh = Object.keys(entries).filter((key) => !(key in existing)).sort()
+    if (fresh.length === 0 && Object.entries(entries).every(([key, value]) => canonicalJson(existing[key]) === canonicalJson(value))) {
+      report[locale] = 'unchanged'
+      continue
+    }
+    // An entry the pull did not change keeps its value as written — key order included.
+    const merged = [...new Set([...order, ...Object.keys(existing)])].map((key) => [
+      key,
+      key in entries && canonicalJson(entries[key]) !== canonicalJson(existing[key]) ? entries[key] : existing[key],
+    ])
+    for (const key of fresh) merged.push([key, entries[key]])
+    const next = jsonObjectText(merged)
 
     let current = null
     try {