@uniweb/build 1.3.5 → 1.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "~1.4.0",
-    "@uniweb/projections": "~1.1.1",
     "@uniweb/content-writer": "~1.1.2",
+    "@uniweb/projections": "~1.1.1",
+    "@uniweb/theming": "~1.2.0",
     "@uniweb/schemas": "~1.3.0",
-    "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/theming": "~1.2.0"
+    "@uniweb/semantic-parser": "~1.8.1"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.4"

package/src/i18n/data-models.js

@@ -11,6 +11,12 @@
  * 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.
+ *
+ * ⛔ A key that DOES declare a shape, which the translation step cannot read, is said aloud
+ * (`warnUnreadable`): its blocks fall back to the heuristic, which never offers a field named
+ * `email`, `time`, `href` and the like. ⛔ Until 2026-10-16 that fall was silent — measured on a
+ * block of contact labels declared `{ type: 'object', values: { type: 'string' } }`, whose `email`
+ * and `time` labels were never offered for translation.
  */
 import { normalizeData } from '@uniweb/schemas/foundation'
 import { foundationSections, resolveRecordSchemas } from '../site/queries-config.js'
@@ -27,6 +33,9 @@ export const NO_DATA_MODELS = () => null
  * @returns {Promise<(type: string, tag: string) => object|null>}
  */
 export async function dataBlockModels(siteRoot, siteYml = null) {
+  // Each key's declaration as written, to say what was meant when its shape cannot be read.
+  const raw = new Map()
+  const warn = (where, reason) => warnUnreadable(siteRoot, where, reason, raw.get(where))
   let sections
   try {
     sections = await foundationSections(siteRoot, siteYml)
@@ -39,7 +48,10 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
   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 [key, decl] of Object.entries(normalized || {})) {
+      declared.set(at(owner, key), decl)
+      raw.set(at(owner, key), data?.[key])
+    }
   }
   for (const [name, entry] of Object.entries(sections)) {
     if (!entry || typeof entry !== 'object' || name === 'dataSchemas' || name === '_layouts') continue
@@ -62,8 +74,11 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
   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'))
+      const { kind: _kind, problems, ...schema } = decl
+      let lowering = null
+      const model = modelOf(schema, '@/inline', (err) => (lowering = err))
+      if (problems?.length || !model) warn(where, problems?.length ? problems.join('; ') : lowering?.message || 'it lowers to no model')
+      models.set(where, model)
     } else models.set(where, null)
   }
 
@@ -75,3 +90,24 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
 }
 
 const at = (owner, key) => `${owner}\u0000${key}`
+
+// Each unreadable shape once per site per process: extraction, the build, a push and a pull all
+// read the same declarations.
+const warned = new Set()
+
+function warnUnreadable(siteRoot, where, reason, declaration) {
+  const [owner, key] = where.split('\u0000')
+  const once = `${siteRoot}\u0000${where}\u0000${reason}`
+  if (warned.has(once)) return
+  warned.add(once)
+  const who = owner ? `the ${owner} section type` : 'the foundation (main.js)'
+  const fieldsCalledType = declaration && typeof declaration === 'object' && typeof declaration.type === 'string' && ('values' in declaration || 'fields' in declaration)
+  const hint = fieldsCalledType
+    ? ` A data key is declared as its block's fields: { type: '${declaration.type}', ${'values' in declaration ? 'values' : 'fields'}: … } declares two fields, named "type" and "${'values' in declaration ? 'values' : 'fields'}" — name the block's fields instead ({ email: 'string', time: 'string' }).`
+    : /open map/.test(reason)
+      ? " An open map is read when its values are records: values: { type: 'object', fields: { … } }."
+      : ''
+  console.warn(
+    `Warning: ${who} declares data key "${key}" with a shape the translation step cannot read (${reason}), so its blocks' strings are guessed — a field named email, time, href or the like is never offered for translation.${hint}`
+  )
+}

package/src/i18n/merge.js

@@ -207,9 +207,14 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
  *
  * ⛔ Do not add the field or the role to the hash. Genuine wording divergence by
  * context is what `overrides` is for (`lookupTranslation`); representation
- * divergence is this function's job.
+ * divergence is this function's job — and `translatedInline`'s, for an element whose
+ * source has no link.
+ *
+ * ⭐ One rule for both lanes: a push sends a plain-text slot's translations through it too
+ * (`uwx/locale-sync.js::plainTextTargets`). ⛔ Until 2026-10-16 only the build did, so a host
+ * was handed `[Sign in](/sign-in)` as a page's French title.
  */
-function toPlainText(value) {
+export function toPlainText(value) {
   if (typeof value !== 'string' || !value.includes('[') && !value.includes('*') && !value.includes('`') && !value.includes('_')) {
     return value
   }
@@ -239,7 +244,8 @@ function translateSiteMeta(config, translations, fallbackToSource) {
   if (!seo || typeof seo !== 'object') return
   for (const key of ['ogTitle', 'ogDescription']) {
     if (typeof seo[key] === 'string' && seo[key]) {
-      seo[key] = lookupTranslation(seo[key], SITE_META_CONTEXT, translations, fallbackToSource)
+      // A plain-text slot, as a page's are (`translatePageMeta`). ⛔ Not flattened until 2026-10-16.
+      seo[key] = toPlainText(lookupTranslation(seo[key], SITE_META_CONTEXT, translations, fallbackToSource))
     }
   }
 }
@@ -381,9 +387,19 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
  * its link: the button became a plain paragraph, or vanished from a section that renders only
  * links. Locale files keyed before whole-element keying hold exactly such labels.
  *
- * A value that writes a link is taken as written, re-targeted or not. So is a plain value for an
- * element that mixes words and links, since which words were linked cannot be known;
- * `uniweb i18n status` reports that loss (`translationKeepsMarkup`).
+ * ⭐ And a link is the SOURCE's to have: a value that writes one, given to an element whose source
+ * has none, gives it its words alone. One text is one unit wherever it appears (`hash.js`), so its
+ * value serves a heading that says it and a link that says it alike — `Faculty of Science` in a
+ * header, `[Faculty of Science](/)` in a list — and the link belongs to the place that has one.
+ * Representation is the consumer's, as a title's is (`toPlainText`). ⛔ Until 2026-10-16 the value
+ * was taken as written: `uniweb i18n init` seeds a unit with the markup of whichever occurrence
+ * carries some, so an untouched seeded locale turned the heading into a link — and the parser,
+ * which reads a heading made only of a link as a link, left its section without a title.
+ *
+ * A value that writes a link, given to an element whose source has one, is taken as written,
+ * re-targeted or not. So is a plain value for an element that mixes words and links, since which
+ * words were linked cannot be known; `uniweb i18n status` reports that loss
+ * (`translationKeepsMarkup`). Emphasis is the translator's: a value's bold or italic stays.
  *
  * @param {Array} source - the element's source inline content
  * @param {string} value - the translation, inline markdown
@@ -392,7 +408,36 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
 export function translatedInline(source, value) {
   const fragment = inlineMarkdownToFragment(value)
   if (!fragment) return null
-  return asLinkLabels(source, fragment, value) || fragment
+  const labels = asLinkLabels(source, fragment, value)
+  if (labels) return labels
+  return hasLink(source) ? fragment : withoutLinks(fragment)
+}
+
+// Whether inline content holds a link — on its text, or inside an inline wrapper.
+function hasLink(nodes) {
+  return (nodes || []).some((node) => Boolean(linkMarkOf(node)) || hasLink(node?.content))
+}
+
+// Inline content without its links: the words, and every other mark, kept — runs that end up
+// alike joined, as the reader would have written them.
+function withoutLinks(nodes) {
+  const out = []
+  for (const node of nodes) {
+    let next = node
+    if (node?.content) next = { ...node, content: withoutLinks(node.content) }
+    else if (linkMarkOf(node)) {
+      const { marks, ...rest } = node
+      const kept = marks.filter((mark) => mark.type !== 'link')
+      next = kept.length ? { ...rest, marks: kept } : rest
+    }
+    const last = out[out.length - 1]
+    if (last?.type === 'text' && next?.type === 'text' && JSON.stringify(last.marks || []) === JSON.stringify(next.marks || [])) {
+      out[out.length - 1] = { ...last, text: last.text + next.text }
+    } else {
+      out.push(next)
+    }
+  }
+  return out
 }
 
 /**
@@ -581,7 +626,7 @@ function translateDataBlocks(doc, context, translations, fallbackToSource, model
         const data = node.attrs?.data
         if (data && typeof data === 'object') {
           visitDataBlockStrings(data, (value) => {
-            const translated = lookupTranslation(value, context, translations, fallbackToSource)
+            const translated = asDataString(value, lookupTranslation(value, context, translations, fallbackToSource))
             if (translated !== value) changed = true
             return translated
           }, modelFor(node.attrs?.tag))
@@ -595,6 +640,18 @@ function translateDataBlocks(doc, context, translations, fallbackToSource, model
   return changed
 }
 
+/**
+ * ⭐ A data block's string written as TEXT takes its translation as text — the rule an element
+ * with no link follows (`translatedInline`), for a string a component renders as it is: the markup a
+ * translation carries for a link elsewhere is not this string's. ⛔ Until 2026-10-16 it was taken
+ * as written, and a label shared with a link rendered as `[Sign in](/sign-in)`. A string written
+ * with markdown keeps its translation as written.
+ */
+function asDataString(source, translated) {
+  if (typeof translated !== 'string' || translated === source) return translated
+  return toPlainText(source) === source ? toPlainText(translated) : translated
+}
+
 /**
  * Resolve ONE ProseMirror content doc for a single target locale: a deep clone of
  * the source doc with each whole-element translated (inline content replaced from

package/src/i18n/records.js

@@ -187,11 +187,12 @@ function isFieldTranslatable(fieldDef) {
  * @param {string} ref - the ref it was resolved from
  * @returns {Object|null} the lowered declaration, or null when there is none
  */
-export function modelOf(schema, ref) {
+export function modelOf(schema, ref, onError = null) {
   if (!schema) return null
   try {
     return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
-  } catch {
+  } catch (err) {
+    onError?.(err) // a caller that can say why — `data-models.js`, for a declared block shape
     return null // a schema a push refuses is refused there, and the build keeps its heuristic
   }
 }

package/src/uwx/locale-sync.js

@@ -24,7 +24,7 @@ import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-w
 import { computeHash } from '../i18n/hash.js'
 import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
 import { visitDataBlockStrings } from '../i18n/data-strings.js'
-import { resolveDocForLocale, translatedInline, linkLabels } from '../i18n/merge.js'
+import { resolveDocForLocale, translatedInline, linkLabels, toPlainText } from '../i18n/merge.js'
 import { computeSourceHash } from '../i18n/freeform-manifest.js'
 import { sameMarkdownDocument, canonicalJson } from './same-content.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
@@ -250,6 +250,30 @@ export function contextKey(context) {
  * @param {string} sourceLocale
  * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
  */
+/**
+ * A localized PLAIN-TEXT value — a page's title, label, description, keywords and Open Graph
+ * texts, and the site's — with each translation as text, as the build renders it
+ * (`i18n/merge.js::toPlainText`). The source stays as the author wrote it, as the build leaves it.
+ * ⛔ Until 2026-10-16 a push sent a translation's markdown as it was, so a unit shared by a page's
+ * title and a link to the page reached a host as `[Sign in](/sign-in)`.
+ *
+ * @param {object|Array|undefined} value - a `{ locale: text }` map, or a list of them
+ * @param {string} sourceLocale
+ */
+export function plainTextTargets(value, sourceLocale) {
+  if (Array.isArray(value)) return value.map((item) => plainTextTargets(item, sourceLocale))
+  if (!value || typeof value !== 'object') return value
+  let out = value
+  for (const [locale, text] of Object.entries(value)) {
+    if (locale === sourceLocale || typeof text !== 'string') continue
+    const plain = toPlainText(text)
+    if (plain === text) continue
+    if (out === value) out = { ...value }
+    out[locale] = plain
+  }
+  return out
+}
+
 export function localizeScalarList(value, sourceLocale, translations, context = null) {
   if (value == null) return undefined
   if (!Array.isArray(value)) return localizeScalar(value, sourceLocale, translations, context)

package/src/uwx/records-project.js

@@ -54,6 +54,7 @@ import { LINK_MODEL, writeLinkRecords } from './link-records.js'
 import { FILE_MODEL, filesToPull } from './file-records.js'
 import { parseBibtex } from '@citestyle/bibtex'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
+import { siteSourceLocale } from './source-locale.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
 
 // Single-record source extensions we scan + place (BibTeX is multi-record → out).
@@ -527,7 +528,7 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * @returns {{ status: 'updated'|'unchanged'|'removed'|'skipped', entries: Array, warnings: string[], file: string }}
  *   `file` is where the organization lives, as the author would write it
  */
-export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = 'en' }) {
+export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = siteSourceLocale(siteRoot) }) {
   const warnings = []
   const { abs, rel: file } = folderYmlPath(siteRoot)
   if (!folderDoc) return { status: 'skipped', entries: [], warnings, file }
@@ -625,7 +626,9 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
  * @returns {{ updated: string[], placed: string[], unchanged: string[], skipped: object[], warnings: string[], locales: object }}
  */
 export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts = {} }) {
-  const { resolveDeclaration, sourceLocale = 'en' } = opts
+  // The site's language, as its `site.yml` says it — written by the pull of the site's content, which
+  // runs first (`./source-locale.js`).
+  const { resolveDeclaration, sourceLocale = siteSourceLocale(siteRoot) } = opts
   refuseOrgOption(opts, 'recordsToProject')
   // The scope the push qualified `@/x` with — the site's foundation's — so a
   // `@scope/x` model is placed back where the author wrote it. ⛔ It was the site

package/src/uwx/records.js

@@ -64,6 +64,7 @@ import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { isUuid } from './uuid.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { siteSourceLocale } from './source-locale.js'
 import { localizeScalar, localizeScalarList, localizeContentDoc, loadLocaleTranslations, discoverLocales, discoverFreeformLocales, localesDir, isLocalizedContent } from './locale-sync.js'
 import { loadFreeformRecord } from '../i18n/freeform.js'
 import { isDraftRecord } from '../site/record-draft.js'
@@ -1031,7 +1032,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   }
 
   const sourceLocale =
-    opts.sourceLocale || LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale
+    opts.sourceLocale || siteSourceLocale(siteRoot)
 
   // Target locales for wrapping localized record fields per-locale: those with a
   // structural-translation file (locales/records/{locale}.json) UNIONED with

package/src/uwx/site-diff.js

@@ -48,7 +48,7 @@
 
 import { entityContentHash } from './records.js'
 import { sectionFileBase, pageDirName, layoutSectionPaths } from './site-project.js'
-import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { documentSourceLocale } from './source-locale.js'
 
 // A unit's own content, with the nested collections that are their own units
 // removed — so editing a section never also marks its page (or its parent
@@ -70,7 +70,7 @@ const ownContent = (record, ...childKeys) => {
  *
  * @returns {Map<string, object>} path → the unit's own record
  */
-export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function collectSiteUnits(doc, sourceLocale = documentSourceLocale(doc)) {
   const units = new Map()
   walkSiteUnits(doc, (path, record, kind) => {
     units.set(
@@ -93,7 +93,7 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
  *
  * @param {(path: string, record: object, kind: 'info'|'page'|'section') => void} cb
  */
-export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc)) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
       // The projector's own file rule — including an app-created section named from its
@@ -353,7 +353,7 @@ const KEYED_SECTIONS = {
  *
  * @returns {Map<string, { uuid: string|null, record: object }>}
  */
-export function siteItemsByKey(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function siteItemsByKey(doc, sourceLocale = documentSourceLocale(doc)) {
   const out = new Map()
   const uuidOf = (record) => (typeof record?.$uuid === 'string' && record.$uuid ? record.$uuid : null)
   const units = collectSiteUnits(doc, sourceLocale)

package/src/uwx/site-project.js

@@ -52,6 +52,7 @@ import { unwritableNodes } from '@uniweb/content-writer'
 import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { documentSourceLocale } from './source-locale.js'
 import { siteContentDirs } from './site-dirs.js'
 import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
 import { layoutNameKey } from '@uniweb/core/layout-name'
@@ -215,7 +216,7 @@ function readAuthoredYaml(filePath) {
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
  *          write status ('updated' | 'unchanged')
  */
-export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
+export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false }) {
   const info = document?.info || {}
   const settingsSection = document?.settings || {}
 
@@ -1272,7 +1273,8 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
  * @param {object} params
  * @param {object} params.document - the `@uniweb/site-content` `$`-document
  * @param {string} params.siteRoot
- * @param {string} [params.sourceLocale]
+ * @param {string} [params.sourceLocale] - the language the document is written in; by default its
+ *        own `settings`, by the rule its push wrapped it with (`documentSourceLocale`)
  * @param {boolean} [params.prune=false] - delete orphaned pages/sections/layout
  *        files that have no corresponding incoming item (git-pull-like). Off by
  *        default; `uniweb pull` opts in. Guarded against wiping a level on an
@@ -1282,7 +1284,7 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
  *        `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, dataModel = null }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
   // Before anything is written: a pull that would leave content out of the files stops here.
   refuseContentFilesCannotHold(document, sourceLocale)
 

package/src/uwx/site.js

@@ -73,7 +73,7 @@ import { readLayoutFolder, layoutAreaRoute } from '../site/layout-folder.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
-import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
+import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent, plainTextTargets } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { resolveLocaleList } from '../i18n/locales.js'
@@ -264,11 +264,13 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
 // build translates them (`i18n/merge.js::translatePageMeta`, `<route>:_meta`): an override for one
 // page applies there and nowhere else. ⛔ Until 2026-09-26 they were resolved with no page, so an
 // override never reached a backend — nor, until the same day, an entry's default.
+// ⭐ Each is a plain-text slot, so a translation reaches it as text, as the build renders it
+// (`plainTextTargets`).
 function localizePageMeta(page, route, sourceLocale, translations) {
   const context = { page: route, section: '_meta' }
   const again = (value) =>
     value && typeof value === 'object' && typeof value[sourceLocale] === 'string'
-      ? localizeScalar(value[sourceLocale], sourceLocale, translations, context)
+      ? plainTextTargets(localizeScalar(value[sourceLocale], sourceLocale, translations, context), sourceLocale)
       : value
   for (const key of ['title', 'label', 'description', 'og_title', 'og_description']) {
     if (page[key] !== undefined) page[key] = again(page[key])
@@ -1306,14 +1308,15 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // The site's Open Graph title and description per language, where the deployment's `settings`
   // takes them (`uwx/open-graph.js`), in the site's context (`SITE_META_CONTEXT`).
   // (Each read inline from `siteYml.seo`, so the emit surface names its source.)
-  setIf(settings, 'og_title', openGraphValue(siteYml.seo, 'og_title', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
-  setIf(settings, 'og_description', openGraphValue(siteYml.seo, 'og_description', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
+  // Plain-text slots, each translation as text (`plainTextTargets`).
+  setIf(settings, 'og_title', plainTextTargets(openGraphValue(siteYml.seo, 'og_title', settingsFields, sourceLocale, translations, SITE_META_CONTEXT), sourceLocale))
+  setIf(settings, 'og_description', plainTextTargets(openGraphValue(siteYml.seo, 'og_description', settingsFields, sourceLocale, translations, SITE_META_CONTEXT), sourceLocale))
   setIf(settings, 'seo', seoBesideOpenGraph(siteYml.seo, settingsFields))
   // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
   // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
   // convenience, not because it is a different kind of thing. Localized, so it
   // carries the translation collector with it.
-  setIf(settings, 'keywords', localizeScalarList(siteYml.keywords, sourceLocale, translations))
+  setIf(settings, 'keywords', plainTextTargets(localizeScalarList(siteYml.keywords, sourceLocale, translations), sourceLocale))
 
   // ⛔ NO SERVICE IS HERE. A service's address and options ride its row in the
   // `services` Section, whole (`requestedServices`) [Diego, 2026-10-06: "If it's on and
@@ -1431,7 +1434,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // a localized `{lang:value}` map. Genuine content fields (`description` below, page
   // title/slug/label/keywords, the body) stay localized. (uwx-format.md → identity-label names.)
   info.name = siteYml.name
-  setIf(info, 'description', localizeScalar(siteYml.description, sourceLocale, translations))
+  setIf(info, 'description', plainTextTargets(localizeScalar(siteYml.description, sourceLocale, translations), sourceLocale))
   // Publish intent (site.yml `publishLanguages:`) rides VERBATIM — dangling
   // codes included. Sync carries the full working set; only *publish* filters
   // (backend projection / static-build filter). The verbatim carry is what

package/src/uwx/source-locale.js

@@ -0,0 +1,57 @@
+/**
+ * ⭐ THE LANGUAGE A SITE IS WRITTEN IN — the locale every localized value of it is keyed by on the
+ * sync wire, its source. One rule for both directions, `resolveDefaultLocale`
+ * (`@uniweb/core/locale-config`): `defaultLanguage`, else the first of `languages`, else `en`.
+ *
+ * - From the files, `site.yml` (`siteSourceLocale`): what a push wraps pages, records and folder
+ *   labels under.
+ * - From a document, its `settings` (`documentSourceLocale`): what a pull unwraps them by, and what
+ *   keys a document's units. A push sends `default_language` when the site names one, and its
+ *   `languages` source first (`uwx/site.js`), so the rule over a document gives back the language
+ *   the push wrapped it in.
+ *
+ * ⛔ Until 2026-10-16 only the page push asked the site. The record push and every pull assumed
+ * `en`, which every site measured until then happened to be written in: a French site with an
+ * English translation came back from a pull in English, its own text filed as a translation of it;
+ * a French-only clone came back with empty sections; and its records were pushed labelled English,
+ * their English translations left out.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+
+/**
+ * The language a site's files are written in — `site.yml`'s, by the shared rule.
+ *
+ * @param {string} siteRoot - the directory holding `site.yml`
+ * @returns {string}
+ */
+export function siteSourceLocale(siteRoot) {
+  const path = join(siteRoot, 'site.yml')
+  let siteYml = null
+  if (existsSync(path)) {
+    try {
+      siteYml = yaml.load(readFileSync(path, 'utf8'), YAML_OPTIONS)
+    } catch {
+      siteYml = null // an unreadable site.yml is reported by whoever reads it for more
+    }
+  }
+  return resolveDefaultLocale(siteYml && typeof siteYml === 'object' ? siteYml : {})
+}
+
+/**
+ * The language a `@uniweb/site-content` document's localized values are keyed by — its
+ * `settings`, by the shared rule.
+ *
+ * @param {object} document - the site-content `$`-document
+ * @returns {string}
+ */
+export function documentSourceLocale(document) {
+  const settings = document?.settings
+  return resolveDefaultLocale({
+    defaultLanguage: settings?.default_language,
+    languages: settings?.languages,
+  })
+}

package/src/uwx/sync-package.js

@@ -25,6 +25,7 @@ import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { fileRecordUploads } from './file-records.js'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
+import { siteSourceLocale } from './source-locale.js'
 import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
 import { emitEntitySyncPackage } from './entity-document.js'
@@ -299,7 +300,10 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  */
 export async function emitSyncPackages(siteRoot, opts = {}) {
   const includeSite = opts.includeSite !== false
-  const sourceLocale = opts.sourceLocale
+  // ⭐ ONE LANGUAGE FOR THE WHOLE EMIT — the site's (`./source-locale.js`): its pages, its records,
+  // its folder's labels and the paths its units are keyed by. ⛔ Until 2026-10-16 only the pages asked
+  // the site; the rest assumed `en`.
+  const sourceLocale = opts.sourceLocale || siteSourceLocale(siteRoot)
   const priorHashes = opts.priorHashes || {}
   const sendAll = !!opts.sendAll
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})