@sudajs/cli 0.13.4 → 0.15.0

package/dist/index.d.ts

@@ -1702,6 +1702,7 @@ declare function fetchJson<T>(url: string, options?: RequestInit & {
 declare function validateThemeTailwindContract(root: string): Promise<void>;
 declare function validateTheme(root: string): Promise<ValidatedTheme>;
 declare function validateThemeLocales(root: string): Promise<void>;
+declare function validateThemePreviewLocales(root: string, previewLocales: string[] | undefined): Promise<void>;
 declare function toViteModuleUrl(root: string, absolutePath: string): string;
 declare function buildTheme(root: string): Promise<ValidatedTheme>;
 declare function finalizeTheme(root: string): Promise<ValidatedTheme>;
@@ -1728,11 +1729,20 @@ declare const __testUtils: {
     validateThemeName: typeof validateThemeName;
     validateThemeTailwindContract: typeof validateThemeTailwindContract;
     validateThemeLocales: typeof validateThemeLocales;
+    validateThemePreviewLocales: typeof validateThemePreviewLocales;
+    resolveThemePreviewLocale: typeof resolveThemePreviewLocale;
+    withSerializedVitePreviewLocaleLoad: typeof withSerializedVitePreviewLocaleLoad;
     toViteModuleUrl: typeof toViteModuleUrl;
     updateRemotePageDraft: typeof updateRemotePageDraft;
 };
 declare function watchTheme(root: string, port: number): Promise<void>;
+declare function withSerializedVitePreviewLocaleLoad<Result>(server: object, load: () => Promise<Result>): Promise<Result>;
 declare function resolveDevStarterSlug(pathname: string): string | null | undefined;
+declare function resolveThemePreviewLocale(params: {
+    previewLocales: string[] | undefined;
+    explicitLang?: string | null;
+    acceptLanguage?: string;
+}): string;
 /**
  * Theme-project-scoped renderer bundle. We deliberately resolve `react`,
  * `react-dom/server` and `@sudajs/theme-engine/server` through the theme
@@ -1751,7 +1761,7 @@ interface ThemeRenderer {
     renderToString: typeof renderToString;
 }
 declare function loadThemeScopedRenderer(themeRoot: string): Promise<ThemeRenderer>;
-declare function renderDevStarterPageHtml(theme: ValidatedTheme, page: ThemeStarterPage, renderer: ThemeRenderer): string;
+declare function renderDevStarterPageHtml(theme: ValidatedTheme, page: ThemeStarterPage, renderer: ThemeRenderer, locale?: string, preserveLang?: boolean): string;
 interface ScreenshotOptions extends ThemeRootOptions {
     device?: string[] | string;
     output?: string;

package/dist/index.js

@@ -9,7 +9,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { themeDesignSystemSchema, createThemeAgentManifest, createSudaPageAgentRuntime, checkThemeModule, formatThemeCheckResult, agentValidationResultSchema, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
-import { themeManifestSchema } from '@sudajs/theme-engine/server';
+import { themeManifestSchema, runWithThemePreviewLocale } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build } from 'esbuild';
 import { z } from 'zod';
@@ -580,85 +580,105 @@ export const { createRoot, hydrateRoot, version } = ReactDOMClient;
     }
   };
 }
-function createHostPuckCoreShimPlugin() {
+function createRejectEditorRuntimeDependencyPlugin() {
   return {
-    name: "suda-host-puck-core-shim",
+    name: "suda-reject-editor-runtime-dependency",
     setup(build) {
-      build.onResolve({ filter: /^@puckeditor\/core$/ }, () => ({
-        path: "puck-core-host-shim",
-        namespace: "suda-shim"
-      }));
-      build.onLoad({ filter: /^puck-core-host-shim$/, namespace: "suda-shim" }, () => ({
-        loader: "js",
-        contents: `
-const PuckCore = globalThis.__SUDA_PUCK_CORE__;
-if (!PuckCore) {
-  throw new Error("Missing host Puck core runtime (__SUDA_PUCK_CORE__).");
-}
-export default PuckCore;
-export const {
-  Action,
-  ActionBar,
-  AutoField,
-  Button,
-  Drawer,
-  DropZone,
-  FieldLabel,
-  Group,
-  IconButton,
-  Label,
-  Puck,
-  Render,
-  RichTextMenu,
-  Separator,
-  blocksPlugin,
-  createUsePuck,
-  fieldsPlugin,
-  legacySideBarPlugin,
-  migrate,
-  outlinePlugin,
-  overrideKeys,
-  registerOverlayPortal,
-  renderContext,
-  resolveAllData,
-  setDeep,
-  transformProps,
-  useGetPuck,
-  usePuck,
-  walkTree,
-} = PuckCore;
-`
+      build.onResolve({ filter: /^@puckeditor\/(?:core|plugin-ai)(?:\/.*)?$/ }, (args) => ({
+        errors: [
+          {
+            text: `${args.path} is an editor dependency and cannot be imported by the public theme client runtime.`
+          }
+        ]
       }));
     }
   };
 }
-function createThemeEngineRuntimeAliasPlugin(root) {
+function createHostThemeRuntimeShimPlugin() {
   return {
-    name: "suda-theme-engine-runtime-alias",
+    name: "suda-host-theme-runtime-shim",
     setup(build) {
-      const themeRequire = createRequire(path2.join(root, "package.json"));
-      const runtimeEntry = themeRequire.resolve("@sudajs/theme-engine/runtime");
       build.onResolve({ filter: /^@sudajs\/theme-engine\/runtime$/ }, () => ({
-        path: runtimeEntry
+        path: "theme-runtime-host-shim",
+        namespace: "suda-shim"
+      }));
+      build.onLoad({ filter: /^theme-runtime-host-shim$/, namespace: "suda-shim" }, () => ({
+        loader: "js",
+        contents: `
+const ThemeRuntime = globalThis.__SUDA_THEME_RUNTIME__;
+if (!ThemeRuntime) {
+  throw new Error("Missing host theme runtime (__SUDA_THEME_RUNTIME__).");
+}
+export const {
+  SudaLucideIcon,
+  isSudaLucideIconName,
+  normalizeSudaLucideIconName,
+  colorSchemeField,
+  createColorSchemeDefault,
+  createThemeCssVariables,
+  designSystemField,
+  resolveColorSchemeTokens,
+  SUDA_COLOR_TOKEN_KEYS,
+  createThemeDesignCssVariables,
+  createThemeDesignDefault,
+  resolveThemeDesignTokens,
+  SUDA_CUSTOM_DESIGN_PRESET_ID,
+  SUDA_DESIGN_COLOR_KEYS,
+  SUDA_DESIGN_RADIUS_KEYS,
+  compileSudaBlockSlots,
+  isSudaLocalBlockComponent,
+  SUDA_LOCAL_BLOCK_CATEGORY,
+  SUDA_LOCAL_BLOCK_TYPE_PREFIX,
+  cmsPaginationUrl,
+  getIcpRecord,
+  getCmsContent,
+  getContactForm,
+  getPostResource,
+  getWhiteLabel,
+  resolveAsset,
+  postResourceKey,
+  getPageSlot,
+  THEME_PAGE_SLOT,
+  createThemeAsset,
+  createThemeAssetPath,
+  createThemeAssetResolver,
+  resolveThemeClientRuntimeUrl,
+  resolveThemeRuntimeUrl,
+  resolveAssetPath,
+  THEME_CLIENT_RUNTIME_ARTIFACT,
+  clearThemeLocale,
+  createThemeTranslate,
+  installThemeLocale,
+  clearThemePreviewLocale,
+  createThemePreviewTranslate,
+  installThemePreviewLocale,
+} = ThemeRuntime;
+`
       }));
     }
   };
 }
-function createThemeEngineIconAliasPlugin(root) {
+function createHostThemeIconsShimPlugin() {
   return {
-    name: "suda-theme-engine-icon-alias",
+    name: "suda-host-theme-icons-shim",
     setup(build) {
-      const themeRequire = createRequire(path2.join(root, "package.json"));
-      const themeEngineEntry = themeRequire.resolve("@sudajs/theme-engine");
-      const entryDir = path2.dirname(themeEngineEntry);
-      const packageRoot2 = path2.basename(entryDir) === "dist" || path2.basename(entryDir) === "src" ? path2.dirname(entryDir) : entryDir;
-      const sourceEntry = path2.join(packageRoot2, "src", "icons", "lucide-icon.hydrate.client.tsx");
       build.onResolve({ filter: /^@sudajs\/theme-engine\/icons$/ }, () => {
-        if (existsSync(sourceEntry)) {
-          return { path: sourceEntry };
-        }
-        return { path: themeRequire.resolve("@sudajs/theme-engine/icons") };
+        return { path: "theme-icons-host-shim", namespace: "suda-shim" };
       });
+      build.onLoad({ filter: /^theme-icons-host-shim$/, namespace: "suda-shim" }, () => ({
+        loader: "js",
+        contents: `
+const ThemeIcons = globalThis.__SUDA_THEME_ICONS__;
+if (!ThemeIcons) {
+  throw new Error("Missing host theme icon runtime (__SUDA_THEME_ICONS__).");
+}
+export const {
+  SudaLucideIcon,
+  isSudaLucideIconName,
+  normalizeSudaLucideIconName,
+} = ThemeIcons;
+`
+      }));
     }
   };
 }
@@ -779,9 +799,9 @@ ${issues}`);
   if (module.manifest.entry !== "index.js") {
     throw new Error('manifest.entry must be artifact-local: "index.js".');
   }
-  if (module.manifest.clientEntry !== void 0 && module.manifest.clientEntry !== "runtime.client.js") {
+  if ("clientEntry" in module.manifest) {
     throw new Error(
-      'manifest.clientEntry must be artifact-local: "runtime.client.js" when provided.'
+      "manifest.clientEntry is no longer supported. The CLI owns the runtime.client.js artifact."
     );
   }
   assertRecord(module.pageConfig?.components, "pageConfig.components");
@@ -839,6 +859,7 @@ async function validateTheme(root) {
   validateThemeModule(module);
   await validateThemeTailwindContract(root);
   await validateThemeLocales(root);
+  await validateThemePreviewLocales(root, module.manifest.previewLocales);
   const result = {
     root,
     module,
@@ -885,7 +906,16 @@ async function listLocaleFiles(localesDir) {
     return [];
   }
   const entries = await readdir(localesDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
+  return entries.filter(
+    (entry) => entry.isFile() && entry.name.endsWith(".json") && !entry.name.endsWith(".content.json")
+  ).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
+}
+async function listPreviewLocaleFiles(localesDir) {
+  if (!await pathExists(localesDir)) {
+    return [];
+  }
+  const entries = await readdir(localesDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".content.json")).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
 }
 async function validateThemeLocales(root) {
   const localesDir = path2.join(root, "dist", "locales");
@@ -921,6 +951,47 @@ ${details}`
     }
   }
 }
+async function validateThemePreviewLocales(root, previewLocales) {
+  const localesDir = path2.join(root, "dist", "locales");
+  const files = await listPreviewLocaleFiles(localesDir);
+  const declared = previewLocales ?? [];
+  const expectedFiles = new Set(declared.map((locale) => `${locale}.content.json`));
+  const undeclared = files.filter((file) => !expectedFiles.has(file));
+  const missing = [...expectedFiles].filter((file) => !files.includes(file));
+  if (missing.length > 0 || undeclared.length > 0) {
+    const details = [
+      ...missing.map((file) => `  - missing locales/${file}`),
+      ...undeclared.map((file) => `  - undeclared locales/${file}`)
+    ].join("\n");
+    throw new Error(`Theme preview locale files do not match manifest.previewLocales:
+${details}`);
+  }
+  if (declared.length === 0) {
+    return;
+  }
+  const referenceFile = "en.content.json";
+  const referenceMessages = await readLocaleJson(path2.join(localesDir, referenceFile));
+  const referenceKeys = new Set(collectLocaleKeys(referenceMessages).sort());
+  for (const file of files) {
+    if (file === referenceFile) {
+      continue;
+    }
+    const messages = await readLocaleJson(path2.join(localesDir, file));
+    const keys = new Set(collectLocaleKeys(messages).sort());
+    const missingKeys = [...referenceKeys].filter((key) => !keys.has(key));
+    const extraKeys = [...keys].filter((key) => !referenceKeys.has(key));
+    if (missingKeys.length > 0 || extraKeys.length > 0) {
+      const details = [
+        ...missingKeys.map((key) => `  - missing ${key}`),
+        ...extraKeys.map((key) => `  - extra ${key}`)
+      ].join("\n");
+      throw new Error(
+        `Theme preview locale ${file} does not match ${referenceFile} key set:
+${details}`
+      );
+    }
+  }
+}
 var VITE_CONFIG_FILES = [
   "vite.config.ts",
   "vite.config.mts",
@@ -950,18 +1021,6 @@ async function loadThemeVite(root) {
   }
   return await import(pathToFileURL(viteEntry).href);
 }
-async function findClientEntry(root) {
-  const candidates = [
-    path2.join(root, "src", "runtime.client.tsx"),
-    path2.join(root, "src", "runtime.client.ts")
-  ];
-  for (const candidate of candidates) {
-    if (await pathExists(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error(`Missing runtime entry. Add src/runtime.client.ts(x) in ${root}.`);
-}
 async function findServerEntry(root) {
   const candidates = [path2.join(root, "src", "index.tsx"), path2.join(root, "src", "index.ts")];
   for (const candidate of candidates) {
@@ -1062,38 +1121,74 @@ async function copyThemeLocales(root) {
   await copyDirectory(sourceLocales, path2.join(root, "dist", "locales"));
 }
 async function buildClientRuntime(root, minify) {
-  const entryPoint = await findClientEntry(root);
-  if (!await pathExists(entryPoint)) {
-    throw new Error(`Missing client entry: ${entryPoint}`);
+  const legacyEntries = [
+    path2.join(root, "src", "runtime.client.ts"),
+    path2.join(root, "src", "runtime.client.tsx")
+  ];
+  if (legacyEntries.some((entry) => existsSync(entry))) {
+    throw new Error(
+      "Theme-authored src/runtime.client.ts(x) is no longer supported. Move optional browser setup to src/client.ts as clientHooks; the CLI owns runtime.client.js."
+    );
   }
   const packageJson = JSON.parse(await readFile(path2.join(root, "package.json"), "utf8"));
   const themeVersion = typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+  const clientHooksPath = path2.join(root, "src", "client.ts");
+  const generatedEntry = path2.join(root, ".suda-build", "runtime.client.ts");
+  const clientHooksImport = await pathExists(clientHooksPath) ? 'import { clientHooks } from "../src/client.js";' : "const clientHooks = {};";
+  await mkdir(path2.dirname(generatedEntry), { recursive: true });
+  await writeFile(
+    generatedEntry,
+    [
+      '"use client";',
+      'import type { ThemeClientHooks, ThemeClientRuntime, ThemeRenderModule } from "@sudajs/theme-engine/runtime";',
+      'import * as themeConfig from "../src/config.js";',
+      clientHooksImport,
+      "const theme: ThemeRenderModule = {",
+      "  pageConfig: themeConfig.pageConfig,",
+      "  layoutConfig: themeConfig.layoutConfig,",
+      "};",
+      'if ("rendering" in themeConfig && themeConfig.rendering !== undefined) {',
+      "  theme.rendering = themeConfig.rendering;",
+      "}",
+      "const hooks: ThemeClientHooks = clientHooks;",
+      "const runtime: ThemeClientRuntime = { theme };",
+      "if (hooks.initialize !== undefined) {",
+      "  runtime.initialize = hooks.initialize;",
+      "}",
+      "export default runtime;",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
   await mkdir(path2.join(root, "dist"), { recursive: true });
   const hostReactShimPlugin = createHostReactShimPlugin();
-  const hostPuckCoreShimPlugin = createHostPuckCoreShimPlugin();
-  const themeEngineRuntimeAliasPlugin = createThemeEngineRuntimeAliasPlugin(root);
-  const themeEngineIconAliasPlugin = createThemeEngineIconAliasPlugin(root);
+  const rejectEditorRuntimeDependencyPlugin = createRejectEditorRuntimeDependencyPlugin();
+  const hostThemeRuntimeShimPlugin = createHostThemeRuntimeShimPlugin();
+  const hostThemeIconsShimPlugin = createHostThemeIconsShimPlugin();
   const themeDependencyResolverPlugin = createThemeDependencyResolverPlugin(root);
   await build({
     bundle: true,
-    entryPoints: [entryPoint],
+    entryPoints: { "runtime.client": generatedEntry },
     external: ["react", "react/*", "react-dom", "react-dom/*"],
     format: "esm",
     jsx: "automatic",
+    logOverride: { "import-is-undefined": "silent" },
     minify,
-    outfile: path2.join(root, "dist", "runtime.client.js"),
+    outdir: path2.join(root, "dist"),
     platform: "browser",
     define: {
       __SUDA_THEME_VERSION__: JSON.stringify(themeVersion)
     },
     plugins: [
       hostReactShimPlugin,
-      hostPuckCoreShimPlugin,
-      themeEngineRuntimeAliasPlugin,
-      themeEngineIconAliasPlugin,
+      rejectEditorRuntimeDependencyPlugin,
+      hostThemeRuntimeShimPlugin,
+      hostThemeIconsShimPlugin,
       themeDependencyResolverPlugin
     ],
     sourcemap: false,
+    splitting: true,
+    chunkNames: "chunks/[name]-[hash]",
     target: "es2022",
     treeShaking: true
   });
@@ -1284,6 +1379,9 @@ var __testUtils = {
   validateThemeName,
   validateThemeTailwindContract,
   validateThemeLocales,
+  validateThemePreviewLocales,
+  resolveThemePreviewLocale,
+  withSerializedVitePreviewLocaleLoad,
   toViteModuleUrl,
   updateRemotePageDraft
 };
@@ -1381,7 +1479,15 @@ function createSudaPreviewVitePlugin(root) {
             return;
           }
           try {
-            const theme = await loadViteDevTheme(root, server);
+            const acceptLanguageHeader = request.headers["accept-language"];
+            const acceptLanguage = Array.isArray(acceptLanguageHeader) ? acceptLanguageHeader.join(",") : acceptLanguageHeader;
+            const explicitLang = url.searchParams.get("lang");
+            const { theme, locale } = await loadLocalizedViteDevTheme(
+              root,
+              server,
+              explicitLang,
+              acceptLanguage
+            );
             const renderer = await loadThemeScopedRenderer(root);
             if (slug === null) {
               const homeSlug = pickStarterSlug(theme);
@@ -1398,7 +1504,13 @@ function createSudaPreviewVitePlugin(root) {
               }
               const html2 = await server.transformIndexHtml(
                 url.pathname,
-                renderDevStarterPageHtml(theme, starter2, renderer)
+                renderDevStarterPageHtml(
+                  theme,
+                  starter2,
+                  renderer,
+                  locale,
+                  canonicalLocale(explicitLang) !== null
+                )
               );
               response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
               response.end(html2);
@@ -1412,7 +1524,13 @@ function createSudaPreviewVitePlugin(root) {
             }
             const html = await server.transformIndexHtml(
               url.pathname,
-              renderDevStarterPageHtml(theme, starter, renderer)
+              renderDevStarterPageHtml(
+                theme,
+                starter,
+                renderer,
+                locale,
+                canonicalLocale(explicitLang) !== null
+              )
             );
             response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
             response.end(html);
@@ -1425,6 +1543,48 @@ function createSudaPreviewVitePlugin(root) {
     }
   };
 }
+async function loadLocalizedViteDevTheme(root, server, explicitLang, acceptLanguage) {
+  return withSerializedVitePreviewLocaleLoad(server, async () => {
+    const baseTheme = await loadViteDevTheme(root, server);
+    const localeParams = {
+      previewLocales: baseTheme.module.manifest.previewLocales,
+      explicitLang
+    };
+    if (acceptLanguage !== void 0) {
+      localeParams.acceptLanguage = acceptLanguage;
+    }
+    const locale = resolveThemePreviewLocale(localeParams);
+    if (!baseTheme.module.manifest.previewLocales) {
+      return { theme: baseTheme, locale };
+    }
+    const messages = await readDevPreviewLocaleMessages(root, locale);
+    server.moduleGraph.invalidateAll();
+    const theme = await runWithThemePreviewLocale(
+      messages,
+      () => loadViteDevTheme(root, server)
+    );
+    return { theme, locale };
+  });
+}
+var vitePreviewLocaleLoadTails = /* @__PURE__ */ new WeakMap();
+async function withSerializedVitePreviewLocaleLoad(server, load) {
+  const previous = vitePreviewLocaleLoadTails.get(server) ?? Promise.resolve();
+  let release;
+  const gate = new Promise((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => gate);
+  vitePreviewLocaleLoadTails.set(server, tail);
+  await previous;
+  try {
+    return await load();
+  } finally {
+    release();
+    if (vitePreviewLocaleLoadTails.get(server) === tail) {
+      vitePreviewLocaleLoadTails.delete(server);
+    }
+  }
+}
 async function loadViteDevTheme(root, server) {
   const serverEntryPath = await findServerEntry(root);
   const imported = await server.ssrLoadModule(toViteModuleUrl(root, serverEntryPath));
@@ -1461,6 +1621,73 @@ function resolveDevStarterSlug(pathname) {
   }
   return decodeURIComponent(normalized);
 }
+function canonicalLocale(value) {
+  const candidate = value?.trim();
+  if (!candidate || candidate === "*") {
+    return null;
+  }
+  try {
+    return Intl.getCanonicalLocales(candidate)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function acceptLanguageLocales(value) {
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((part, index) => {
+    const [rawLocale, ...parameters] = part.trim().split(";");
+    const locale = canonicalLocale(rawLocale);
+    const qualityParameter = parameters.find((parameter) => parameter.trim().startsWith("q="));
+    const parsedQuality = qualityParameter ? Number.parseFloat(qualityParameter.trim().slice(2)) : 1;
+    const quality = Number.isFinite(parsedQuality) ? parsedQuality : 0;
+    return { locale, quality, index };
+  }).filter(
+    (entry) => Boolean(entry.locale) && entry.quality > 0
+  ).sort((left, right) => right.quality - left.quality || left.index - right.index).map((entry) => entry.locale);
+}
+function localeLookupCandidates(locale) {
+  const candidates = [];
+  let current = locale;
+  while (current) {
+    candidates.push(current);
+    const separator = current.lastIndexOf("-");
+    if (separator < 0) {
+      break;
+    }
+    current = current.slice(0, separator);
+  }
+  return candidates;
+}
+function resolveThemePreviewLocale(params) {
+  const supported = params.previewLocales ?? ["en"];
+  const supportedByNormalized = new Map(
+    supported.map((locale) => [locale.toLowerCase(), locale])
+  );
+  const explicitLocale = canonicalLocale(params.explicitLang);
+  const requestedLocales = explicitLocale ? [explicitLocale] : acceptLanguageLocales(params.acceptLanguage);
+  for (const requested of requestedLocales) {
+    for (const candidate of localeLookupCandidates(requested)) {
+      const supportedLocale = supportedByNormalized.get(candidate.toLowerCase());
+      if (supportedLocale) {
+        return supportedLocale;
+      }
+    }
+    if (explicitLocale) {
+      break;
+    }
+  }
+  return supportedByNormalized.get("en") ?? "en";
+}
+async function readDevPreviewLocaleMessages(root, locale) {
+  const filePath = path2.join(root, "src", "locales", `${locale}.content.json`);
+  const messages = await readLocaleJson(filePath);
+  if (!isRecord(messages)) {
+    throw new Error(`Theme preview locale ${locale} must be a JSON object.`);
+  }
+  return messages;
+}
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -1494,7 +1721,7 @@ async function loadThemeScopedRenderer(themeRoot) {
     renderToString: reactDomServerModule.renderToString
   };
 }
-function renderDevStarterPageHtml(theme, page, renderer) {
+function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserveLang = false) {
   const chrome = renderer.extractLayoutChrome(theme.module.defaultLayout);
   const metadata = {
     resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath),
@@ -1513,7 +1740,7 @@ function renderDevStarterPageHtml(theme, page, renderer) {
   const customBody = chrome.customBodyCode ?? "";
   return [
     "<!doctype html>",
-    '<html lang="en">',
+    `<html lang="${escapeHtml(locale)}">`,
     "<head>",
     '<meta charset="utf-8" />',
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
@@ -1524,6 +1751,9 @@ function renderDevStarterPageHtml(theme, page, renderer) {
     `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
     body,
     customBody,
+    ...preserveLang ? [
+      '<script>for(const a of document.querySelectorAll("a[href]")){try{const u=new URL(a.href,location.href);if(u.origin===location.origin){u.searchParams.set("lang",new URL(location.href).searchParams.get("lang"));a.href=u.pathname+u.search+u.hash}}catch{}}</script>'
+    ] : [],
     "</body>",
     "</html>"
   ].join("");