@uniweb/build 1.20.10 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.20.10",
3
+ "version": "1.22.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,15 +57,15 @@
57
57
  "js-yaml": "^4.3.2",
58
58
  "sharp": "^0.35.5",
59
59
  "yaml": "^2.5.0",
60
- "@uniweb/content-reader": "~1.5.9",
61
- "@uniweb/projections": "~1.2.16",
60
+ "@uniweb/content-reader": "~1.5.10",
61
+ "@uniweb/content-writer": "~1.3.2",
62
+ "@uniweb/projections": "~1.2.17",
62
63
  "@uniweb/schemas": "~1.7.1",
63
- "@uniweb/semantic-parser": "~1.13.3",
64
- "@uniweb/content-writer": "~1.3.1",
64
+ "@uniweb/semantic-parser": "~1.13.4",
65
65
  "@uniweb/theming": "~1.3.2"
66
66
  },
67
67
  "optionalDependencies": {
68
- "@uniweb/runtime": "~1.5.9"
68
+ "@uniweb/runtime": "~1.6.1"
69
69
  },
70
70
  "peerDependencies": {
71
71
  "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
74
74
  "@tailwindcss/vite": "^4.0.0",
75
75
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
76
76
  "vite-plugin-svgr": "^4.0.0",
77
- "@uniweb/core": "~1.6.12",
78
- "@uniweb/runtime": "~1.5.9"
77
+ "@uniweb/runtime": "~1.6.1",
78
+ "@uniweb/core": "~1.6.12"
79
79
  },
80
80
  "peerDependenciesMeta": {
81
81
  "vite": {
@@ -0,0 +1,149 @@
1
+ /**
2
+ * A foundation's mappings — `src/mappings/<name>.yml`, one per file: how a vendor's file translates
3
+ * to and from one of the foundation's types (a catalog CSV ⇄ `@/vehicle`, a lead's XML ⇄ `@/lead`).
4
+ *
5
+ * ```yaml
6
+ * # src/mappings/vehicle-to-meta.yml
7
+ * label: Meta catalog
8
+ * model: '@/vehicle' # the type, named as a data schema names one
9
+ * direction: out
10
+ * shape: list
11
+ * format: { type: csv }
12
+ * key: id
13
+ * keys_from: '@/dms-inventory' # optional: another mapping
14
+ * fields:
15
+ * - { title: listing.title }
16
+ * ```
17
+ *
18
+ * ⭐ THE FOLDER IS THE DECLARATION, as `schemas/` is for data schemas (`ownSchemaFiles`): a file is
19
+ * a mapping by being there, its name is the file's, a name with a leading `_` is left out, and
20
+ * `.js .json .yml .yaml` all count.
21
+ *
22
+ * ⭐ THE BACKEND JUDGES THE RULES. A mapping is registered with its foundation (`registry-package.js`,
23
+ * `@uniweb/mapping-schema`) and a backend checks it there. The build refuses only what can't be
24
+ * registered at all, so the author learns of it at the build and not at `register`:
25
+ *
26
+ * - a file that is not a map, or a `label`/`description` that is not text;
27
+ * - a `model` that is missing or names no type, or an `@/x` the foundation doesn't define;
28
+ * - a `keys_from` that names no mapping, or an `@/x` that isn't one of the foundation's.
29
+ *
30
+ * Mappings are editor-time only: they ride in `schema.json` as `_mappings` and never reach a page.
31
+ *
32
+ * @module
33
+ */
34
+
35
+ import { existsSync, readdirSync } from 'node:fs'
36
+ import { readFile } from 'node:fs/promises'
37
+ import { join, extname, basename } from 'node:path'
38
+ import { pathToFileURL } from 'node:url'
39
+ import yaml from 'js-yaml'
40
+ import { SCHEMA_EXTENSIONS, parseSchemaRef } from '@uniweb/schemas/format'
41
+ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
42
+
43
+ /** The folder, under a foundation's source root. */
44
+ export const MAPPINGS_DIR = 'mappings'
45
+
46
+ const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
47
+
48
+ /**
49
+ * The mapping files a foundation defines, by name, sorted.
50
+ *
51
+ * @param {string} srcDir - the foundation's source root
52
+ * @returns {{ name: string, file: string }[]}
53
+ */
54
+ export function ownMappingFiles(srcDir) {
55
+ const dir = join(srcDir, MAPPINGS_DIR)
56
+ if (!existsSync(dir)) return []
57
+ return readdirSync(dir)
58
+ .sort()
59
+ .filter((file) => SCHEMA_EXTENSIONS.includes(extname(file)) && !file.startsWith('_'))
60
+ .map((file) => ({ name: basename(file, extname(file)), file: join(dir, file) }))
61
+ }
62
+
63
+ async function loadMappingFile(file) {
64
+ if (file.endsWith('.js')) return (await import(pathToFileURL(file).href)).default
65
+ const text = await readFile(file, 'utf8')
66
+ return file.endsWith('.json') ? JSON.parse(text) : yaml.load(text, YAML_OPTIONS)
67
+ }
68
+
69
+ /**
70
+ * Read and check every mapping a foundation defines.
71
+ *
72
+ * @param {string} srcDir - the foundation's source root
73
+ * @param {object} [opts]
74
+ * @param {Iterable<string>} [opts.ownTypes] - the `@/x` data schemas the foundation defines
75
+ * @returns {Promise<Object<string, object>>} `{ '@/<name>': declaration }` as written (`@/x` unqualified)
76
+ * @throws {Error} naming every mapping that cannot be registered, and why
77
+ */
78
+ export async function buildMappingMap(srcDir, { ownTypes = [] } = {}) {
79
+ const files = ownMappingFiles(srcDir)
80
+ if (!files.length) return {}
81
+ const types = new Set(ownTypes)
82
+ const names = new Set(files.map(({ name }) => `@/${name}`))
83
+ const map = {}
84
+ const found = []
85
+ for (const { name, file } of files) {
86
+ const at = `src/${MAPPINGS_DIR}/${basename(file)}`
87
+ let decl
88
+ try {
89
+ decl = await loadMappingFile(file)
90
+ } catch (err) {
91
+ found.push(`${at}: ${String(err?.message || err).split('\n')[0]}`)
92
+ continue
93
+ }
94
+ const problems = mappingProblems(decl, { types, names })
95
+ if (problems.length) found.push(...problems.map((p) => `${at}: ${p}`))
96
+ else map[`@/${name}`] = decl
97
+ }
98
+ if (found.length) {
99
+ throw new Error(
100
+ found.length === 1
101
+ ? `[uniweb] ${found[0]}`
102
+ : `[uniweb] mappings that cannot be registered:\n${found.map((f) => ` - ${f}`).join('\n')}`
103
+ )
104
+ }
105
+ return map
106
+ }
107
+
108
+ /**
109
+ * What stops one mapping from registering — `[]` when nothing does.
110
+ *
111
+ * @param {*} decl - the file, as read
112
+ * @param {{ types: Set<string>, names: Set<string> }} own - the foundation's `@/x` types and mappings
113
+ * @returns {string[]}
114
+ */
115
+ export function mappingProblems(decl, { types, names }) {
116
+ if (!isMap(decl)) return ['a mapping is a map — `model:`, `direction:`, `fields:` and the rest.']
117
+ const found = []
118
+ for (const key of ['label', 'description']) {
119
+ if (key in decl && (typeof decl[key] !== 'string' || !decl[key].trim())) {
120
+ found.push(`\`${key}\` is text.`)
121
+ }
122
+ }
123
+ if (!('model' in decl)) {
124
+ found.push("`model` is missing: name the type the mapping translates, `model: '@/vehicle'`.")
125
+ } else {
126
+ const problem = refProblem('model', decl.model, 'type')
127
+ if (problem) found.push(problem)
128
+ else if (decl.model.startsWith('@/') && !types.has(decl.model)) {
129
+ found.push(`\`model\` is \`${decl.model}\`, which is not one of the foundation's types (src/schemas/).`)
130
+ }
131
+ }
132
+ if ('keys_from' in decl) {
133
+ const problem = refProblem('keys_from', decl.keys_from, 'mapping')
134
+ if (problem) found.push(problem)
135
+ else if (decl.keys_from.startsWith('@/') && !names.has(decl.keys_from)) {
136
+ found.push(`\`keys_from\` is \`${decl.keys_from}\`, which is not one of the foundation's mappings (src/${MAPPINGS_DIR}/).`)
137
+ }
138
+ }
139
+ return found
140
+ }
141
+
142
+ function refProblem(key, ref, what) {
143
+ try {
144
+ parseSchemaRef(ref)
145
+ return null
146
+ } catch {
147
+ return `\`${key}\` names no ${what}: one of the foundation's own is \`'@/<name>'\`, any other is named in full, \`'@scope/<name>'\`.`
148
+ }
149
+ }
package/src/i18n/audit.js CHANGED
@@ -13,14 +13,17 @@ import { join } from 'node:path'
13
13
  import { translationKeepsMarkup } from './merge.js'
14
14
  import { KEPT_FILE } from './locales.js'
15
15
  import { standingFlags } from '../uwx/locale-sync.js'
16
+ import { isInExcludedBranch } from '@uniweb/projections'
16
17
 
17
18
  /**
18
19
  * Audit a locale file against the manifest
19
20
  * @param {string} localesPath - Path to locales directory
20
21
  * @param {string} locale - Locale code (e.g., 'es')
21
- * @returns {Promise<Object>} Audit result { locale, exists, total, valid, missing, stale }
22
+ * @param {Object} [options]
23
+ * @param {string[]} [options.exclude] - the site's `i18n.exclude`
24
+ * @returns {Promise<Object>} Audit result { locale, exists, total, valid, missing, stale, excluded }
22
25
  */
23
- export async function auditLocale(localesPath, locale) {
26
+ export async function auditLocale(localesPath, locale, { exclude = null } = {}) {
24
27
  const manifestPath = join(localesPath, 'manifest.json')
25
28
  const localePath = join(localesPath, `${locale}.json`)
26
29
 
@@ -51,6 +54,7 @@ export async function auditLocale(localesPath, locale) {
51
54
  const valid = []
52
55
  const missing = []
53
56
  const stale = []
57
+ const excluded = []
54
58
  const losesMarkup = []
55
59
  const outdated = []
56
60
 
@@ -95,10 +99,13 @@ export async function auditLocale(localesPath, locale) {
95
99
  // Check for stale entries (in translations but not in manifest)
96
100
  for (const hash of translationHashes) {
97
101
  if (!manifestHashes.has(hash)) {
98
- stale.push({
99
- hash,
100
- translation: getTranslationText(translations[hash])
101
- })
102
+ const entry = { hash, translation: getTranslationText(translations[hash]) }
103
+ // ⭐ One written for a place on a page the site doesn't translate (`i18n.exclude`) applies there
104
+ // (`extract.js::translationContext`), and the manifest, which takes no string from such a page,
105
+ // can't judge it: it is listed apart, and `--clean` keeps it. ⛔ Until 2026-11-11 it was stale, and
106
+ // `--clean` deleted what a pull had brought back of an author's translation on such a page.
107
+ if (namesExcludedPlace(translations[hash], exclude)) excluded.push(entry)
108
+ else stale.push(entry)
102
109
  }
103
110
  }
104
111
 
@@ -109,11 +116,22 @@ export async function auditLocale(localesPath, locale) {
109
116
  valid,
110
117
  missing,
111
118
  stale,
119
+ excluded,
112
120
  losesMarkup,
113
121
  outdated
114
122
  }
115
123
  }
116
124
 
125
+ // Whether an entry's overrides name a place in a branch `exclude` names: `<route>:<section>`, whose
126
+ // route may hold a `:` of its own (`/blog/:slug:intro`).
127
+ function namesExcludedPlace(entry, exclude) {
128
+ if (!exclude || !entry || typeof entry !== 'object') return false
129
+ return Object.keys(entry.overrides || {}).some((place) => {
130
+ const at = place.lastIndexOf(':')
131
+ return at > 0 && isInExcludedBranch(place.slice(0, at), exclude)
132
+ })
133
+ }
134
+
117
135
  /**
118
136
  * Does the merge drop the inline markup this translation's source element carries?
119
137
  *
@@ -199,6 +217,9 @@ export function formatAuditReport(results, options = {}) {
199
217
  lines.push(` Valid: ${result.valid.length} (${coverage}%)`)
200
218
  lines.push(` Missing: ${result.missing.length}`)
201
219
  lines.push(` Stale: ${result.stale.length}`)
220
+ if (result.excluded?.length > 0) {
221
+ lines.push(` For pages i18n.exclude names: ${result.excluded.length} (each for one place there; --clean keeps them)`)
222
+ }
202
223
  if (result.losesMarkup?.length > 0) {
203
224
  lines.push(` Loses markup: ${result.losesMarkup.length} (links/bold in the source, plain in the translation)`)
204
225
  }
@@ -9,6 +9,7 @@ import { resolveDefaultLocale } from '@uniweb/core'
9
9
  import { computeHash, stripInlineTags } from './hash.js'
10
10
  import { visitDataBlockStrings } from './data-strings.js'
11
11
  import { serializeInlineContent } from '@uniweb/content-writer'
12
+ import { isInExcludedBranch } from '@uniweb/projections'
12
13
 
13
14
  /**
14
15
  * Extract all translatable units from site content
@@ -22,11 +23,19 @@ import { serializeInlineContent } from '@uniweb/content-writer'
22
23
  export function extractTranslatableContent(siteContent, { dataModel = null } = {}) {
23
24
  const units = {}
24
25
 
26
+ // ⭐ `i18n.exclude` — branches the site doesn't translate, such as a mounted repo's docs it shows in
27
+ // their own language: their pages give no strings, so `init`, `status` and the rest, which read the
28
+ // manifest, leave them alone. Routes as `agents.exclude` takes them (`isInExcludedBranch`). Their
29
+ // pages show the source in every language: only a translation written for one of their places
30
+ // applies there (`translationContext`).
31
+ const exclude = siteContent.config?.i18n?.exclude
32
+
25
33
  // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
26
34
  extractFromSiteMeta(siteContent.config, units)
27
35
 
28
36
  for (const page of siteContent.pages || []) {
29
37
  const pageRoute = page.route || '/'
38
+ if (isInExcludedBranch(pageRoute, exclude)) continue
30
39
 
31
40
  // Extract page metadata (title, description, keywords from page.yml)
32
41
  extractFromPageMeta(page, pageRoute, units)
@@ -38,7 +47,7 @@ export function extractTranslatableContent(siteContent, { dataModel = null } = {
38
47
  }
39
48
 
40
49
  // Extract from 404 page (stored as top-level notFound)
41
- if (siteContent.notFound) {
50
+ if (siteContent.notFound && !isInExcludedBranch(siteContent.notFound.route || '/404', exclude)) {
42
51
  const notFoundPage = siteContent.notFound
43
52
  const pageRoute = notFoundPage.route || '/404'
44
53
  extractFromPageMeta(notFoundPage, pageRoute, units)
@@ -147,12 +156,34 @@ function extractFromPageMeta(page, pageRoute, units) {
147
156
  * `1-hero.md`) — so an override moved to another section when files were renumbered, and a clone,
148
157
  * whose files are not numbered, could not key it at all.
149
158
  *
159
+ * ⭐ A PAGE IN A BRANCH THE SITE DOESN'T TRANSLATE (`i18n.exclude`, given as `exclude`) TAKES ONLY A
160
+ * TRANSLATION WRITTEN FOR ITS PLACE, and its context says so (`placeOnly`): an override naming the
161
+ * place, which is how a pull writes what an author translated there in the app, or a free-form file
162
+ * for it. A translation of the text wherever it appears, a plain entry or an entry's `default`, is
163
+ * not one. The build (`merge.js::lookupTranslation`), the push (`locale-sync.js::translationFor`) and
164
+ * the pull (`reconcileTranslation`) read it. ⛔ Until 2026-11-11 such a page took the site's
165
+ * translation of any string it shared with the site's own pages, so a mounted repo's docs, shown in
166
+ * English, read a sentence in Spanish where the site's home page had the same one.
167
+ *
150
168
  * @param {Object} section - a section with `stableId` (and the build `id` as a fallback)
151
169
  * @param {string} pageRoute - the route of the page (or layout area) it is on
152
- * @returns {{ page: string, section: string }}
170
+ * @param {string[]} [exclude] - the site's `i18n.exclude`; none for a layout area, which is the site's own
171
+ * @returns {{ page: string, section: string, placeOnly?: true }}
172
+ */
173
+ export function translationContext(section, pageRoute, exclude = null) {
174
+ const context = { page: pageRoute, section: section?.stableId || section?.id || 'unknown' }
175
+ return isInExcludedBranch(pageRoute, exclude) ? { ...context, placeOnly: true } : context
176
+ }
177
+
178
+ /**
179
+ * Where a page's own words are translated — its title, label, description and keywords:
180
+ * `<route>:_meta`, the place an override for them names (`translationContext`).
181
+ *
182
+ * @param {string} pageRoute
183
+ * @param {string[]} [exclude] - the site's `i18n.exclude`
153
184
  */
154
- export function translationContext(section, pageRoute) {
155
- return { page: pageRoute, section: section?.stableId || section?.id || 'unknown' }
185
+ export function pageMetaContext(pageRoute, exclude = null) {
186
+ return translationContext({ stableId: '_meta' }, pageRoute, exclude)
156
187
  }
157
188
 
158
189
  /**
package/src/i18n/index.js CHANGED
@@ -256,6 +256,21 @@ export async function extractRecordManifest(siteRoot, options = {}) {
256
256
  * @param {Object} options - Options
257
257
  * @returns {Object} Status per locale
258
258
  */
259
+ /**
260
+ * A language's words for a text, from its entry: the string, or an entry's `default`; an entry
261
+ * that gives only context-specific `overrides` gives words too. '' for none.
262
+ *
263
+ * @param {*} entry
264
+ * @returns {string}
265
+ */
266
+ function entryWords(entry) {
267
+ if (typeof entry === 'string') return entry
268
+ if (!entry || typeof entry !== 'object') return ''
269
+ if (typeof entry.default === 'string' && entry.default.trim()) return entry.default
270
+ const overrides = entry.overrides && typeof entry.overrides === 'object' ? Object.values(entry.overrides) : []
271
+ return overrides.find((value) => typeof value === 'string' && value.trim()) || ''
272
+ }
273
+
259
274
  export async function getTranslationStatus(siteRoot, options = {}) {
260
275
  const {
261
276
  localesDir = DEFAULTS.localesDir,
@@ -296,16 +311,22 @@ export async function getTranslationStatus(siteRoot, options = {}) {
296
311
  let translated = 0
297
312
  let missing = 0
298
313
  let outdated = 0
314
+ let unchanged = 0
299
315
 
300
- for (const hash of Object.keys(manifest.units)) {
316
+ for (const [hash, unit] of Object.entries(manifest.units)) {
301
317
  // An entry flagged `outdated` still renders, and is not this text's translation.
302
318
  if (Object.keys(standingFlags(translations[hash], translations, locale, kept)).length) {
303
319
  outdated++
304
- } else if (translatedHashes.has(hash)) {
305
- translated++
306
- } else {
307
- missing++
320
+ continue
308
321
  }
322
+ const words = translatedHashes.has(hash) ? entryWords(translations[hash]) : null
323
+ // ⭐ An empty entry is none: the build shows the source for it. And an entry that is the
324
+ // source's own text is what `uniweb i18n init` writes, so it is counted apart, not as a
325
+ // translation, whether the language says it the same way or nobody has translated it yet.
326
+ // ⛔ Until 2026-11-11 any entry counted, so a file `init` had just made read as all done.
327
+ if (words === null || !words.trim()) missing++
328
+ else if (words === unit.source || words === unit.markup) unchanged++
329
+ else translated++
309
330
  }
310
331
 
311
332
  status[locale] = {
@@ -313,6 +334,7 @@ export async function getTranslationStatus(siteRoot, options = {}) {
313
334
  translated,
314
335
  missing,
315
336
  ...(outdated ? { outdated } : {}),
337
+ ...(unchanged ? { unchanged } : {}),
316
338
  coverage: totalUnits > 0 ? Math.round((translated / totalUnits) * 100) : 100
317
339
  }
318
340
  }
@@ -677,6 +699,9 @@ export function formatTranslationStatus(status) {
677
699
  if (info.outdated > 0) {
678
700
  lines.push(` ${info.outdated} outdated: the old translation still shows, and its source has changed`)
679
701
  }
702
+ if (info.unchanged > 0) {
703
+ lines.push(` ${info.unchanged} the same as the source: what \`uniweb i18n init\` wrote, or words that stay the same in ${locale}`)
704
+ }
680
705
  }
681
706
  }
682
707
 
package/src/i18n/merge.js CHANGED
@@ -14,7 +14,7 @@
14
14
 
15
15
  import { computeHash } from './hash.js'
16
16
  import { loadFreeformTranslation } from './freeform.js'
17
- import { elementText, blockElements, translationContext, SITE_META_CONTEXT, imageNodes, TRANSLATED_IMAGE_ATTRS } from './extract.js'
17
+ import { elementText, blockElements, translationContext, pageMetaContext, SITE_META_CONTEXT, imageNodes, TRANSLATED_IMAGE_ATTRS } from './extract.js'
18
18
  import { visitDataBlockStrings } from './data-strings.js'
19
19
  import { inlineMarkdownToProseMirror } from '@uniweb/content-reader'
20
20
 
@@ -63,25 +63,27 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource, data
63
63
  // Deep clone to avoid mutating original
64
64
  const translated = JSON.parse(JSON.stringify(siteContent))
65
65
  translateSiteMeta(translated.config, translations, fallbackToSource)
66
+ // A page the site doesn't translate takes only a translation written for its place (`translationContext`).
67
+ const exclude = siteContent.config?.i18n?.exclude
66
68
 
67
69
  for (const page of translated.pages || []) {
68
70
  const pageRoute = page.route || '/'
69
71
 
70
72
  // Translate page metadata
71
- translatePageMeta(page, pageRoute, translations, fallbackToSource)
73
+ translatePageMeta(page, pageRoute, translations, fallbackToSource, exclude)
72
74
 
73
75
  // Translate section content
74
76
  for (const section of page.sections || []) {
75
- translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
77
+ translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel, exclude)
76
78
  }
77
79
  }
78
80
 
79
81
  // Translate 404 page (stored as top-level notFound)
80
82
  if (translated.notFound) {
81
83
  const pageRoute = translated.notFound.route || '/404'
82
- translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource)
84
+ translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource, exclude)
83
85
  for (const section of translated.notFound.sections || []) {
84
- translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
86
+ translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel, exclude)
85
87
  }
86
88
  }
87
89
 
@@ -113,12 +115,14 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
113
115
  // Deep clone to avoid mutating original
114
116
  const translated = JSON.parse(JSON.stringify(siteContent))
115
117
  translateSiteMeta(translated.config, translations, fallbackToSource)
118
+ // A page the site doesn't translate takes only a translation written for its place (`translationContext`).
119
+ const exclude = siteContent.config?.i18n?.exclude
116
120
 
117
121
  for (const page of translated.pages || []) {
118
122
  const pageRoute = page.route || '/'
119
123
 
120
124
  // Translate page metadata (always hash-based)
121
- translatePageMeta(page, pageRoute, translations, fallbackToSource)
125
+ translatePageMeta(page, pageRoute, translations, fallbackToSource, exclude)
122
126
 
123
127
  // Translate section content (with free-form check)
124
128
  for (const section of page.sections || []) {
@@ -126,7 +130,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
126
130
  fallbackToSource,
127
131
  locale,
128
132
  localesDir,
129
- dataModel
133
+ dataModel,
134
+ exclude
130
135
  })
131
136
  }
132
137
  }
@@ -134,13 +139,14 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
134
139
  // Translate 404 page (stored as top-level notFound)
135
140
  if (translated.notFound) {
136
141
  const pageRoute = translated.notFound.route || '/404'
137
- translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource)
142
+ translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource, exclude)
138
143
  for (const section of translated.notFound.sections || []) {
139
144
  await translateSectionAsync(section, translated.notFound, translations, {
140
145
  fallbackToSource,
141
146
  locale,
142
147
  localesDir,
143
- dataModel
148
+ dataModel,
149
+ exclude
144
150
  })
145
151
  }
146
152
  }
@@ -242,8 +248,8 @@ function translateSiteMeta(config, translations, fallbackToSource) {
242
248
  }
243
249
  }
244
250
 
245
- function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
246
- const context = { page: pageRoute, section: '_meta' }
251
+ function translatePageMeta(page, pageRoute, translations, fallbackToSource, exclude = null) {
252
+ const context = pageMetaContext(pageRoute, exclude)
247
253
  const translate = (value) =>
248
254
  toPlainText(lookupTranslation(value, context, translations, fallbackToSource))
249
255
 
@@ -287,8 +293,8 @@ function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
287
293
  /**
288
294
  * Translate a section's content (synchronous, hash-based only)
289
295
  */
290
- function translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel = null) {
291
- const context = translationContext(section, pageRoute)
296
+ function translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel = null, exclude = null) {
297
+ const context = translationContext(section, pageRoute, exclude)
292
298
 
293
299
  if (section.content?.type === 'doc') {
294
300
  translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
@@ -298,7 +304,7 @@ function translateSectionSync(section, pageRoute, translations, fallbackToSource
298
304
 
299
305
  // Recursively translate subsections
300
306
  for (const subsection of section.subsections || []) {
301
- translateSectionSync(subsection, pageRoute, translations, fallbackToSource, dataModel)
307
+ translateSectionSync(subsection, pageRoute, translations, fallbackToSource, dataModel, exclude)
302
308
  }
303
309
  }
304
310
 
@@ -310,9 +316,9 @@ function translateSectionSync(section, pageRoute, translations, fallbackToSource
310
316
  * 2. Fall back to hash-based translation (element-by-element)
311
317
  */
312
318
  async function translateSectionAsync(section, page, translations, options) {
313
- const { fallbackToSource, locale, localesDir, dataModel } = options
319
+ const { fallbackToSource, locale, localesDir, dataModel, exclude = null } = options
314
320
  const pageRoute = page.route || '/'
315
- const context = translationContext(section, pageRoute)
321
+ const context = translationContext(section, pageRoute, exclude)
316
322
 
317
323
  // Check for free-form translation first
318
324
  const freeform = await loadFreeformTranslation(section, page, locale, localesDir)
@@ -752,6 +758,12 @@ function lookupTranslation(source, context, translations, fallbackToSource) {
752
758
  return fallbackToSource ? source : source
753
759
  }
754
760
 
761
+ // ⭐ On a page the site doesn't translate, only an override naming this place (`translationContext`).
762
+ if (context?.placeOnly) {
763
+ const own = typeof translation === 'object' ? translation.overrides?.[context.key ?? `${context.page}:${context.section}`] : undefined
764
+ return own || source
765
+ }
766
+
755
767
  // Handle simple string translation
756
768
  if (typeof translation === 'string') {
757
769
  // Preserve leading/trailing whitespace from original
package/src/prerender.js CHANGED
@@ -839,17 +839,21 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
839
839
  }
840
840
  }
841
841
 
842
+ // ⭐ Replacer functions, here and for the icons below: in a replacement string `$$`, `$&`, `` $` ``
843
+ // and `$'` are patterns, and this is the site's own text. ⛔ Until 2026-11-11 a page saying `$$x$$`
844
+ // embedded `$x$`, which the browser's render then drew. The shell this replaces escapes every `<`
845
+ // too (`jsonForScript`), so the first `</script>` after it is its own.
842
846
  const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${jsonForScript(contentForJson)}</script>`
843
847
  if (result.includes('__SITE_CONTENT__')) {
844
848
  // Replace existing site content with updated version (includes expanded dynamic routes)
845
849
  result = result.replace(
846
850
  /<script[^>]*id="__SITE_CONTENT__"[^>]*>[\s\S]*?<\/script>/,
847
- contentScript
851
+ () => contentScript
848
852
  )
849
853
  } else {
850
854
  result = result.replace(
851
855
  '</head>',
852
- ` ${contentScript}\n </head>`
856
+ () => ` ${contentScript}\n </head>`
853
857
  )
854
858
  }
855
859
 
@@ -866,12 +870,12 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
866
870
  if (result.includes('__ICON_CACHE__')) {
867
871
  result = result.replace(
868
872
  /<script[^>]*id="__ICON_CACHE__"[^>]*>[\s\S]*?<\/script>/,
869
- iconScript
873
+ () => iconScript
870
874
  )
871
875
  } else {
872
876
  result = result.replace(
873
877
  '</head>',
874
- ` ${iconScript}\n </head>`
878
+ () => ` ${iconScript}\n </head>`
875
879
  )
876
880
  }
877
881
  }