@master/internal-site 0.1.2 → 0.2.0

package/dist/localization-LfIbIysE.mjs

@@ -0,0 +1,356 @@
+import { parseFrontmatter } from "@astrojs/markdown-remark";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { mdxjsEsm } from "micromark-extension-mdxjs-esm";
+import { mdxjsEsmFromMarkdown } from "mdast-util-mdxjs-esm";
+import { mdxJsx } from "micromark-extension-mdx-jsx";
+import { mdxJsxFromMarkdown } from "mdast-util-mdx-jsx";
+import * as acorn from "acorn";
+import Slugger from "github-slugger";
+// src/docs-shell/utils/resolve-heading.js
+function resolveHeading(title, id) {
+	const explicit = typeof title === "string" && title.match(/\s+\{#([\w-]+)\}$/);
+	if (explicit) {
+		title = title.slice(0, explicit.index);
+		id = explicit[1];
+	}
+	const words = title?.split?.(" ");
+	if (words?.pop() === "[sr-only]") return {
+		title: words.join(" "),
+		id: id?.replace("-sr-only", "")?.replace("-[sr-only]", ""),
+		className: "sr-only"
+	};
+	return {
+		title,
+		id
+	};
+}
+/** Section counters stay stable when a detail heading is inserted between them. */
+function createHeadingResolver() {
+	const sections = new Slugger();
+	const details = new Slugger();
+	const assigned = /* @__PURE__ */ new Set();
+	return (title, depth) => {
+		const explicit = /\s+\{#[\w-]+\}$/.test(title);
+		let heading;
+		if (explicit) heading = resolveHeading(title);
+		else {
+			const slugs = depth === 2 || depth === 3 ? sections : details;
+			do
+				heading = resolveHeading(title, slugs.slug(title));
+			while (heading.id && assigned.has(heading.id));
+		}
+		if (heading.id) assigned.add(heading.id);
+		return {
+			...heading,
+			explicit
+		};
+	};
+}
+// src/docs-shell/common/locales.js
+/** URL prefixes stay stable; document language tags use standard BCP 47 values. */
+const locales = [
+	"en",
+	"tw",
+	"ja",
+	"ko",
+	"cn"
+];
+// src/docs-shell/utils/localized-metadata.ts
+/** Prose can vary by locale; publication identity and technical configuration stay with the source. */
+function localizedMetadata(metadata, frontmatter, locale) {
+	const localized = {
+		...metadata,
+		locale
+	};
+	for (const key of ["description", "subtitle"]) if (typeof frontmatter[key] === "string") localized[key] = frontmatter[key];
+	if (typeof frontmatter.title === "string") localized.title = metadata.title && typeof metadata.title === "object" ? {
+		...metadata.title,
+		..."absolute" in metadata.title ? { absolute: frontmatter.title } : { default: frontmatter.title }
+	} : frontmatter.title;
+	if (metadata.cover && typeof frontmatter.cover?.alt === "string") localized.cover = {
+		...metadata.cover,
+		alt: frontmatter.cover.alt
+	};
+	for (const channel of ["openGraph", "twitter"]) {
+		const authored = frontmatter[channel];
+		if (metadata[channel] || authored) {
+			const prose = Object.fromEntries(["title", "description"].flatMap((key) => {
+				const text = authored?.[key] ?? (locale !== "en" ? frontmatter[key] : void 0);
+				return typeof text === "string" ? [[key, text]] : [];
+			}));
+			localized[channel] = {
+				...metadata[channel],
+				...prose
+			};
+		}
+	}
+	return localized;
+}
+// src/scripts/mdx-sample.ts
+/** Only prose-free companion examples share one source across editions. */
+function isSharedMdxSample(file, source) {
+	if (["content.mdx", "contract.mdx"].includes(basename(file))) return false;
+	const { content, frontmatter } = parseFrontmatter(source);
+	if (Object.keys(frontmatter).length) return false;
+	const nodes = fromMarkdown(content).children;
+	return nodes.length > 0 && nodes.every((node) => node.type === "code");
+}
+// src/scripts/localization.ts
+const emptyReviews = () => ({
+	version: 1,
+	resources: {}
+});
+const hash = (value) => createHash("sha256").update(value.replaceAll("\r\n", "\n")).digest("hex");
+const sourceHash = (resource) => hash(JSON.stringify([resource.source, Object.entries(resource.dependencies ?? {}).sort(([a], [b]) => a.localeCompare(b))]));
+/** Explicit review operation. Preparation and production builds never call this function. */
+function reviewTranslation(resource, locale) {
+	const translation = resource.translations[locale];
+	if (!translation?.trim()) throw new Error(`Missing translation: ${resource.id} (${locale})`);
+	return {
+		sourceHash: sourceHash(resource),
+		translationHash: hash(translation)
+	};
+}
+function auditTranslations(resources, reviews, { locales: locales$1 = locales, defaultLocale = "en" } = {}) {
+	if (reviews.version !== 1 || !reviews.resources) throw new Error("Unsupported translation review index; expected version 1");
+	const diagnostics = [];
+	const ids = /* @__PURE__ */ new Set();
+	for (const resource of resources) {
+		if (ids.has(resource.id)) throw new Error(`Duplicate translation resource: ${resource.id}`);
+		ids.add(resource.id);
+		if (resource.draft) continue;
+		for (const locale of resource.locales ?? locales$1) {
+			if (locale === defaultLocale) continue;
+			const report = (reason, message) => diagnostics.push({
+				id: resource.id,
+				locale,
+				reason,
+				message
+			});
+			const translation = resource.translations[locale];
+			if (!translation?.trim()) {
+				report("missing", "Translation is missing");
+				continue;
+			}
+			if (parseFrontmatter(translation).frontmatter.draft === true) {
+				report("missing", "Translation is a draft and is not available for publication");
+				continue;
+			}
+			const review = reviews.resources[resource.id]?.[locale];
+			if (!review) report("unreviewed", "Translation has not been reviewed");
+			else {
+				if (review.sourceHash !== sourceHash(resource)) report("source-changed", "English source changed after translation review");
+				if (review.translationHash !== hash(translation)) report("translation-changed", "Translation changed after review");
+			}
+			if (resource.checkAnchors) {
+				const expected = headingAnchors(resource.source);
+				const actual = headingAnchors(translation);
+				if (new Set(actual).size !== actual.length || JSON.stringify(expected) !== JSON.stringify(actual)) report("anchors", "Translated heading IDs must preserve source IDs and order");
+			}
+			if (resource.requireMetadata) {
+				const { frontmatter } = parseFrontmatter(translation);
+				if (typeof frontmatter.title !== "string" || !frontmatter.title.trim() || typeof frontmatter.description !== "string" || !frontmatter.description.trim()) report("metadata", "Localized MDX requires title and description frontmatter");
+			}
+		}
+	}
+	return diagnostics;
+}
+function assertTranslations(resources, reviews, options = {}) {
+	const diagnostics = auditTranslations(resources, reviews, options);
+	if (diagnostics.length) throw new Error(`Translation completeness check failed (${diagnostics.length}):\n${diagnostics.map((issue) => `${issue.id} [${issue.locale}] ${issue.reason}: ${issue.message}`).join("\n")}`);
+}
+/** Shared Astro build gate, also usable by a consumer's explicit audit command. */
+async function validateSiteTranslations({ validation, ...options }) {
+	const locales$2 = options.locales ?? locales;
+	if (!validation) {
+		if (locales$2.some((locale) => locale !== (options.defaultLocale ?? "en"))) throw new Error("Multilingual production builds require i18n.validation resources and reviews");
+		return;
+	}
+	const [{ default: load }, raw] = await Promise.all([import(validation.resources.href), readFile(validation.reviews, "utf8")]);
+	const resources = typeof load === "function" ? await load() : load;
+	if (!Array.isArray(resources) || resources.length === 0) throw new Error("Translation resource loader must return a nonempty resource inventory");
+	assertTranslations(resources, JSON.parse(raw), options);
+}
+async function readLocalizedDocument({ sourceFile, locale, defaultLocale = "en", metadata = {} }) {
+	const original = sourceFile.replace(/\.([a-z]{2})\.mdx$/, ".mdx");
+	const file = locale === defaultLocale ? original : original.replace(/\.mdx$/, `.${locale}.mdx`);
+	let source;
+	try {
+		source = await readFile(file, "utf8");
+	} catch (cause) {
+		throw new Error(`Missing localized document: ${file} (${locale})`, { cause });
+	}
+	const { content, frontmatter } = parseFrontmatter(source);
+	return {
+		file,
+		content,
+		frontmatter,
+		metadata: localizedMetadata(metadata, frontmatter, locale)
+	};
+}
+async function filesOf(directory) {
+	const files = [];
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		const file = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name !== "drafts") files.push(...await filesOf(file));
+		} else files.push(file);
+	}
+	return files.sort();
+}
+/** Filesystem inventory, with no page imports, component execution or generated source writes. */
+async function discoverDocumentResources({ contentRoot, locales: locales$3 = locales, defaultLocale = "en", exclude = [], siteRoot = dirname(contentRoot) }) {
+	const files = new Set(await filesOf(contentRoot));
+	const resources = [];
+	for (const file of files) {
+		if (!file.endsWith(".mdx") || /\.[a-z]{2}\.mdx$/.test(file)) continue;
+		const source = await readFile(file, "utf8");
+		const id = relative(contentRoot, file).replaceAll("\\", "/");
+		if (!source.trim() || exclude.includes(id)) continue;
+		if (isSharedMdxSample(file, source)) continue;
+		const metadata = join(dirname(file), "metadata.ts");
+		const sourceMetadata = files.has(metadata) ? await readFile(metadata, "utf8") : void 0;
+		const dependencies = await collectSourceDependencies([file, ...sourceMetadata ? [metadata] : []], { siteRoot });
+		delete dependencies[relative(siteRoot, file).replaceAll("\\", "/")];
+		const translations = {};
+		for (const locale of locales$3) {
+			if (locale === defaultLocale) continue;
+			const translatedFile = file.replace(/\.mdx$/, `.${locale}.mdx`);
+			if (files.has(translatedFile)) translations[locale] = await readFile(translatedFile, "utf8");
+		}
+		resources.push({
+			id,
+			source,
+			translations,
+			dependencies,
+			checkAnchors: true,
+			requireMetadata: basename(file) === "content.mdx",
+			draft: parseFrontmatter(source).frontmatter.draft === true || /\bdraft\s*:\s*true\b/.test(sourceMetadata ?? "")
+		});
+	}
+	return resources;
+}
+/** Literal interface requests must exist even when a newly added control has no dictionary entry yet. */
+async function sharedInterfaceKeys(sourceRoot = join(dirname(fileURLToPath(import.meta.resolve("@master/internal-site/package.json"))), "src")) {
+	const keys = /* @__PURE__ */ new Set();
+	const visit = async (directory) => {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const file = join(directory, entry.name);
+			if (entry.isDirectory()) await visit(file);
+			else if (/\.(?:astro|svelte|ts|js)$/.test(entry.name) && !/\.(?:test|spec)\./.test(entry.name)) {
+				const source = await readFile(file, "utf8");
+				for (const match of source.matchAll(/\bt\s*\(\s*(?=['"`])/g)) {
+					const expression = acorn.parseExpressionAt(source, match.index + match[0].length, { ecmaVersion: "latest" });
+					const value = expression.type === "Literal" ? expression.value : expression.type === "TemplateLiteral" && !expression.expressions.length ? expression.quasis[0].value.cooked : void 0;
+					if (typeof value === "string" && value.trim()) keys.add(value);
+				}
+			}
+		}
+	};
+	await visit(sourceRoot);
+	return [...keys].sort();
+}
+/** Follow local prose/data modules without executing them or importing product compiler code. */
+async function collectSourceDependencies(files, { siteRoot }) {
+	const root = resolve(siteRoot);
+	const sharedRoot = dirname(fileURLToPath(import.meta.resolve("@master/internal-site/package.json")));
+	const collected = {};
+	const seen = /* @__PURE__ */ new Set();
+	const visit = async (file) => {
+		file = resolve(file).replace(/\.(tw|ja|ko|cn)\.mdx$/, ".mdx");
+		if (!file.startsWith(root + sep) && !file.startsWith(sharedRoot + sep) || seen.has(file)) return;
+		if (file.startsWith(sharedRoot + sep) && /\/common\/(?:translations|locales)\.[jt]s$/.test(file.replaceAll("\\", "/"))) return;
+		seen.add(file);
+		const source = await readFile(file, "utf8").catch(() => void 0);
+		if (source === void 0) return;
+		const key = file.startsWith(sharedRoot + sep) ? `@master/internal-site/${relative(sharedRoot, file)}` : relative(root, file);
+		collected[key.replaceAll("\\", "/")] = source;
+		const imports = source.matchAll(/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)(['"])([^'"\n]+)\1/g);
+		for (const [, , specifier] of imports) {
+			if (!specifier.startsWith(".") && !specifier.startsWith("~/site/") && !specifier.startsWith("@master/internal-site/")) continue;
+			let target;
+			try {
+				target = specifier.startsWith("@master/internal-site/") ? fileURLToPath(import.meta.resolve(specifier.split("?")[0])) : specifier.startsWith("~/site/") ? resolve(root, specifier.slice(7)) : resolve(dirname(file), specifier.split("?")[0]);
+			} catch {
+				continue;
+			}
+			if (extname(target) && !/\.(?:[cm]?[jt]s|[jt]sx|mdx|astro|svelte)$/.test(target)) continue;
+			const candidates = extname(target) ? [target, .../\.js$/.test(target) ? [target.replace(/\.js$/, ".ts")] : []] : [
+				"",
+				".ts",
+				".js",
+				".mdx",
+				".astro",
+				".svelte",
+				"/index.ts",
+				"/index.js"
+			].map((suffix) => target + suffix);
+			for (const candidate of candidates) {
+				const before = Object.keys(collected).length;
+				await visit(candidate);
+				if (Object.keys(collected).length > before) break;
+			}
+		}
+	};
+	for (const file of files) await visit(file);
+	return Object.fromEntries(Object.entries(collected).sort(([a], [b]) => a.localeCompare(b)));
+}
+function headings(source) {
+	const parsed = parseFrontmatter(source);
+	const offset = source.indexOf(parsed.content, parsed.rawFrontmatter ? parsed.rawFrontmatter.length : 0);
+	const tree = fromMarkdown(parsed.content, {
+		extensions: [
+			{ disable: { null: [
+				"htmlFlow",
+				"htmlText",
+				"codeIndented"
+			] } },
+			mdxjsEsm({
+				acorn,
+				addResult: true
+			}),
+			mdxJsx({
+				acorn,
+				addResult: true
+			})
+		],
+		mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+	});
+	const resolveHeading = createHeadingResolver();
+	const found = [];
+	const visit = (node) => {
+		if (node.type === "heading" && node.depth >= 2 && node.depth <= 6) {
+			const title = node.children.filter((child) => child.type === "text" || child.type === "inlineCode").map((child) => child.value).join(" ").trim();
+			const resolved = resolveHeading(title, node.depth);
+			const raw = parsed.content.slice(node.position.start.offset, node.position.end.offset);
+			const end = raw.includes("\n") ? node.position.start.offset + raw.indexOf("\n") : node.position.end.offset;
+			found.push({
+				id: resolved.id ?? "",
+				explicit: resolved.explicit,
+				offset: Math.max(0, offset) + end
+			});
+		}
+		node.children?.forEach(visit);
+	};
+	visit(tree);
+	return found;
+}
+function headingAnchors(source) {
+	return headings(source).map((heading) => heading.id);
+}
+/** Pin the existing automatic English IDs before translation, without modifying fenced examples. */
+function stabilizeHeadingAnchors(source) {
+	for (const heading of headings(source).reverse()) {
+		if (heading.explicit || !heading.id) continue;
+		const closing = source.slice(0, heading.offset).match(/[ \t]+#+[ \t]*$/)?.[0] ?? "";
+		const at = heading.offset - closing.length;
+		source = source.slice(0, at) + ` \\{#${heading.id}\\}` + source.slice(at);
+	}
+	return source;
+}
+export { emptyReviews as a, reviewTranslation as c, validateSiteTranslations as d, isSharedMdxSample as f, createHeadingResolver as h, discoverDocumentResources as i, sharedInterfaceKeys as l, locales as m, auditTranslations as n, headingAnchors as o, localizedMetadata as p, collectSourceDependencies as r, readLocalizedDocument as s, assertTranslations as t, stabilizeHeadingAnchors as u };

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.2",
+  "version": "0.2.0",
   "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,11 @@ 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'
 import svgoConfig from '../docs-shell/common/svgo.config.js'
@@ -28,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')
@@ -40,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',
@@ -74,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.
@@ -109,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' })]
         })
       },
@@ -118,6 +123,7 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
         const destination = output
         await mkdir(destination, { recursive: true })
         await cp(new URL('../public/', import.meta.url), destination, { recursive: true, force: false })
+        await compactStyleAssets(fileURLToPath(destination))
       }
     }
   }

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 }
+    }
+  }
+}