@takazudo/zudo-doc 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.15.0] - 2026-09-01
+
+### Features
+
+- Added an accessible language dropdown that scales to every configured locale instead of assuming a two-language site. (`607121e9`)
+- Generated locale-owned Claude/Codex resource indexes and Asset Viewer routes for every configured locale, with translated page chrome, locale-preserving links, and safe handling of generated versus authored indexes. (`781fb820`, `8ceca53e`, `44ae7812`, `1e558854`, `5d682bc1`)
+- Localized all seven `HtmlPreview` control labels and added per-preview `labels`, `showSource`, and `showViewportControls` overrides while preserving host-provided MDX bindings. (`ffee673f`, `6538184a`)
+- Added `loading="visible"` for route-bound `HtmlPreview` instances, deferring iframe markup, scripts, and external resources until the reserved preview area enters the viewport. (`df63d981`)
+- Kept auto-height previews synchronized after delayed content changes and viewport reflows, including both growth and shrink. (`df3d4b56`)
+- Added escaped, nonblank language and title metadata to generated preview documents, with explicit author `<title>` content retaining precedence. (`2b8b0ee3`, `55e66300`)
+
+### Bug Fixes
+
+- Retained package English strings when a configured locale supplies only partial translations. (`0a3619cb`)
+- Preserved an explicit empty `sandbox` attribute in generated HTML so strict opaque previews remain sandboxed as authored. (`c8b1cac7`)
+- Increased interactive `HtmlPreview` controls to accessible minimum hit-target dimensions. (`a35f1573`)
+
+### Other Changes
+
+- Updated the zfb peer family to 2.14.2. (`5c5bfd2f`)
+
 ## [5.14.0] - 2026-08-31
 
 ### Features
@@ -23,6 +44,8 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 ### Other Changes
 
+- Enabled Asset Viewer routes now localize automatically for existing multi-locale consumers after a package bump, unless `/${assetViewerRoutePrefix}/` is explicitly present in `defaultLocaleOnlyPrefixes`. Existing apps that already carry the legacy Claude/Codex resource prefixes remain default-locale-only after upgrading; remove the prefixes for resource sections you want generated in every configured locale. (#3820)
+- Migration: before building with 5.14.0, remove or rename any authored locale resource overview/category `index.mdx` at a generator target and move custom titles, descriptions, and labels to `ZudoDocConfig.translations`. The generator refuses to overwrite an existing file unless its frontmatter contains `generated: true`. (#3820)
 - Updated the zfb peer family to 2.14.0, `@takazudo/zdtp` to 0.4.14, and the doc-history-server peer floor to 5.13.1. (`dbe8553c7`, `038870c94`, `95a82f15f`)
 
 ## [5.13.1] - 2026-08-28

package/dist/asset-components/asset-card.js

@@ -2,6 +2,7 @@ import { jsx, jsxs } from "preact/jsx-runtime";
 import { assetRawHref, assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
+  assetComponentViewerLocale,
   assetComponentText,
   formatAssetBytes,
   formatAssetLanguage,
@@ -23,7 +24,8 @@ function createAssetCard(context) {
     const viewerHref = assetViewerHref({
       base: context.base,
       routePrefix: context.routePrefix,
-      path
+      path,
+      locale: assetComponentViewerLocale(context, path)
     });
     const rawHref = assetRawHref({ base: context.base, dir: context.dir, path });
     const details = [

package/dist/asset-components/asset-code.js

@@ -2,6 +2,7 @@ import { jsx, jsxs } from "preact/jsx-runtime";
 import { assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
+  assetComponentViewerLocale,
   assetComponentText,
   MissingAssetWarning,
   resolveAssetEntry
@@ -43,6 +44,7 @@ function createAssetCode(context) {
       base: context.base,
       routePrefix: context.routePrefix,
       path: resolved.path,
+      locale: assetComponentViewerLocale(context, resolved.path),
       fragment: excerpt.viewerLineAvailable ? `L${excerpt.startLine}` : void 0
     });
     const shown = Math.max(0, excerpt.endLine - excerpt.startLine + 1);

package/dist/asset-components/shared.d.ts

@@ -7,9 +7,14 @@ export interface AssetComponentContext {
     assetManifest: AssetManifest | null;
     routePrefix: string;
     dir: string;
+    /** Non-default locale segment for viewer links. */
+    locale?: string;
+    /** Match viewer paths that intentionally remain default-locale-only. */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
     /** Locale-bound package translator. Omitted callers retain English fallbacks. */
     t?: (key: string) => string;
 }
+export declare function assetComponentViewerLocale(context: AssetComponentContext, path: string): string | undefined;
 export declare function assetComponentText(context: AssetComponentContext, key: string, fallback: string, values?: Record<string, string | number>): string;
 export declare function resolveAssetEntry(src: string, context: AssetComponentContext): {
     path: string;

package/dist/asset-components/shared.js

@@ -1,5 +1,11 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { decodeAuthoredHref } from "../asset-path/index.js";
+function assetComponentViewerLocale(context, path) {
+  if (context.isDefaultLocaleOnlyPath?.(`/${context.routePrefix}/${path}`)) {
+    return void 0;
+  }
+  return context.locale;
+}
 function assetComponentText(context, key, fallback, values = {}) {
   let text = context.t?.(key) ?? fallback;
   for (const [name, value] of Object.entries(values)) {
@@ -83,6 +89,7 @@ export {
   AssetFileIcon,
   MissingAssetWarning,
   assetComponentText,
+  assetComponentViewerLocale,
   formatAssetBytes,
   formatAssetLanguage,
   resolveAssetEntry

package/dist/asset-index-page/index.d.ts

@@ -14,6 +14,7 @@ export interface AssetTreeNode {
 }
 export interface AssetIndexPageViewProps {
     entries: AssetIndexEntry[];
+    locale?: string;
 }
 /** Build a sorted directory tree and aggregate every directory's subtree totals. */
 export declare function buildAssetTree(entries: AssetIndexEntry[]): AssetTreeNode;

package/dist/asset-index-page/index.js

@@ -86,7 +86,7 @@ function iconFor(asset) {
 function countLabel(count, plural, single) {
   return (count === 1 ? single : plural).replace("{count}", String(count));
 }
-function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel, root = false }) {
+function AssetTree({ node, base, routePrefix, locale, fileCountLabel, fileCountSingleLabel, linesLabel, root = false }) {
   return /* @__PURE__ */ jsxs("ul", { "data-zd-asset-tree": root ? true : void 0, children: [
     node.dirs.map((dir) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("details", { open: true, children: [
       /* @__PURE__ */ jsxs("summary", { class: "flex cursor-pointer items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small hover:bg-accent/10 focus-visible:bg-accent/10", children: [
@@ -103,13 +103,13 @@ function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLab
           formatAssetBytes(dir.bytes)
         ] })
       ] }),
-      /* @__PURE__ */ jsx(AssetTree, { node: dir, base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel })
+      /* @__PURE__ */ jsx(AssetTree, { node: dir, base, routePrefix, locale, fileCountLabel, fileCountSingleLabel, linesLabel })
     ] }) })),
     node.files.map((asset) => {
       const Icon = iconFor(asset);
       const facet = facetLabel(asset, linesLabel);
       const meta = [kindLabel(asset), facet, formatAssetBytes(asset.bytes)].filter(Boolean).join(" \xB7 ");
-      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path }), title: asset.name, class: "flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
+      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path, locale }), title: asset.name, class: "flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
         /* @__PURE__ */ jsx(Icon, { className: "h-icon-sm w-icon-sm shrink-0 text-muted" }),
         /* @__PURE__ */ jsx("span", { class: "min-w-0 truncate font-mono", children: basename(asset.path) }),
         /* @__PURE__ */ jsx("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block", children: meta })
@@ -120,17 +120,18 @@ function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLab
 function createAssetIndexPageView(ctx) {
   assertChromeContext(ctx, "createAssetIndexPageView");
   const settings = ctx.settings;
-  const locale = ctx.defaultLocale;
   const t = ctx.t;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults, Breadcrumb: BreadcrumbWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const dataThemePack = resolveThemePackSsrSlug(ctx.themePackRegistry, settings);
-  return function AssetIndexPageView({ entries }) {
+  return function AssetIndexPageView({ entries, locale = ctx.defaultLocale }) {
+    const localeSegment = locale === ctx.defaultLocale ? void 0 : locale;
     const routePrefix = ctx.assetManifest?.routePrefix ?? settings.assetViewerRoutePrefix;
     const dir = ctx.assetManifest?.dir ?? settings.assetViewerDir;
-    const indexUrl = ctx.withBase(`/${routePrefix}/`);
+    const indexUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}${routePrefix}/`);
+    const homeUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}`);
     const tree = buildAssetTree(entries);
     const folders = folderCount(tree);
     const fileCountLabel = t("asset.fileCount", locale);
@@ -138,7 +139,7 @@ function createAssetIndexPageView(ctx) {
     const folderCountLabel = t("asset.folderCount", locale);
     const folderCountSingleLabel = t("asset.folderCountSingle", locale);
     const title = t("asset.crumb", locale);
-    return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(title), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title, description: t("asset.indexDescription", locale), canonical: ctx.absoluteUrl(indexUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: [{ label: "", href: ctx.withBase("/") }, { label: title }] }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: indexUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { "data-zd-asset-index-page": true, children: [
+    return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(title), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title, description: t("asset.indexDescription", locale), canonical: ctx.absoluteUrl(indexUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: [{ label: "", href: homeUrl }, { label: title }] }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: indexUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { "data-zd-asset-index-page": true, children: [
       /* @__PURE__ */ jsxs("header", { children: [
         /* @__PURE__ */ jsxs("div", { class: "mb-vsp-xs flex flex-wrap items-center gap-hsp-xs text-micro tracking-wide uppercase", children: [
           /* @__PURE__ */ jsx("span", { class: "rounded-full border border-muted px-hsp-sm py-vsp-3xs text-fg", children: title }),
@@ -163,7 +164,7 @@ function createAssetIndexPageView(ctx) {
           /* @__PURE__ */ jsx("button", { type: "button", disabled: true, "data-zd-asset-index-action": "collapse", class: "text-fg hover:text-accent focus-visible:text-accent", children: t("asset.collapseAll", locale) })
         ] })
       ] }),
-      entries.length > 0 ? /* @__PURE__ */ jsx(AssetTree, { root: true, node: tree, base: settings.base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel: t("asset.lines", locale) }) : /* @__PURE__ */ jsx("p", { class: "text-small text-muted", "data-zd-asset-index-empty": true, children: t("asset.indexEmpty", locale) }),
+      entries.length > 0 ? /* @__PURE__ */ jsx(AssetTree, { root: true, node: tree, base: settings.base, routePrefix, locale: localeSegment, fileCountLabel, fileCountSingleLabel, linesLabel: t("asset.lines", locale) }) : /* @__PURE__ */ jsx("p", { class: "text-small text-muted", "data-zd-asset-index-empty": true, children: t("asset.indexEmpty", locale) }),
       /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: ASSET_INDEX_PAGE_SCRIPT } })
     ] }) });
   };

package/dist/asset-page/index.d.ts

@@ -8,6 +8,7 @@ export { ASSET_PAGE_SCRIPT } from "./script.js";
 export type { AssetRecord } from "../plugins/internal/asset-viewer/types.js";
 export interface AssetPageViewProps {
     entry: AssetRecord;
+    locale?: string;
 }
 export declare function AssetEyebrow({ asset, badge }: {
     asset: AssetRecord;
@@ -36,9 +37,17 @@ export declare function AssetCodeBody({ asset, copyLabel, wrapLabel, truncatedLa
     truncatedLabel: string;
     linesLabel?: string;
 }): VNode;
-export declare function AssetImageStage({ asset, rawUrl }: {
+export interface AssetImageStageLabels {
+    fit: string;
+    actualSize: string;
+    checker: string;
+    dark: string;
+    enlarge: string;
+}
+export declare function AssetImageStage({ asset, rawUrl, labels }: {
     asset: AssetRecord;
     rawUrl: string;
+    labels: AssetImageStageLabels;
 }): VNode;
 export declare function AssetVideoStage({ asset, rawUrl }: {
     asset: AssetRecord;
@@ -60,8 +69,17 @@ export declare function AssetLinkedFrom({ asset, label }: {
     asset: AssetRecord;
     label: string;
 }): VNode | null;
-export declare function AssetDetails({ asset }: {
+export interface AssetDetailsLabels {
+    heading: string;
+    type: string;
+    size: string;
+    path: string;
+    dimensions: string;
+    updated: string;
+}
+export declare function AssetDetails({ asset, labels }: {
     asset: AssetRecord;
+    labels: AssetDetailsLabels;
 }): VNode;
 /** Build the package-owned wide asset viewer page from a chrome context. */
 export declare function createAssetPageView<S extends Settings = Settings>(ctx: ChromeContext<S>): (props: AssetPageViewProps) => JSX.Element;

package/dist/asset-page/index.js

@@ -93,21 +93,21 @@ function AssetCodeBody({ asset, copyLabel, wrapLabel, truncatedLabel, linesLabel
 function EnlargeIcon() {
   return /* @__PURE__ */ jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { fill: "none", stroke: "currentColor", "stroke-linecap": "round", "stroke-linejoin": "round", "stroke-width": "2", d: "M8 3H3v5m13-5h5v5M8 21H3v-5m13 5h5v-5M3 8l6-6m12 6-6-6M3 16l6 6m12-6-6 6" }) });
 }
-function AssetImageStage({ asset, rawUrl }) {
+function AssetImageStage({ asset, rawUrl, labels }) {
   return /* @__PURE__ */ jsxs("section", { children: [
     /* @__PURE__ */ jsxs("div", { class: "mb-vsp-xs flex flex-wrap gap-hsp-sm text-caption", children: [
       /* @__PURE__ */ jsxs("div", { class: "flex rounded border border-muted", children: [
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "fit", class: "px-hsp-sm py-vsp-3xs", children: "Fit" }),
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "1to1", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: "1:1" })
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "fit", class: "px-hsp-sm py-vsp-3xs", children: labels.fit }),
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "1to1", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: labels.actualSize })
       ] }),
       /* @__PURE__ */ jsxs("div", { class: "flex rounded border border-muted", children: [
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "checker", class: "px-hsp-sm py-vsp-3xs", children: "Checker" }),
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "dark", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: "Dark" })
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "checker", class: "px-hsp-sm py-vsp-3xs", children: labels.checker }),
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "dark", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: labels.dark })
       ] })
     ] }),
     /* @__PURE__ */ jsxs("figure", { class: "zd-enlargeable zd-asset-stage is-checker flex min-h-[20rem] items-center justify-center overflow-auto rounded border border-muted bg-surface p-hsp-lg", children: [
       /* @__PURE__ */ jsx("img", { src: rawUrl, alt: asset.description ?? asset.name, width: asset.width, height: asset.height }),
-      /* @__PURE__ */ jsx("button", { type: "button", class: "zd-enlarge-btn", hidden: true, "aria-label": "Enlarge image", children: /* @__PURE__ */ jsx(EnlargeIcon, {}) })
+      /* @__PURE__ */ jsx("button", { type: "button", class: "zd-enlarge-btn", hidden: true, "aria-label": labels.enlarge, children: /* @__PURE__ */ jsx(EnlargeIcon, {}) })
     ] })
   ] });
 }
@@ -147,12 +147,12 @@ function AssetLinkedFrom({ asset, label }) {
     ] })) })
   ] });
 }
-function AssetDetails({ asset }) {
-  const rows = [["Type", asset.mime], ["Size", formatAssetBytes(asset.bytes)], ["Path", asset.path]];
-  if (asset.width !== void 0 && asset.height !== void 0) rows.splice(1, 0, ["Dimensions", `${asset.width} \xD7 ${asset.height}`]);
-  if (asset.updatedDate) rows.push(["Updated", asset.updatedDate]);
+function AssetDetails({ asset, labels }) {
+  const rows = [[labels.type, asset.mime], [labels.size, formatAssetBytes(asset.bytes)], [labels.path, asset.path]];
+  if (asset.width !== void 0 && asset.height !== void 0) rows.splice(1, 0, [labels.dimensions, `${asset.width} \xD7 ${asset.height}`]);
+  if (asset.updatedDate) rows.push([labels.updated, asset.updatedDate]);
   return /* @__PURE__ */ jsxs("section", { children: [
-    /* @__PURE__ */ jsx("h2", { class: "mb-vsp-xs text-title font-bold", children: "Details" }),
+    /* @__PURE__ */ jsx("h2", { class: "mb-vsp-xs text-title font-bold", children: labels.heading }),
     /* @__PURE__ */ jsx("dl", { class: "grid grid-cols-[auto_1fr] gap-x-hsp-md gap-y-vsp-2xs text-caption", children: rows.map(([term, value]) => /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx("dt", { class: "font-medium text-muted", children: term }),
       /* @__PURE__ */ jsx("dd", { class: "min-w-0 break-words text-fg", children: value })
@@ -171,53 +171,72 @@ function MediaLayout({ stage, details, linked }) {
 function createAssetPageView(ctx) {
   assertChromeContext(ctx, "createAssetPageView");
   const settings = ctx.settings;
-  const locale = ctx.defaultLocale;
   const t = ctx.t;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults, Breadcrumb: BreadcrumbWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const dataThemePack = resolveThemePackSsrSlug(ctx.themePackRegistry, settings);
-  return function AssetPageView({ entry: asset }) {
+  return function AssetPageView({ entry: asset, locale = ctx.defaultLocale }) {
+    const localeSegment = locale === ctx.defaultLocale ? void 0 : locale;
     const routePrefix = ctx.assetManifest?.routePrefix ?? settings.assetViewerRoutePrefix;
     const dir = ctx.assetManifest?.dir ?? settings.assetViewerDir;
-    const viewerUrl = assetViewerHref({ base: settings.base, routePrefix, path: asset.path });
+    const viewerUrl = assetViewerHref({ base: settings.base, routePrefix, path: asset.path, locale: localeSegment });
     const rawUrl = assetRawHref({ base: settings.base, dir, path: asset.path });
     const linesLabel = t("asset.lines", locale).replace(
       "{count}",
       String(asset.lines ?? 0)
     );
     const dirSegments = asset.dir.split("/").filter(Boolean);
-    const indexUrl = ctx.withBase(`/${routePrefix}/`);
+    const indexUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}${routePrefix}/`);
+    const homeUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}`);
+    const backLink = locale === ctx.defaultLocale ? asset.linkedFrom[0] : asset.linkedFrom.find((link) => link.locale === locale) ?? asset.linkedFrom[0];
     const breadcrumbItems = [
-      { label: "", href: ctx.withBase("/") },
+      { label: "", href: homeUrl },
       { label: t("asset.crumb", locale), ...settings.assetViewerIndex ? { href: indexUrl } : {} },
       ...dirSegments.map((label) => ({ label })),
       { label: asset.name }
     ];
     const linked = /* @__PURE__ */ jsx(AssetLinkedFrom, { asset, label: t("asset.linkedFrom", locale) });
-    const details = /* @__PURE__ */ jsx(AssetDetails, { asset });
+    const detailsLabels = {
+      heading: t("asset.details", locale),
+      type: t("asset.type", locale),
+      size: t("asset.size", locale),
+      path: t("asset.path", locale),
+      dimensions: t("asset.dimensions", locale),
+      updated: t("doc.updated", locale)
+    };
+    const imageStageLabels = {
+      fit: t("asset.fit", locale),
+      actualSize: t("asset.actualSize", locale),
+      checker: t("asset.checker", locale),
+      dark: t("asset.dark", locale),
+      enlarge: t("asset.enlarge", locale)
+    };
+    const details = /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels });
     const downloadPanel = /* @__PURE__ */ jsx(AssetDownloadPanel, { asset, rawUrl, noPreview: t("asset.noPreview", locale), downloadLabel: t("asset.download", locale), copyLabel: t("asset.copy", locale) });
     let body;
     const isMedia = asset.previewable && asset.sniffOk && ["image", "video", "pdf"].includes(asset.kind);
     if (!asset.previewable || !asset.sniffOk) body = /* @__PURE__ */ jsxs(Fragment, { children: [
       downloadPanel,
-      /* @__PURE__ */ jsx(AssetDetails, { asset }),
+      /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels }),
       linked
     ] });
-    else if (asset.kind === "image") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetImageStage, { asset, rawUrl }), details, linked });
+    else if (asset.kind === "image") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetImageStage, { asset, rawUrl, labels: imageStageLabels }), details, linked });
     else if (asset.kind === "video") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetVideoStage, { asset, rawUrl }), details, linked });
     else if (asset.kind === "pdf") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetPdfStage, { asset, rawUrl, children: downloadPanel }), details, linked });
     else body = /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(AssetCodeBody, { asset, copyLabel: t("asset.copy", locale), wrapLabel: t("asset.wrap", locale), truncatedLabel: t("asset.truncated", locale), linesLabel }),
-      /* @__PURE__ */ jsx(AssetDetails, { asset }),
+      /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels }),
       linked
     ] });
     const showSource = settings.bodyFootUtilArea !== false && settings.bodyFootUtilArea.viewSourceLink !== false;
     return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(asset.name), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: asset.name, description: asset.description, canonical: ctx.absoluteUrl(viewerUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: breadcrumbItems }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: viewerUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/", forceImageEnlarge: asset.kind === "image" && asset.previewable && asset.sniffOk }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { class: "zd-asset-page", "data-zd-asset-page": true, children: [
-      asset.linkedFrom[0] && /* @__PURE__ */ jsx("p", { class: "mb-vsp-xs text-caption", children: /* @__PURE__ */ jsxs("a", { href: asset.linkedFrom[0].href, class: "text-muted hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline", children: [
-        "\u2190 Back to ",
-        asset.linkedFrom[0].title
+      backLink && /* @__PURE__ */ jsx("p", { class: "mb-vsp-xs text-caption", children: /* @__PURE__ */ jsxs("a", { href: backLink.href, class: "text-muted hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline", children: [
+        "\u2190 ",
+        t("asset.backTo", locale),
+        " ",
+        backLink.title
       ] }) }),
       /* @__PURE__ */ jsx(AssetHeader, { asset, locale, badge: t("asset.badge", locale), updatedLabel: t("doc.updated", locale), linesLabel }),
       /* @__PURE__ */ jsx(AssetActions, { rawUrl, downloadLabel: t("asset.download", locale), openRawLabel: t("asset.openRaw", locale), copyLabel: t("asset.copy", locale), wrapLabel: t("asset.wrap", locale), code: !isMedia && asset.previewable && asset.sniffOk }),

package/dist/asset-path/index.d.ts

@@ -9,6 +9,8 @@ export interface AssetViewerHrefOptions {
     base: string;
     routePrefix: string;
     path: string;
+    /** Non-default locale segment. Omit for the unprefixed default locale. */
+    locale?: string;
     /** A fragment with or without its leading `#`. */
     fragment?: string;
 }

package/dist/asset-path/index.js

@@ -59,9 +59,10 @@ function decodeAuthoredHref(href, options) {
 }
 function assetViewerHref(options) {
   const routePrefix = normalizeSettingPath(options.routePrefix, "routePrefix");
+  const localePrefix = options.locale === void 0 ? "" : `/${encodeURIComponent(normalizeLocaleSegment(options.locale))}`;
   const href = withBase(
     options.base,
-    `/${routePrefix}/${encodeAssetPathForUrl(options.path)}/`
+    `${localePrefix}/${routePrefix}/${encodeAssetPathForUrl(options.path)}/`
   );
   if (options.fragment == null || options.fragment === "") return href;
   if (CONTROL_CHARS.test(options.fragment)) {
@@ -69,6 +70,15 @@ function assetViewerHref(options) {
   }
   return href + (options.fragment.startsWith("#") ? options.fragment : `#${options.fragment}`);
 }
+function normalizeLocaleSegment(locale) {
+  if (locale.length === 0 || locale.includes("/") || locale.includes("\\")) {
+    throw new Error("Asset viewer locale must be a non-empty URL segment");
+  }
+  if (locale === "." || locale === ".." || CONTROL_CHARS.test(locale)) {
+    throw new Error("Asset viewer locale must be a safe URL segment");
+  }
+  return locale.normalize("NFC");
+}
 function assetRawHref(options) {
   const dir = normalizeSettingPath(options.dir, "dir");
   return withBase(options.base, `/${dir}/${encodeAssetPathForUrl(options.path)}`);

package/dist/chrome/derive.js

@@ -314,12 +314,6 @@ function deriveMdxComponents(ctx) {
     t: (key, locale) => ctx.t(key, locale),
     versionedDocsUrl: ctx.versionedDocsUrl
   });
-  function HtmlPreviewBound(props) {
-    return HtmlPreviewWrapper({
-      globalConfig: ctx.settings.htmlPreview ?? null,
-      ...props
-    });
-  }
   const assetComponentContext = {
     base: ctx.settings.base,
     assetManifest: ctx.assetManifest,
@@ -329,8 +323,37 @@ function deriveMdxComponents(ctx) {
   function createMdxComponentsBound(lang = ctx.defaultLocale, currentVersion, currentSlug = "") {
     const localizedAssetContext = {
       ...assetComponentContext,
+      locale: lang === ctx.defaultLocale ? void 0 : lang,
+      isDefaultLocaleOnlyPath: ctx.isDefaultLocaleOnlyPath,
       t: (key) => ctx.t(key, lang)
     };
+    const localizedHtmlPreviewLabels = {
+      mobile: ctx.t("htmlPreview.viewport.mobile", lang),
+      tablet: ctx.t("htmlPreview.viewport.tablet", lang),
+      full: ctx.t("htmlPreview.viewport.full", lang),
+      viewportSize: ctx.t("htmlPreview.viewport.label", lang),
+      showCode: ctx.t("htmlPreview.source.show", lang),
+      hideCode: ctx.t("htmlPreview.source.hide", lang),
+      preview: ctx.t("htmlPreview.iframe.title", lang)
+    };
+    function HtmlPreviewBound(props) {
+      const labels = props.labels;
+      const effectiveLang = props.lang?.trim() ? props.lang : lang.trim() ? lang : "en";
+      return HtmlPreviewWrapper({
+        globalConfig: ctx.settings.htmlPreview ?? null,
+        ...props,
+        lang: effectiveLang,
+        labels: {
+          mobile: labels?.mobile ?? localizedHtmlPreviewLabels.mobile,
+          tablet: labels?.tablet ?? localizedHtmlPreviewLabels.tablet,
+          full: labels?.full ?? localizedHtmlPreviewLabels.full,
+          viewportSize: labels?.viewportSize ?? localizedHtmlPreviewLabels.viewportSize,
+          showCode: labels?.showCode ?? localizedHtmlPreviewLabels.showCode,
+          hideCode: labels?.hideCode ?? localizedHtmlPreviewLabels.hideCode,
+          preview: labels?.preview ?? localizedHtmlPreviewLabels.preview
+        }
+      });
+    }
     const mdxExtrasDefault = {
       Asset: createAssetCard(localizedAssetContext),
       AssetCode: createAssetCode(localizedAssetContext),
@@ -348,6 +371,8 @@ function deriveMdxComponents(ctx) {
     return createMdxComponents({
       settings: ctx.settings,
       assetManifest: ctx.assetManifest,
+      assetViewerLocale: lang === ctx.defaultLocale ? void 0 : lang,
+      isDefaultLocaleOnlyPath: ctx.isDefaultLocaleOnlyPath,
       locale: lang,
       currentVersion,
       currentSlug,

package/dist/compiled.css

@@ -658,6 +658,9 @@
 .min-h-\[20rem\] {
   min-height: 20rem;
 }
+.min-h-\[44px\] {
+  min-height: 44px;
+}
 .min-h-\[60vh\] {
   min-height: 60vh;
 }
@@ -754,6 +757,9 @@
 .w-icon-xs {
   width: var(--spacing-icon-xs);
 }
+.max-w-\[16rem\] {
+  max-width: 16rem;
+}
 .max-w-\[64rem\] {
   max-width: 64rem;
 }
@@ -772,6 +778,9 @@
 .max-w-\[calc\(100vw-2rem\)\] {
   max-width: calc(100vw - 2rem);
 }
+.max-w-\[calc\(100vw-var\(--spacing-hsp-xl\)\)\] {
+  max-width: calc(100vw - var(--spacing-hsp-xl));
+}
 .max-w-\[clamp\(50rem\,75vw\,90rem\)\] {
   max-width: clamp(50rem, 75vw, 90rem);
 }
@@ -793,6 +802,9 @@
 .min-w-\[10rem\] {
   min-width: 10rem;
 }
+.min-w-\[44px\] {
+  min-width: 44px;
+}
 .flex-1 {
   flex: 1;
 }

package/dist/content/content-link.d.ts

@@ -9,10 +9,14 @@ export interface CreateContentLinkOptions {
     assetManifest: AssetManifest | null;
     routePrefix: string;
     dir: string;
+    /** Non-default locale segment used by asset-viewer links. */
+    locale?: string;
+    /** Match viewer paths that intentionally remain default-locale-only. */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
 }
 /**
  * Bind ContentLink to an asset manifest. Only exact manifest entries are
  * decorated and redirected; every other anchor follows ContentLink verbatim.
  */
-export declare function createContentLink({ base, assetManifest, routePrefix, dir, }: CreateContentLinkOptions): (props: Props) => JSX.Element;
+export declare function createContentLink({ base, assetManifest, routePrefix, dir, locale, isDefaultLocaleOnlyPath, }: CreateContentLinkOptions): (props: Props) => JSX.Element;
 export {};

package/dist/content/content-link.js

@@ -24,7 +24,9 @@ function createContentLink({
   base,
   assetManifest,
   routePrefix,
-  dir
+  dir,
+  locale,
+  isDefaultLocaleOnlyPath
 }) {
   return function ManifestAwareContentLink(props) {
     const { href, className, children } = props;
@@ -43,6 +45,7 @@ function createContentLink({
           base,
           routePrefix,
           path: entry.path,
+          locale: isDefaultLocaleOnlyPath?.(`/${routePrefix}/${entry.path}`) ? void 0 : locale,
           fragment: decoded.fragment
         }),
         children: /* @__PURE__ */ jsxs("span", { className: "inline-flex items-baseline gap-x-hsp-xs font-mono", children: [

package/dist/factory-context/index.d.ts

@@ -27,8 +27,9 @@ export interface FactoryI18n {
     /** Display label for a locale (e.g. `"EN"`, `"日本語"`). */
     getLocaleLabel: (locale: string) => string;
     /**
-     * Translate a UI string key for a locale, falling back to the default locale
-     * then the key itself. Optional: factories that emit no UI strings omit it.
+     * Translate a UI string key for a locale, falling back through the configured
+     * default locale, package English, then the raw key. Optional: factories
+     * that emit no UI strings omit it.
      */
     t?: (key: string, locale?: string) => string;
 }
@@ -136,7 +137,10 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     } | undefined;
     /** Display label for a locale. */
     getLocaleLabel(locale: string): string;
-    /** Translate a UI string key for a locale (falls back to default then key). */
+    /**
+     * Translate a UI string key for a locale (falls back through the configured
+     * default locale, package English, then the raw key).
+     */
     t(key: string, locale?: string): string;
     /** The full URL-helper bag (also spread as own members via `extends`). */
     urlHelpers: UrlHelpers;

package/dist/header-with-defaults/index.js

@@ -120,6 +120,8 @@ function createHeaderWithDefaults(ctx) {
       LanguageSwitcher,
       {
         links: localeLinks,
+        accessibleLabel: t("language.switcher.label", lang),
+        idSuffix: "header",
         config: {
           base: settings.base.replace(/\/+$/, ""),
           defaultLocale,