@uniweb/build 0.63.4 → 0.64.1

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 {

package/src/uwx/open-graph.js

@@ -0,0 +1,69 @@
+// ⭐ A PAGE'S OR A SITE'S OPEN GRAPH TITLE AND DESCRIPTION, PER LANGUAGE — `og_title` and
+// `og_description` on the wire, `seo.ogTitle` / `seo.ogDescription` in a file.
+//
+// A file keeps them inside `seo`, whose other keys are crawler and sitemap directives a deployment
+// stores as one object. Where the deployment's page — or `settings` — Section declares the two keys
+// (`GET /dev/config` → `siteContent.pageFields` / `settingsFields`), a push sends them per language
+// through those keys and the rest of `seo` as it is; elsewhere they ride inside `seo` as authored,
+// in the source language only. A pull puts them back inside `seo`.
+import { localizeScalar } from './locale-sync.js'
+import { unwrapLocalized } from './backfill.js'
+
+// wire key → the key inside a file's `seo`
+const OPEN_GRAPH_KEYS = [
+  ['og_title', 'ogTitle'],
+  ['og_description', 'ogDescription'],
+]
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/** Whether a Section's declared keys take the two. */
+export function takesOpenGraph(fields) {
+  return Array.isArray(fields) && OPEN_GRAPH_KEYS.every(([wire]) => fields.includes(wire))
+}
+
+/**
+ * A file's `seo` as a push sends it: `{ og_title?, og_description?, seo? }`. The two are taken out
+ * of `seo` and localized only where the Section takes them; `seo` is left out when nothing else is
+ * in it. A value that is not a string stays where it is.
+ */
+export function splitOpenGraph(seo, fields, sourceLocale, translations, context = null) {
+  if (!takesOpenGraph(fields) || !isRecord(seo)) return { seo }
+  const rest = { ...seo }
+  const out = {}
+  for (const [wire, key] of OPEN_GRAPH_KEYS) {
+    if (typeof seo[key] !== 'string') continue
+    out[wire] = localizeScalar(seo[key], sourceLocale, translations, context)
+    delete rest[key]
+  }
+  out.seo = Object.keys(rest).length ? rest : undefined
+  return out
+}
+
+/** One of the two, as a push sends it — or undefined where the Section does not take them. */
+export function openGraphValue(seo, wire, fields, sourceLocale, translations, context = null) {
+  return splitOpenGraph(seo, fields, sourceLocale, translations, context)[wire]
+}
+
+/** `seo` as a push sends it beside the two — without them where the Section takes them. */
+export function seoBesideOpenGraph(seo, fields) {
+  return splitOpenGraph(seo, fields, null, null).seo
+}
+
+/**
+ * A document's `og_title` / `og_description` folded back into a file's `seo` — the source
+ * language's value — with the other languages handed to `collector` in `context`. Returns `seo`
+ * unchanged when the holder carries neither, and undefined for an empty result.
+ */
+export function foldOpenGraph(holder, seo, sourceLocale, collector = null, context = null) {
+  if (!OPEN_GRAPH_KEYS.some(([wire]) => holder?.[wire] !== undefined)) return seo
+  const out = isRecord(seo) ? { ...seo } : {}
+  for (const [wire, key] of OPEN_GRAPH_KEYS) {
+    const value = holder?.[wire]
+    if (value === undefined) continue
+    collector?.add(value, context)
+    const source = unwrapLocalized(value, sourceLocale)
+    if (typeof source === 'string' && source !== '') out[key] = source
+  }
+  return Object.keys(out).length ? out : undefined
+}