@master/internal-site 0.1.3 → 0.2.1

package/dist/localization.d.mts

@@ -0,0 +1,69 @@
+/** Prose can vary by locale; publication identity and technical configuration stay with the source. */
+export declare function localizedMetadata(metadata: Record<string, any>, frontmatter: Record<string, any>, locale: string): Record<string, any>;
+export interface TranslationResource {
+  id: string;
+  source: string;
+  translations: Record<string, string | undefined>;
+  /** Source-only data or metadata whose changes require another translation review. */
+  dependencies?: Record<string, string>;
+  locales?: readonly string[];
+  draft?: boolean;
+  checkAnchors?: boolean;
+  requireMetadata?: boolean;
+}
+export interface TranslationReview {
+  sourceHash: string;
+  translationHash: string;
+}
+export interface TranslationReviews {
+  version: 1;
+  resources: Record<string, Record<string, TranslationReview>>;
+}
+export interface LocalizationOptions {
+  locales?: readonly string[];
+  defaultLocale?: string;
+}
+export interface TranslationDiagnostic {
+  id: string;
+  locale: string;
+  reason: 'missing' | 'unreviewed' | 'source-changed' | 'translation-changed' | 'anchors' | 'metadata';
+  message: string;
+}
+export declare const emptyReviews: () => TranslationReviews;
+/** Explicit review operation. Preparation and production builds never call this function. */
+export declare function reviewTranslation(resource: TranslationResource, locale: string): TranslationReview;
+export declare function auditTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, { locales, defaultLocale }?: LocalizationOptions): TranslationDiagnostic[];
+export declare function assertTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, options?: LocalizationOptions): void;
+/** Shared Astro build gate, also usable by a consumer's explicit audit command. */
+export declare function validateSiteTranslations({ validation, ...options }: LocalizationOptions & {
+  validation?: {
+    reviews: URL;
+    resources: URL;
+  };
+}): Promise<void>;
+export declare function readLocalizedDocument({ sourceFile, locale, defaultLocale, metadata }: {
+  sourceFile: string;
+  locale: string;
+  defaultLocale?: string;
+  metadata?: Record<string, any>;
+}): Promise<{
+  file: string;
+  content: string;
+  frontmatter: Record<string, any>;
+  metadata: Record<string, any>;
+}>;
+/** Filesystem inventory, with no page imports, component execution or generated source writes. */
+export declare function discoverDocumentResources({ contentRoot, locales, defaultLocale, exclude, siteRoot }: {
+  contentRoot: string;
+  siteRoot?: string;
+  exclude?: readonly string[];
+} & LocalizationOptions): Promise<TranslationResource[]>;
+/** Literal interface requests must exist even when a newly added control has no dictionary entry yet. */
+export declare function sharedInterfaceKeys(sourceRoot?: string): Promise<string[]>;
+/** Follow local prose/data modules without executing them or importing product compiler code. */
+export declare function collectSourceDependencies(files: readonly string[], { siteRoot }: {
+  siteRoot: string;
+}): Promise<Record<string, string>>;
+export declare function headingAnchors(source: string): string[];
+/** Pin the existing automatic English IDs before translation, without modifying fenced examples. */
+export declare function stabilizeHeadingAnchors(source: string): string;

package/dist/localization.mjs

@@ -0,0 +1 @@
+export { t as assertTranslations, n as auditTranslations, r as collectSourceDependencies, i as discoverDocumentResources, a as emptyReviews, o as headingAnchors, p as localizedMetadata, s as readLocalizedDocument, c as reviewTranslation, l as sharedInterfaceKeys, u as stabilizeHeadingAnchors, d as validateSiteTranslations } from "./localization-LfIbIysE.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@master/internal-site",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
   "description": "First-party Astro and Svelte website framework for Master sites.",
   "engines": {
@@ -27,6 +27,10 @@
     "./assets/*": "./src/public/*",
     "./astro/*": "./src/astro/*",
     "./build/*": "./src/scripts/*",
+    "./build/localization.ts": {
+      "types": "./dist/localization.d.mts",
+      "import": "./dist/localization.mjs"
+    },
     "./utils/cloudflare-image-loader.js": "./src/utils/cloudflare-image-loader.js",
     "./package.json": "./package.json",
     "./components/*": "./src/docs-shell/components/*",
@@ -236,7 +240,6 @@
     "./blog/*": "./src/blog/*",
     "./demo/*": "./src/demo/*",
     "./demo/style": "./src/demo/style.ts",
-    "./blog/article/language": "./src/blog/article/language.ts",
     "./blog/article/neighbors": "./src/blog/article/neighbors.ts",
     "./blog/article/title-parts": "./src/blog/article/title-parts.ts",
     "./home/home-lamp": "./src/home/home-lamp.ts",
@@ -305,14 +308,14 @@
   "peerDependencies": {
     "astro": "7.4.2",
     "svelte": "5.57.2",
-    "@master/css": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
-    "@master/css-astro": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
+    "@master/css": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
+    "@master/css-astro": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
     "vite": "8.3.5",
-    "@master/css-compiler": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
-    "@master/css-tooling": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
-    "@master/css-schema": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
-    "@master/css-preset": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1",
-    "@master/css-language-service": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1"
+    "@master/css-compiler": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
+    "@master/css-tooling": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
+    "@master/css-schema": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
+    "@master/css-preset": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0",
+    "@master/css-language-service": "0.0.0 || >=0.0.0-site.1793646900.gdf48b35846c1 <0.0.1 || ^2.0.0"
   },
   "dependencies": {
     "@astrojs/svelte": "^9.1.2",

package/src/astro/content-pages.ts

@@ -2,6 +2,7 @@ import { readdir, readFile, mkdir, writeFile, unlink } from 'node:fs/promises'
 import { join, relative, dirname } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { SiteConfig } from '../config'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
 
 export async function contentFiles(directory: string): Promise<string[]> {
   const files: string[] = []
@@ -22,6 +23,34 @@ export async function prepareContentPages(site: SiteConfig, root: string, conten
   const destination = join(root, '.astro/master-site/pages')
   const pages: Record<string, URL> = {}
   const wanted = new Set<string>()
+  const localizedDocuments: Record<string, Record<string, URL>> = {}
+  const localizedMetadata: Record<string, Record<string, Record<string, any>>> = {}
+  const availableLocales: Record<string, readonly string[]> = {}
+  for (const file of files) {
+    if (!file.endsWith('/content.mdx')) continue
+    const directory = dirname(file)
+    const route = relative(content, directory).replaceAll('\\', '/')
+    const pathname = '/' + route.split('/').filter(part => !/^\(.+\)$/.test(part)).join('/')
+    const key = `${contentPrefix}/${route ? route + '/' : ''}page.astro`
+    const section = route.split('/').find(part => !/^\(.+\)$/.test(part)) ?? 'home'
+    const locales = site.i18n.sectionLocales?.[section] ?? site.i18n.locales
+    const metadataSource = await readFile(join(directory, 'metadata.ts'), 'utf8').catch(() => '')
+    const source = parseFrontmatter(await readFile(file, 'utf8')).frontmatter
+    const draft = source.draft === true || /\bdraft\s*:\s*true\b/.test(metadataSource)
+    const documents: Record<string, URL> = {}
+    const metadata: Record<string, Record<string, any>> = {}
+    for (const locale of draft ? [] : locales) {
+      const variant = locale === site.i18n.defaultLocale ? file : join(directory, `content.${locale}.mdx`)
+      if (!files.has(variant)) continue
+      const { frontmatter } = parseFrontmatter(await readFile(variant, 'utf8'))
+      if (frontmatter.draft === true) continue
+      documents[locale] = pathToFileURL(variant)
+      metadata[locale] = frontmatter
+    }
+    localizedDocuments[pathname] = documents
+    localizedMetadata[pathname] = metadata
+    availableLocales[key] = Object.keys(documents)
+  }
   for (const file of files) {
     if (!file.endsWith('/content.mdx')) continue
     const directory = dirname(file)
@@ -54,16 +83,6 @@ export const generateMetadata = createPageMetadata(metadata, dictionaries)
   for (const stale of await contentFiles(destination).catch(() => [])) {
     if (stale.endsWith('/page.astro') && !wanted.has(stale)) await unlink(stale)
   }
-  const availableLocales: Record<string, readonly string[]> = {}
-  for (const file of files) {
-    if (!file.endsWith('/content.mdx')) continue
-    const directory = dirname(file)
-    const route = relative(content, directory).replaceAll('\\', '/')
-    const section = route.split('/').find(segment => !/^\(.+\)$/.test(segment)) ?? 'home'
-    if (!site.i18n.translatedOnly?.includes(section)) continue
-    availableLocales[`${contentPrefix}/${route ? route + '/' : ''}page.astro`] = site.i18n.locales.filter(locale =>
-      locale === site.i18n.defaultLocale || files.has(join(directory, `content.${locale}.mdx`)))
-  }
   // A translated archive exists only when at least one article is translated.
   for (const section of site.i18n.translatedOnly ?? []) {
     const key = `${contentPrefix}/${section}/page.astro`
@@ -71,5 +90,5 @@ export const generateMetadata = createPageMetadata(metadata, dictionaries)
     const published = Object.entries(availableLocales).filter(([page]) => page.startsWith(`${contentPrefix}/${section}/`))
     availableLocales[key] = site.i18n.locales.filter(locale => locale === site.i18n.defaultLocale || published.some(([, locales]) => locales.includes(locale)))
   }
-  return { pages, availableLocales }
+  return { pages, availableLocales, localizedDocuments, localizedMetadata }
 }

package/src/astro/index.ts

@@ -12,8 +12,10 @@ import { searchForWorkspaceRoot, transformWithOxc, type Plugin } from 'vite'
 import type { SiteConfig } from '../config'
 import sourceURL from './source-url'
 import { prepareContentPages } from './content-pages'
+import { validateSiteTranslations } from '../scripts/localization'
 import serverStyles from './server-styles'
 import svgMarkup from './svg-markup'
+import localizedMdx from './localized-mdx'
 import { compactStyleAssets } from './style-assets'
 import remarkSlugAndTOC from '../docs-shell/remark/slug-and-toc.js'
 import remarkMarkdownComponents from '../docs-shell/remark/markdown-components.js'
@@ -29,7 +31,8 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
   return {
     name: '@master/internal-site',
     hooks: {
-      'astro:config:setup': async ({ config, updateConfig, addRenderer, injectRoute }) => {
+      'astro:config:setup': async ({ config, command, updateConfig, addRenderer, injectRoute }) => {
+        if (command === 'build') await validateSiteTranslations(site.i18n)
         const root = fileURLToPath(config.root)
         const contentRelative = relative(root, fileURLToPath(site.content)).split(sep).join('/')
         if (contentRelative.startsWith('..')) throw new Error('Site content must be inside the Astro project root')
@@ -41,7 +44,8 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
           'virtual:master-site/config': `export default ${JSON.stringify(site)}`,
           'virtual:master-site/app': moduleImport(site.app),
           'virtual:master-site/highlight': moduleImport(site.highlighter ?? new URL('../docs-shell/utils/highlight-code-core.ts', import.meta.url)),
-          'virtual:master-site/translations': `export default import.meta.glob(${JSON.stringify(`${contentPrefix}/**/content.*.mdx`)})`,
+          'virtual:master-site/translations': `export default {${Object.entries(prepared.localizedDocuments).map(([pathname, documents]) => `${JSON.stringify(pathname)}: {${Object.entries(documents).map(([locale, url]) => `${JSON.stringify(locale)}: ${propagated(url)}`).join(',')}}`).join(',')}}`,
+          'virtual:master-site/localized-metadata': `export default ${JSON.stringify(prepared.localizedMetadata)}`,
         }
         const plugin: Plugin = {
           name: '@master/internal-site:modules',
@@ -75,10 +79,10 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
               clearTimeout(restart)
               restart = setTimeout(() => { void server.restart() }, 100)
             }
-            server.watcher.on('add', refresh).on('unlink', refresh)
+            server.watcher.on('add', refresh).on('unlink', refresh).on('change', refresh)
             server.httpServer?.once('close', () => {
               clearTimeout(restart)
-              server.watcher.off('add', refresh).off('unlink', refresh)
+              server.watcher.off('add', refresh).off('unlink', refresh).off('change', refresh)
             })
             // Serve package-owned assets without copying them into the consumer's source tree.
             // A consumer's public asset takes precedence at the same URL.
@@ -110,7 +114,7 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
           build: { format: 'file' },
           markdown: { processor: unified({ remarkPlugins: [remarkSlugAndTOC, remarkMarkdownComponents], gfm: true, smartypants: false }), syntaxHighlight: false },
           experimental: { svgOptimizer: svgoOptimizer(svgoConfig as Parameters<typeof svgoOptimizer>[0]) },
-          vite: { plugins: [plugin, sourceURL(), serverStyles([root, packageSource]), svgMarkup()], resolve: { dedupe: ['svelte'] }, server: { fs: { allow: [searchForWorkspaceRoot(root), packageSource] } } },
+          vite: { plugins: [plugin, localizedMdx(site.i18n), sourceURL(), serverStyles([root, packageSource]), svgMarkup()], resolve: { dedupe: ['svelte'] }, server: { fs: { allow: [searchForWorkspaceRoot(root), packageSource] } } },
           integrations: [svelte(), mdx(), masterCSS({ mode: 'progressive' })]
         })
       },

package/src/astro/localized-mdx.ts

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises'
+import { isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import type { Plugin } from 'vite'
+import { locales as supportedLocales, defaultLocale as sourceLocale } from '../docs-shell/common/locales.js'
+import { isSharedMdxSample } from '../scripts/mdx-sample'
+import { cleanId } from './module-id'
+
+/** Nested article MDX follows its importer; executable examples keep one source. */
+export default function localizedMdx({ locales = supportedLocales, defaultLocale = sourceLocale }: { locales?: readonly string[]; defaultLocale?: string } = {}): Plugin {
+  return {
+    name: '@master/internal-site:localized-mdx',
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      if (!importer || !cleanId(importer).endsWith('.mdx')) return
+      const language = cleanId(importer).match(/\.([a-z]{2})\.mdx$/)?.[1]
+      const locale = language && locales.includes(language) ? language : defaultLocale
+
+      // Let Vite resolve aliases and filesystem boundaries before selecting a sibling.
+      const resolved = await this.resolve(source, importer, { ...options, skipSelf: true })
+      if (!resolved || resolved.external) return
+      const id = cleanId(resolved.id)
+      if (!id.endsWith('.mdx') || id.startsWith('\0')) return
+      const suffix = resolved.id.slice(id.length) || source.slice(cleanId(source).length)
+      const file = id.startsWith('file:') ? fileURLToPath(id) : id.startsWith('/@fs/') ? id.slice(5) : id
+      if (!isAbsolute(file)) return
+      const original = file.replace(/\.([a-z]{2})\.mdx$/, (match, language: string) => locales.includes(language) ? '.mdx' : match)
+      this.addWatchFile(original)
+      const originalSource = await readFile(original, 'utf8')
+      const originalMetadata = parseFrontmatter(originalSource).frontmatter
+      if (originalMetadata.draft === true || originalMetadata.disabled === true) throw new Error(`Unpublished source MDX include: ${original}`)
+      if (locale === defaultLocale || !originalSource.trim() || isSharedMdxSample(original, originalSource)) return { ...resolved, id: original + suffix }
+
+      const translated = original.replace(/\.mdx$/, `.${locale}.mdx`)
+      this.addWatchFile(translated)
+      let translatedSource: string
+      try { translatedSource = await readFile(translated, 'utf8') }
+      catch (cause) { throw new Error(`Missing translated MDX include: ${translated}`, { cause }) }
+      const metadata = parseFrontmatter(translatedSource).frontmatter
+      if (metadata.draft === true || metadata.disabled === true) throw new Error(`Unpublished translated MDX include: ${translated}`)
+      return { ...resolved, id: translated + suffix }
+    }
+  }
+}

package/src/astro/routes.template.ts

@@ -3,6 +3,7 @@ import { mergeAssets, type PageAssets, type PropagatedModule } from '@master/int
 import { createStaticPaths, directoriesOf, localesOf, sectionOf, type ParamsModule, type RouteProps, type Section } from '@master/internal-site/astro/route-paths'
 import type { Metadata } from '@master/internal-site/types/Metadata'
 import type { Props } from '@master/internal-site/types/Props'
+import { loadLocalizedContent } from '@master/internal-site/factories/create-page'
 
 export { localizePathname, sectionOf } from '@master/internal-site/astro/route-paths'
 export type { RouteProps, Section } from '@master/internal-site/astro/route-paths'
@@ -77,6 +78,8 @@ export async function loadRoute({ file, locale, params }: RouteProps): Promise<L
   const metadata = (module.generateMetadata ? await module.generateMetadata(props) : module.metadata) ?? {}
   const layers = [module.default]
   const propagated: PropagatedModule<unknown>[] = [page.propagated]
+  const localized = await loadLocalizedContent(locale, metadata)
+  if (localized) { await localized.getMod(); propagated.push(localized) }
   const directories = directoriesOf(file, contentRoot)
   for (let depth = directories.length; depth > 0; depth--) {
     const layoutFile = `${contentRoot}${directories.slice(0, depth).join('/')}/layout.astro`

package/src/astro/site-context.ts

@@ -1,5 +1,6 @@
 import config from 'virtual:master-site/config'
 import { createSite, type Site, type SiteContextValue } from '../docs-shell/site'
+import sharedTranslations from '../docs-shell/common/translations'
 
 export function localeOfPathname(pathname: string): string {
   const segment = pathname.split('/')[1]
@@ -18,10 +19,17 @@ export function canonicalPathname(pathname: string) {
 export function siteContextOf(url: URL): SiteContextValue {
   const pathname = canonicalPathname(url.pathname)
   const locale = localeOfPathname(pathname)
-  const { translations, ...i18n } = config.i18n
-  return { locale, pathname, translations: translations[locale] ?? {}, i18n }
+  const { translations, defaultLocale, locales, hreflangOfLocale, nameOfLocale, localizablePathnameRoots, localizableOrigins } = config.i18n
+  // Only public navigation settings belong in the serialized island context.
+  const i18n = { defaultLocale, locales, hreflangOfLocale, nameOfLocale, localizablePathnameRoots, localizableOrigins }
+  return { locale, pathname, translations: { ...sharedTranslations[locale], ...translations[locale] }, i18n }
 }
 
 export function siteOf(astro: { url: URL }): Site {
   return createSite(siteContextOf(astro.url))
 }
+
+/** Request-local authored figure captions and other article-specific copy. */
+export function documentCopyOf(astro: { locals: object }): Record<string, any> {
+  return (astro.locals as Record<string, any>).masterDocument ?? {}
+}

package/src/benchmarks/BenchmarkChart.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context'
+import { localizeBenchmarkChart } from './localization'
 import '@master/internal-site/styles/system/table.css'
 import ExpandContent from '@master/internal-site/components/ExpandContent.svelte'
 import BenchmarkBars from '@master/internal-site/benchmarks/BenchmarkBars.astro'
@@ -11,7 +13,8 @@ interface Props {
 }
 
 /** Renders an authored chart model; `utils/benchmark-content` exports the same model as Markdown. */
-const { chart } = Astro.props
+const { t } = siteOf(Astro)
+const chart = localizeBenchmarkChart(Astro.props.chart, t)
 ---
 
 {chart.kind === 'bars' && <BenchmarkBars items={chart.items} max={chart.max} unit={chart.unit} valueFormatter={chart.valueFormatter} />}

package/src/benchmarks/BenchmarkMetricTable.astro

@@ -16,7 +16,7 @@ const hasDetails = metrics.some((metric) => metric.detail)
 ---
 
 {/* Preserve keyboard access to wide metric tables. */}
-<div class="ui-table" role="region" aria-label={label} tabindex="0">
+<div class="ui-table" role="region" aria-label={t(label)} tabindex="0">
   <table>
     <thead>
       <tr>

package/src/benchmarks/BenchmarkStackedBars.astro

@@ -35,11 +35,11 @@ const labelPrefix = uniqueId(Astro, 'benchmark-stacked-bars')
         <div class="ui-bar" data-variant="stacked" role="img" aria-labelledby={`${labelId} ${valueId}`}>
           {item.segments.map((segment, segmentIndex) => <i
             data-tone={benchmarkTone(segment.color ?? benchmarkColors[segmentIndex % benchmarkColors.length])}
-            title={`${segment.label}: ${segment.valueLabel ?? formatMetricValue(segment.value, unit)}`}
+            title={`${t(segment.label)}: ${segment.valueLabel ?? formatMetricValue(segment.value, unit)}`}
             style={{ width: `${clampPercent(segment.value, max ?? total)}%` }} />)}
         </div>
         <output id={valueId}>{totalLabel}</output>
-        <ul class="ui-legend" role="group" aria-label={`${item.label} breakdown`}>
+        <ul class="ui-legend" role="group" aria-label={t('{label} breakdown').replace('{label}', t(item.label))}>
           {item.segments.map((segment, segmentIndex) => {
             const valueLabel = segment.valueLabel ?? (valueFormatter ? valueFormatter(segment.value) : formatMetricValue(segment.value, unit))
             return <li>

package/src/benchmarks/BenchmarkStatus.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/system/specimens.css'
 import type { BenchmarkTone } from '@master/internal-site/benchmarks/types.ts'
 import { benchmarkStatusTones } from '@master/internal-site/benchmarks/utils.ts'
@@ -13,4 +15,4 @@ const names: Record<Exclude<BenchmarkTone, 'neutral'>, string> = { good: 'Good',
 const { tone } = Astro.props
 ---
 
-{tone && tone !== 'neutral' && <span class="ui-badge" data-tone={benchmarkStatusTones[tone]} data-variant="dot" data-size="sm">{names[tone]}</span>}
+{tone && tone !== 'neutral' && <span class="ui-badge" data-tone={benchmarkStatusTones[tone]} data-variant="dot" data-size="sm">{t(names[tone])}</span>}

package/src/benchmarks/localization.ts

@@ -0,0 +1,22 @@
+/** Reader copy only: numeric values, technical units, fixture rows and formatters stay canonical. */
+const proseFields = new Set(['label', 'labelNote', 'title', 'detail', 'description', 'caption', 'headers'])
+
+function mapCopy<T>(model: T, translate: (text: string) => string): T {
+  const visit = (value: unknown, field: string): unknown => {
+    if (typeof value === 'string') return proseFields.has(field) && value.trim() ? translate(value) : value
+    if (Array.isArray(value)) return value.map(item => visit(item, field))
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, visit(item, key)]))
+    return value
+  }
+  return visit(model, '') as T
+}
+
+export function benchmarkCopyKeys(model: unknown): string[] {
+  const keys = new Set<string>()
+  mapCopy(model, text => { keys.add(text); return text })
+  return [...keys].sort()
+}
+
+export function localizeBenchmarkChart<T>(model: T, translate: (text: string) => string): T {
+  return mapCopy(model, translate)
+}

package/src/blog/article/BlogArticleEnd.astro

@@ -1,11 +1,10 @@
 ---
-import dayjs from 'dayjs'
+import { formatDate } from '../../docs-shell/common/locales'
 import IconArrowLeft from '@tabler/icons-svelte-runes/icons/arrow-left'
 import IconArrowRight from '@tabler/icons-svelte-runes/icons/arrow-right'
 import Link from '@master/internal-site/components/Link.svelte'
 import { siteOf } from '@master/internal-site/astro/site-context'
 import TitleLines from './title-lines.astro'
-import { sourceLanguageOf } from './language'
 import type { BlogArticleNeighbor } from './neighbors'
 
 interface Props {
@@ -20,14 +19,12 @@ interface Props {
  * article as quiet links.
  */
 const { newer, older, showCategory = true } = Astro.props
-const { t: $, i18n, locale } = siteOf(Astro)
-const tw = locale === 'tw'
-const languageOf = (text?: string) => sourceLanguageOf(text, { ...i18n, locale })
+const { t: $, locale } = siteOf(Astro)
 // Readers who finish a post usually continue backwards through the archive; the newest post leads with the one before it.
 const lead = older ?? newer
 const other = lead === older ? newer : undefined
 // Written out in full, as on the post's own header and on the index's featured sheet.
-const date = (value: string) => dayjs(value).format(tw ? 'YYYY 年 M 月 D 日' : 'MMMM D, YYYY')
+const date = (value: string) => formatDate(value, locale)
 ---
 
 <nav class="blog-article-end blog-rails blog-rails-rule" aria-labelledby="blog-article-end-title">
@@ -38,8 +35,8 @@ const date = (value: string) => dayjs(value).format(tw ? 'YYYY 年 M 月 D 日'
         {showCategory && lead.category && <span>{$(lead.category)}</span>}
         {lead.date && <time datetime={lead.date}>{date(lead.date)}</time>}
       </span>
-      <span class="blog-article-next-title" lang={languageOf(lead.title)}><TitleLines title={$(lead.title)} class="blog-article-next-title-line" /><IconArrowRight class="blog-article-next-arrow" aria-hidden="true" size={22} stroke={1.25} /></span>
-      {lead.description && <span class="blog-article-next-description" lang={languageOf(lead.description)}>{$(lead.description)}</span>}
+      <span class="blog-article-next-title"><TitleLines title={$(lead.title)} class="blog-article-next-title-line" /><IconArrowRight class="blog-article-next-arrow" aria-hidden="true" size={22} stroke={1.25} /></span>
+      {lead.description && <span class="blog-article-next-description">{$(lead.description)}</span>}
     </Link>
   )}
   <div class="blog-article-end-links">
@@ -47,7 +44,7 @@ const date = (value: string) => dayjs(value).format(tw ? 'YYYY 年 M 月 D 日'
     {other && (
       <Link class="blog-article-end-link" href={other.pathname}>
         <span class="blog-article-end-link-label">{$('Newer')}</span>
-        <span class="blog-article-end-link-title" lang={languageOf(other.title)}>{$(other.title)}</span>
+        <span class="blog-article-end-link-title">{$(other.title)}</span>
         <IconArrowRight aria-hidden="true" size={14} stroke={1.75} />
       </Link>
     )}

package/src/blog/article/BlogArticleMasthead.astro

@@ -1,11 +1,10 @@
 ---
-import dayjs from 'dayjs'
+import { formatDate } from '../../docs-shell/common/locales'
 import authors from '@master/internal-site/data/authors'
 import Image from '@master/internal-site/components/Image.svelte'
 import Link from '@master/internal-site/components/Link.svelte'
 import { siteOf } from '@master/internal-site/astro/site-context'
 import TitleLines from './title-lines.astro'
-import { sourceLanguageOf } from './language'
 import type { DefinedMetadata } from '@master/internal-site/types/Metadata'
 
 interface Props {
@@ -18,11 +17,9 @@ interface Props {
  * falls on it from above and to the left.
  */
 const { metadata } = Astro.props
-const { t: $, i18n, locale } = siteOf(Astro)
-const tw = locale === 'tw'
+const { t: $, locale } = siteOf(Astro)
 const source: string = metadata.title?.absolute || metadata.title
 const title: string = $(source)
-const languageOf = (text?: string) => sourceLanguageOf(text, { ...i18n, locale })
 const people = (metadata.authors ?? [])
   .map(({ name }: { name: string }) => authors.find((author) => author.name === name))
   .filter(Boolean) as typeof authors
@@ -32,11 +29,11 @@ const people = (metadata.authors ?? [])
   {(metadata.category || metadata.date) && (
     <p class="blog-article-meta">
       {metadata.category && <span>{$(metadata.category)}</span>}
-      {metadata.date && <time datetime={metadata.date}>{dayjs(metadata.date).format(tw ? 'YYYY 年 M 月 D 日' : 'MMMM D, YYYY')}</time>}
+      {metadata.date && <time datetime={metadata.date}>{formatDate(metadata.date, locale)}</time>}
     </p>
   )}
-  <h1 class="blog-article-title blog-stone-text" lang={languageOf(source)}><TitleLines title={title} class="blog-article-title-line" /></h1>
-  {metadata.description && <p class="blog-article-dek" lang={languageOf(metadata.description)}>{$(metadata.description)}</p>}
+  <h1 class="blog-article-title blog-stone-text"><TitleLines title={title} class="blog-article-title-line" /></h1>
+  {metadata.description && <p class="blog-article-dek">{$(metadata.description)}</p>}
   {people.length > 0 && (
     <div class="blog-article-byline">
       <span class="blog-article-byline-label">{$('Written by')}</span>

package/src/config.ts

@@ -28,10 +28,13 @@ export interface SiteI18nConfig {
   hreflangOfLocale: Record<string, string>
   nameOfLocale: Record<string, string>
   localizablePathnameRoots: string[]
+  localizableOrigins?: Record<string, readonly string[]>
   translations: Record<string, Record<string, string>>
   sectionLocales?: Record<string, readonly string[]>
   /** These sections emit translated URLs only when translated MDX exists. */
   translatedOnly?: readonly string[]
+  /** Build-only resource loader and version-controlled explicit translation reviews. */
+  validation?: { reviews: URL; resources: URL }
 }
 
 export interface DocumentConfig {

package/src/css/foundation-data/specimen-content.ts

@@ -4,7 +4,7 @@ import { configuredMarkupMarkdown } from '@master/internal-site/css/configured-e
 export function specimenFactsMarkdown(namespace: string, keys?: string[]) {
   return specimenTokens(namespace, keys).map(token => `- \`--${token.name}\`: ${token.values.map(value => `\`${value.value}\` (${value.path.join(' → ')})`).join('; ')}${tokenAdvice(namespace, token.key) ? ` — ${tokenAdvice(namespace, token.key)}` : ''}`).join('\n')
 }
-export function selectedSpecimensMarkdown(namespace: string, keys: string[]) {
+export function selectedSpecimensMarkdown(namespace: string, keys: string[], t: (text: string) => string = text => text) {
   const scene = foundationScene(namespace, keys)
-  return `${scene.caption}\n\n${specimenFactsMarkdown(namespace, keys)}${scene.html && namespace !== 'color' ? `\n\n${configuredMarkupMarkdown(scene.css ?? '', scene.html)}` : ''}`
+  return `${t(scene.caption ?? '')}\n\n${specimenFactsMarkdown(namespace, keys)}${scene.html && namespace !== 'color' ? `\n\n${configuredMarkupMarkdown(scene.css ?? '', scene.html)}` : ''}`
 }