@uniweb/build 1.21.0 → 1.23.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.21.0",
3
+ "version": "1.23.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/content-writer": "~1.3.1",
62
- "@uniweb/semantic-parser": "~1.13.3",
63
- "@uniweb/schemas": "~1.7.1",
64
- "@uniweb/theming": "~1.3.2",
65
- "@uniweb/projections": "~1.2.17"
60
+ "@uniweb/schemas": "~1.7.2",
61
+ "@uniweb/content-writer": "~1.3.2",
62
+ "@uniweb/projections": "~1.2.17",
63
+ "@uniweb/content-reader": "~1.5.10",
64
+ "@uniweb/semantic-parser": "~1.13.4",
65
+ "@uniweb/theming": "~1.3.2"
66
66
  },
67
67
  "optionalDependencies": {
68
- "@uniweb/runtime": "~1.6.0"
68
+ "@uniweb/runtime": "~1.6.2"
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.6.0"
77
+ "@uniweb/runtime": "~1.6.2",
78
+ "@uniweb/core": "~1.6.12"
79
79
  },
80
80
  "peerDependenciesMeta": {
81
81
  "vite": {
@@ -25,7 +25,8 @@
25
25
  *
26
26
  * - a file that is not a map, or a `label`/`description` that is not text;
27
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.
28
+ * - a `keys_from` that names no mapping, or an `@/x` that isn't one of the foundation's;
29
+ * - a reverse `follow` line's `model` that names no type, or an `@/x` the foundation doesn't define.
29
30
  *
30
31
  * Mappings are editor-time only: they ride in `schema.json` as `_mappings` and never reach a page.
31
32
  *
@@ -136,6 +137,36 @@ export function mappingProblems(decl, { types, names }) {
136
137
  found.push(`\`keys_from\` is \`${decl.keys_from}\`, which is not one of the foundation's mappings (src/${MAPPINGS_DIR}/).`)
137
138
  }
138
139
  }
140
+ found.push(...followProblems(decl.follow, types))
141
+ return found
142
+ }
143
+
144
+ /**
145
+ * `follow` — a list of one-entry maps, `{ alias: { field, from? } }` forward, or
146
+ * `{ alias: { model, field, names? } }` reverse. Only a reverse line's `model` is a name (a type);
147
+ * the rest is local and the backend's to judge, as is a `follow` shaped any other way.
148
+ */
149
+ export function followModels(follow) {
150
+ if (!Array.isArray(follow)) return []
151
+ const out = []
152
+ for (const [i, line] of follow.entries()) {
153
+ if (!isMap(line)) continue
154
+ for (const [alias, spec] of Object.entries(line)) {
155
+ if (isMap(spec) && 'model' in spec) out.push({ at: `follow[${i}].${alias}.model`, spec })
156
+ }
157
+ }
158
+ return out
159
+ }
160
+
161
+ function followProblems(follow, types) {
162
+ const found = []
163
+ for (const { at, spec } of followModels(follow)) {
164
+ const problem = refProblem(at, spec.model, 'type')
165
+ if (problem) found.push(problem)
166
+ else if (spec.model.startsWith('@/') && !types.has(spec.model)) {
167
+ found.push(`\`${at}\` is \`${spec.model}\`, which is not one of the foundation's types (src/schemas/).`)
168
+ }
169
+ }
139
170
  return found
140
171
  }
141
172
 
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
  }
@@ -21,11 +21,6 @@
21
21
 
22
22
  import { visitModelStrings } from './model-fields.js'
23
23
 
24
- /** Types that are never translatable regardless of schema. */
25
- export const NON_TRANSLATABLE_TYPES = new Set([
26
- 'number', 'boolean', 'date', 'datetime', 'url', 'email', 'image'
27
- ])
28
-
29
24
  /** Field names skipped by the heuristic extractor (structural, not human-readable). */
30
25
  export const HEURISTIC_SKIP_FIELDS = new Set([
31
26
  'slug', 'id', 'type', 'status', 'href', 'url', 'src', 'icon',
@@ -26,8 +26,8 @@ export function extractTranslatableContent(siteContent, { dataModel = null } = {
26
26
  // ⭐ `i18n.exclude` — branches the site doesn't translate, such as a mounted repo's docs it shows in
27
27
  // their own language: their pages give no strings, so `init`, `status` and the rest, which read the
28
28
  // manifest, leave them alone. Routes as `agents.exclude` takes them (`isInExcludedBranch`). Their
29
- // pages show the source in every language, but for a string the site translates elsewhere, since a
30
- // translation is the text's wherever it appears.
29
+ // pages show the source in every language: only a translation written for one of their places
30
+ // applies there (`translationContext`).
31
31
  const exclude = siteContent.config?.i18n?.exclude
32
32
 
33
33
  // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
@@ -156,12 +156,34 @@ function extractFromPageMeta(page, pageRoute, units) {
156
156
  * `1-hero.md`) — so an override moved to another section when files were renumbered, and a clone,
157
157
  * whose files are not numbered, could not key it at all.
158
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
+ *
159
168
  * @param {Object} section - a section with `stableId` (and the build `id` as a fallback)
160
169
  * @param {string} pageRoute - the route of the page (or layout area) it is on
161
- * @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`
162
184
  */
163
- export function translationContext(section, pageRoute) {
164
- return { page: pageRoute, section: section?.stableId || section?.id || 'unknown' }
185
+ export function pageMetaContext(pageRoute, exclude = null) {
186
+ return translationContext({ stableId: '_meta' }, pageRoute, exclude)
165
187
  }
166
188
 
167
189
  /**
package/src/i18n/index.js CHANGED
@@ -407,12 +407,15 @@ function declaredLanguages(config, defaultLocale, locales) {
407
407
  * @param {string} [options.outputDir] - the built site, `<siteRoot>/dist` by default
408
408
  * @param {boolean} [options.projections=false] - write each language's projections. The bundle
409
409
  * lane's: a static host serves them. The link lane builds for a host, which derives its own.
410
+ * @param {boolean} [options.records=true] - translate each language's compiled records
411
+ * (`dist/<locale>/data/`). The bundle lane's: a static host serves them. The link lane compiles
412
+ * none — a push sends each record, in every language, to a host's records service.
410
413
  * @returns {Promise<{ content: Object, records: Object, projections: Object }>} what each step
411
414
  * wrote, by language — `projections[locale]` the files (`projectionFiles`), each `fileName`
412
415
  * from `outputDir`
413
416
  */
414
417
  export async function buildLocalizedSite(siteRoot, options = {}) {
415
- const { localesDir = DEFAULTS.localesDir, outputDir = join(siteRoot, 'dist'), projections = false } = options
418
+ const { localesDir = DEFAULTS.localesDir, outputDir = join(siteRoot, 'dist'), projections = false, records: withRecords = true } = options
416
419
 
417
420
  // The default language is the root tree, never a subdirectory — by the default the content step
418
421
  // reads (`buildLocalizedContent`), so the records step writes no `dist/<default>/data/` either.
@@ -422,12 +425,14 @@ export async function buildLocalizedSite(siteRoot, options = {}) {
422
425
 
423
426
  // Records first: a language's projections list its record pages, and translating them reads
424
427
  // the site's own files alone — never a translated page.
425
- const records = await buildLocalizedRecords(siteRoot, {
426
- locales,
427
- outputDir,
428
- recordLocalesDir: join(siteRoot, localesDir, RECORD_LOCALES_DIR),
429
- localesDir: join(siteRoot, localesDir)
430
- })
428
+ const records = withRecords
429
+ ? await buildLocalizedRecords(siteRoot, {
430
+ locales,
431
+ outputDir,
432
+ recordLocalesDir: join(siteRoot, localesDir, RECORD_LOCALES_DIR),
433
+ localesDir: join(siteRoot, localesDir)
434
+ })
435
+ : {}
431
436
  const content = await buildLocalizedContent(siteRoot, { localesDir, locales, outputDir, fallbackToSource: true })
432
437
 
433
438
  const written = {}
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