blume 2.0.2 → 2.1.0

package/src/core/frontmatter.ts

@@ -19,13 +19,18 @@ type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 /** Front matter data as gray-matter types it (`GrayMatterFile["data"]`). */
 type FrontMatterData = ReturnType<typeof baseMatter>["data"];
 
+/** A YAML load result: a mapping (or list) Astro keeps as front matter data. */
+const isYamlCollection = (
+  value: ReturnType<typeof load>
+): value is FrontMatterData => typeof value === "object" && value !== null;
+
 const yamlEngine = {
-  // SAFETY: gray-matter's engine contract expects an object; a front matter
-  // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
-  // input, which gray-matter treats the same way its bundled engine's output
-  // is treated.
-  parse: (input: string): object =>
-    (load(input, { schema: YAML_SCHEMA }) ?? {}) as object,
+  // A block that loads to a scalar (`title` alone, or prose between two
+  // `---` lines) is no metadata: Astro reads it as `{}`, and so does Blume.
+  parse: (input: string): FrontMatterData => {
+    const value = load(input, { schema: YAML_SCHEMA });
+    return isYamlCollection(value) ? value : {};
+  },
   stringify: (data: FrontMatterData): string => dump(data),
 };
 
@@ -45,23 +50,21 @@ const withYamlEngine = <O extends { engines?: object } | undefined>(
 
 /**
  * True when a document's leading `---` line is a CommonMark thematic break,
- * not a front matter fence. Two shapes qualify (mirroring
- * `linesWithoutFrontMatter` in `sources/normalize.ts`):
- *   - the next line is blank (or absent) — YAML metadata starts on the very
- *     next line, so a gap means the body *opens* with a divider (e.g. a
- *     Notion page whose first block is one);
- *   - no closing `---` line follows — gray-matter would swallow the whole
- *     document as one unclosed YAML block and hand it to js-yaml, which
- *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ * not a front matter fence: no closing `---` line follows. Astro's own front
+ * matter match requires that close too, while gray-matter would swallow the
+ * whole document as one unclosed YAML block and hand it to js-yaml, which
+ * crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ *
+ * A blank line after the opening `---` is still front matter: Astro strips
+ * the block from the page either way, so reading it as a divider here would
+ * ignore its `draft`, `slug`, and `hidden` while its YAML leaked into search
+ * and llms.txt.
  */
 const opensWithThematicBreak = (input: string): boolean => {
-  const [first = "", second] = input.split(/\r?\n/u, 2);
+  const [first = ""] = input.split(/\r?\n/u, 1);
   if (!/^-{3}\s*$/u.test(first)) {
     return false;
   }
-  if (second === undefined || second.trim() === "") {
-    return true;
-  }
   // gray-matter closes the block at the next line-leading `---`; matching its
   // search exactly keeps this guard from firing on any document it parses.
   return !input.includes("\n---", 1);

package/src/core/graph.ts

@@ -4,6 +4,7 @@ import {
   localizeRoute,
   resolveFallbackLocale,
 } from "./i18n.ts";
+import { resolveLocalizable } from "./localizable.ts";
 import {
   validateNavIcons,
   validateNavStructure,
@@ -97,31 +98,6 @@ const localePagesFor = (
   return [...real, ...filled];
 };
 
-/**
- * Resolve a possibly-per-locale header label to the string a locale renders:
- * the active locale's entry, else the default locale's, else the map's first
- * entry (which is also what a single-locale site gets).
- */
-/** A label is either one string for every locale or a per-locale map. */
-const isSingleLabel = (label: LocalizableLabel): label is string =>
-  typeof label === "string";
-
-const resolveLabel = (
-  label: LocalizableLabel,
-  locale: string,
-  defaultLocale?: string
-): string => {
-  if (isSingleLabel(label)) {
-    return label;
-  }
-  return (
-    label[locale] ??
-    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
-    Object.values(label)[0] ??
-    ""
-  );
-};
-
 /**
  * An explicit sidebar with every item's `href` passed through `localize` (page
  * refs and `root`s resolve against each locale's own pages already).
@@ -154,11 +130,36 @@ const resolveTabLabels = (
     ...tab,
     items: tab.items?.map((item) => ({
       ...item,
-      label: resolveLabel(item.label, locale, defaultLocale),
+      label: resolveLocalizable(item.label, locale, defaultLocale),
     })),
-    label: resolveLabel(tab.label, locale, defaultLocale),
+    label: resolveLocalizable(tab.label, locale, defaultLocale),
   }));
 
+/** A configured header or footer link with its label resolved for a locale. */
+const withLabel = <T extends { label: LocalizableLabel }>(
+  link: T,
+  locale: string,
+  defaultLocale?: string
+): Omit<T, "label"> & { label: string } => ({
+  ...link,
+  label: resolveLocalizable(link.label, locale, defaultLocale),
+});
+
+/** The configured header links (plain, call to action, featured) in `locale`. */
+const resolveHeaderLinks = (
+  navigation: BuildContentGraphOptions["navigation"],
+  locale: string,
+  defaultLocale?: string
+) => ({
+  actions: navigation.actions.map((link) =>
+    withLabel(link, locale, defaultLocale)
+  ),
+  cta: navigation.cta ? withLabel(navigation.cta, locale, defaultLocale) : null,
+  featured: navigation.featured.map((link) =>
+    withLabel(link, locale, defaultLocale)
+  ),
+});
+
 /**
  * Mount a configured link authored as if the site were served at root (the
  * banner's): under `basePath`, except a route served outside the content tree
@@ -274,18 +275,22 @@ const buildLocaleNavigation = (
     ...item,
     href: localizeServed(item.href, false),
   });
-  const { actions, cta, featured } = options.navigation;
+  const { actions, cta, featured } = resolveHeaderLinks(
+    options.navigation,
+    code,
+    i18n.defaultLocale
+  );
   const sidebarItems = options.navigation.sidebar.items;
 
   const navigation = buildNavigation(localePages, {
-    actions: actions?.map(localizeHref),
+    actions: actions.map(localizeHref),
     basePath,
     cta: cta ? localizeHref(cta) : null,
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
     fallbackMetaPrefix,
-    featured: featured?.map(localizeHref),
+    featured: featured.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
     // "/fr/v1.0" inside a snapshot): the tab pointing here spans the whole
@@ -415,13 +420,11 @@ const buildVersionNavigation = (
   }
   return {
     "": buildNavigation(versionPages, {
-      actions: options.navigation.actions,
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       localizedRoot: versionizeRoute("/", id),
       metaPrefix: id,
@@ -465,13 +468,13 @@ export const buildContentGraph = (
     ));
   } else {
     navigation = buildNavigation(currentPages, {
-      actions: options.navigation.actions,
+      // No locale to prefer: a per-locale label map resolves to its first
+      // entry on a single-locale site.
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,

package/src/core/heading-markers.ts

@@ -55,17 +55,12 @@ export interface HeadingMarkers {
  * the heading count (mid-text brackets are ordinary prose); when a marker kind
  * repeats, the last one written wins.
  *
- * `isRefDefined` reports whether a link-reference definition exists for a
- * bracket's label (`toc`, `!toc`, `#id`): a defined bracket is a CommonMark
- * shortcut link, not a marker — the renderer sees a resolved `<a>` element
- * there and strips nothing at or before it, so the parse stops the same way.
- * The render-time hast plugin never passes it (resolved links are already
- * elements by the time it runs); the raw-source scanner does.
+ * Callers pass the heading's trailing text node after a Markdown parse, so a
+ * bracket that a link-reference definition turns into a CommonMark shortcut
+ * link (`[toc]` with a `[toc]: …` definition) is already an element there and
+ * never reaches this parse.
  */
-export const parseHeadingMarkers = (
-  text: string,
-  isRefDefined?: (label: string) => boolean
-): HeadingMarkers => {
+export const parseHeadingMarkers = (text: string): HeadingMarkers => {
   let remaining = text;
   let id: string | undefined;
   let toc: HeadingMarkers["toc"];
@@ -75,14 +70,6 @@ export const parseHeadingMarkers = (
     match = MARKER.exec(remaining)
   ) {
     const explicitId = match.groups.curlyId ?? match.groups.id;
-    const label =
-      explicitId === undefined
-        ? `${match.groups.hide ?? ""}toc`
-        : `#${explicitId}`;
-    // A `{#id}` is never a shortcut link, whatever the definitions say.
-    if (match.groups.curlyId === undefined && isRefDefined?.(label)) {
-      break;
-    }
     remaining = remaining.slice(0, match.index);
     if (explicitId === undefined) {
       // Stripping runs right-to-left, so keeping the first capture of each

package/src/core/i18n-ui.ts

@@ -15,6 +15,8 @@ const uiStringsObject = z.object({
     .object({
       addToCursor: z.string().default("Add to Cursor"),
       addToVscode: z.string().default("Add to VS Code"),
+      // A code block's button that opens the assistant with the code attached.
+      askAboutCode: z.string().default("Ask about this code"),
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
@@ -47,11 +49,32 @@ const uiStringsObject = z.object({
       copy: z.string().default("Copy conversation"),
       empty: z.string().default("Ask a question about the docs."),
       error: z.string().default("Sorry, something went wrong."),
+      // The question sent about an attached code block when the reader
+      // writes none.
+      explainCode: z.string().default("Explain this code."),
       label: z.string().default("Ask a question"),
+      // The header trigger's tooltip.
+      open: z.string().default("Open assistant"),
       placeholder: z.string().default("Ask a question…"),
+      // The answer when the rate limit (`rateLimit`) turns a question away.
+      rateLimited: z
+        .string()
+        .default(
+          "You've asked a lot of questions. Try again in a few minutes."
+        ),
+      // The attached code block's dismiss button.
+      removeCode: z.string().default("Remove code"),
       send: z.string().default("Send"),
+      // The link to your support channel (`ai.assistant.support`), and the
+      // subject of an email it starts.
+      support: z.string().default("Contact support"),
+      supportSubject: z.string().default("Question from the docs"),
       tip: z.string().default("Tip: You can open and close chat with"),
       title: z.string().default("Assistant"),
+      // The answer when the bot check (`ai.assistant.captcha`) fails.
+      verifyFailed: z
+        .string()
+        .default("We couldn't check that you're human. Try again."),
       you: z.string().default("You"),
     })
     .prefault({}),
@@ -70,6 +93,23 @@ const uiStringsObject = z.object({
       title: z.string().default("Changelog"),
     })
     .prefault({}),
+  // The built-in cookie consent banner (`consent: native()`) and the footer
+  // link that reopens a consent manager's preferences.
+  consent: z
+    .object({
+      accept: z.string().default("Accept"),
+      decline: z.string().default("Decline"),
+      // The banner's accessible name.
+      label: z.string().default("Cookie consent"),
+      message: z
+        .string()
+        .default(
+          "We'd like to use cookies to understand how these docs are used."
+        ),
+      policy: z.string().default("Privacy policy"),
+      settings: z.string().default("Cookie settings"),
+    })
+    .prefault({}),
   content: z
     .object({
       // `<Component>`'s source tab.
@@ -89,7 +129,12 @@ const uiStringsObject = z.object({
       prop: z.string().default("Prop"),
       // `<Tabs dropdown>`: the accessible name of the tab picker.
       selectTab: z.string().default("Select tab"),
-      // `<Expandable>`'s toggle when it sets no `title`.
+      // `<View>`: the accessible name of the page's view picker.
+      selectView: z.string().default("Select view"),
+      // An expanded `expandable` code block's toggle.
+      showLess: z.string().default("Show less"),
+      // `<Expandable>`'s toggle when it sets no `title`, and a collapsed
+      // `expandable` code block's.
       showMore: z.string().default("Show more"),
       stars: z.string().default("Stars"),
       // An untitled tab's label; `{n}` is replaced with its position.
@@ -102,8 +147,11 @@ const uiStringsObject = z.object({
     .prefault({}),
   feedback: z
     .object({
+      // The written comment box after the rating (`feedback.comments`).
+      comment: z.string().default("Tell us more (optional)"),
       no: z.string().default("No"),
       question: z.string().default("Was this page helpful?"),
+      send: z.string().default("Send"),
       thanks: z.string().default("Thanks for your feedback!"),
       yes: z.string().default("Yes"),
     })
@@ -114,6 +162,36 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .prefault({}),
+  narration: z
+    .object({
+      // Spoken, not shown: the cues that introduce a callout of each type, a
+      // step (`{n}` is its number), a tab (`{title}` is its label), and a
+      // collapsible section. End each with a full stop so it reads as its own
+      // sentence.
+      cueDanger: z.string().default("Danger."),
+      cueInfo: z.string().default("Info."),
+      cueNote: z.string().default("Note."),
+      cueSection: z.string().default("Expandable section."),
+      cueStep: z.string().default("Step {n}."),
+      cueSuccess: z.string().default("Success."),
+      cueTab: z.string().default("{title} tab."),
+      cueTip: z.string().default("Tip."),
+      cueWarning: z.string().default("Warning."),
+      error: z.string().default("The narration couldn't load."),
+      // Resumes following the sentence being read after the reader scrolls away.
+      follow: z.string().default("Follow along"),
+      label: z.string().default("Listen to this page"),
+      // The estimated listening time; `{n}` is whole minutes.
+      minutes: z.string().default("{n} min"),
+      next: z.string().default("Next sentence"),
+      pause: z.string().default("Pause"),
+      play: z.string().default("Play"),
+      previous: z.string().default("Previous sentence"),
+      progress: z.string().default("Narration progress"),
+      speed: z.string().default("Playback speed"),
+      stop: z.string().default("Stop listening"),
+    })
+    .prefault({}),
   nav: z
     .object({
       back: z.string().default("Back"),
@@ -128,7 +206,7 @@ const uiStringsObject = z.object({
       primary: z.string().default("Primary"),
       sections: z.string().default("Sections"),
       toggleNavigation: z.string().default("Toggle navigation"),
-      toggleTheme: z.string().default("Toggle color theme"),
+      toggleTheme: z.string().default("Toggle theme"),
     })
     .prefault({}),
   notFound: z
@@ -154,6 +232,8 @@ const uiStringsObject = z.object({
       next: z.string().default("Next"),
       pagination: z.string().default("Pagination"),
       previous: z.string().default("Previous"),
+      // The heading over a page's `related` links.
+      related: z.string().default("Related pages"),
       skipToContent: z.string().default("Skip to content"),
     })
     .prefault({}),

package/src/core/i18n.ts

@@ -219,11 +219,31 @@ export const localeTargetPath = (
   return `${folder}/${rel}`;
 };
 
+/**
+ * The warning for a top-level folder named after the default locale
+ * (`docs/en/` when `defaultLocale` is `en`). Only non-default codes are
+ * locale folders — the default locale lives at the content root — so the
+ * folder is ordinary default-locale content, published one level down at
+ * `/en/…` (`/en/en/…` with the default prefix shown) and filled into every
+ * other locale at `/fr/en/…`.
+ */
+const defaultLocaleFolderDiagnostic = (
+  folder: string,
+  i18n: ResolvedI18nConfig
+): Diagnostic => ({
+  code: "BLUME_I18N_DEFAULT_LOCALE_FOLDER",
+  message: `Folder "${folder}/" is named after the default locale, but "${i18n.defaultLocale}" pages live at the content root — its pages publish at ${localizeRoute(`/${folder}`, i18n.defaultLocale, i18n)}/… instead.`,
+  severity: "warning",
+  suggestion: `Move the contents of "${folder}/" up to the content root; only the other locales get a folder.`,
+});
+
 /**
  * Warn about top-level content folders that look like a locale (a code Blume
  * recognizes) but aren't declared in `i18n.locales`. Without this they're
  * silently treated as default-locale content under a `/<code>/…` route, which
  * is almost never intended — usually a translation that wasn't registered.
+ * A folder named after the default locale gets the same treatment (see
+ * {@link defaultLocaleFolderDiagnostic}).
  */
 export const i18nDiagnostics = (
   pages: PageRecord[],
@@ -242,9 +262,17 @@ export const i18nDiagnostics = (
     // Inside a version snapshot the locale dir sits one level deeper
     // (`v1.0/fr/guide.md`), so a configured version segment is skipped first.
     const parts = page.source.ref.split("/");
-    const first = (
-      parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0]
-    )?.toLowerCase();
+    const folder = parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0];
+    const first = folder?.toLowerCase();
+    if (
+      folder !== undefined &&
+      first === i18n.defaultLocale.toLowerCase() &&
+      !seen.has(first)
+    ) {
+      seen.add(first);
+      diagnostics.push(defaultLocaleFolderDiagnostic(folder, i18n));
+      continue;
+    }
     if (
       first &&
       !seen.has(first) &&

package/src/core/includes.ts

@@ -7,6 +7,7 @@ import type { FenceState } from "./code-fences.ts";
 import matter from "./frontmatter.ts";
 import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
+import { substituteVariables } from "./variables.ts";
 
 /**
  * Content includes: `<include>./relative.mdx</include>` on a line of its own
@@ -98,6 +99,12 @@ export interface IncludeAttributes {
   lang?: string;
   /** Fence meta string in code-block mode (e.g. `title="lib.ts"`). */
   meta?: string;
+  /**
+   * Every other attribute with a value: the snippet's own variables.
+   * `<include plan="Pro">` makes `{{plan}}` in the included file read `Pro`,
+   * ahead of any site-wide variable of the same name.
+   */
+  props?: Record<string, string>;
 }
 
 /** A parsed include statement. */
@@ -108,8 +115,8 @@ export interface IncludeStatement {
 
 /**
  * Parse one trimmed line as an include statement, or `null` when it isn't
- * one. Only `lang` and `meta` are meaningful; unknown attributes parse and
- * are ignored so a future attribute degrades gracefully on older versions.
+ * one. `lang` and `meta` shape a code include; every other attribute with a
+ * value becomes a prop, a variable scoped to the included file.
  */
 export const parseIncludeStatement = (
   line: string
@@ -128,6 +135,9 @@ export const parseIncludeStatement = (
     if (name === "meta" && value) {
       attributes.meta = value;
     }
+    if (name && name !== "lang" && name !== "meta" && value !== undefined) {
+      attributes.props = { ...attributes.props, [name]: value };
+    }
   }
   return { attributes, target: match.groups.target ?? "" };
 };
@@ -519,8 +529,15 @@ const expandStatement = async (
     lines.shift();
     origins.shift();
   }
+  // Props replace their `{{name}}` references line by line, so every line
+  // keeps its origin; they reach the file's own nested includes too.
+  const { props } = statement.attributes;
   return {
-    lines: rebaseImages(lines, dirname(path), dirname(filePath)),
+    lines: rebaseImages(
+      props ? lines.map((text) => substituteVariables(text, props)) : lines,
+      dirname(path),
+      dirname(filePath)
+    ),
     origins,
   };
 };

package/src/core/last-modified.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 
-import { relative } from "pathe";
+import { normalize, relative } from "pathe";
 
 import type { Diagnostic } from "./types.ts";
 
@@ -58,6 +59,23 @@ export const parseGitLog = (output: string): Map<string, string> => {
   return times;
 };
 
+/**
+ * `path` with every symlink resolved, the spelling git prints paths in: a
+ * project opened through a link (`/tmp/site` on macOS, where `/tmp` links to
+ * `/private/tmp`) gets `/private/tmp/site` from `rev-parse --show-toplevel`,
+ * so the project's own spelling would compare as outside the repository and
+ * every page would go undated. The native realpath also expands a Windows
+ * 8.3 short name (`RUNNER~1`), which git does too. A path that doesn't exist
+ * stays as written.
+ */
+export const realPath = (path: string): string => {
+  try {
+    return normalize(realpathSync.native(path));
+  } catch {
+    return path;
+  }
+};
+
 /**
  * The toplevel of the repository containing `root`, or null when git is
  * unavailable or the project isn't a repo. Callers use it to decide which
@@ -108,6 +126,10 @@ export const gitLastModifiedTimes = (
   if (gitRoot === null) {
     return new Map();
   }
+  // Git names paths by their real location, so the pathspecs and the paths
+  // read back against the log are compared in that spelling too (see
+  // `realPath`).
+  const top = realPath(gitRoot);
   try {
     const output = execFileSync(
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
@@ -121,14 +143,14 @@ export const gitLastModifiedTimes = (
         "--format=%x00%cI",
         "--name-only",
         "--",
-        ...contentRoots,
+        ...contentRoots.map(realPath),
       ],
       { encoding: "utf-8", env: gitEnv(), maxBuffer: 256 * 1024 * 1024 }
     );
     const byRepoPath = parseGitLog(output);
     const result = new Map<string, string>();
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative(top, realPath(sourcePath)));
       if (iso) {
         result.set(sourcePath, iso);
       }

package/src/core/links.ts

@@ -10,6 +10,7 @@ import {
 import type { LocaleRouting } from "./i18n.ts";
 import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
+import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -87,6 +88,8 @@ interface LinkContext {
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
+  /** Pattern `redirect.from`s (`/beta/:slug*`), based like `redirects`. */
+  redirectPatterns: string[];
   routes: Set<string>;
 }
 
@@ -322,10 +325,16 @@ const checkPathLink = (
   if (ctx.extraRoutes.has(route)) {
     return null;
   }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // A configured `redirect.from`, or a path a pattern `from` covers, resolves
+  // at runtime, so it's a valid target.
   // Its destination (and any anchor there) is validated on its own page, so we
   // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
+  if (
+    ctx.redirects.has(route) ||
+    ctx.redirectPatterns.some(
+      (from) => pathsUnderPattern(from, [route]).length > 0
+    )
+  ) {
     return null;
   }
 
@@ -585,6 +594,11 @@ export const validateLinks = async (
     fileRoutes: buildFileRouteIndex(graph.pages, options.i18n ?? null),
     i18n: options.i18n ?? null,
     publicDir: options.publicDir,
+    redirectPatterns: (options.redirects ?? []).flatMap((redirect) =>
+      isPatternPath(redirect.from)
+        ? [withBasePath(basePath, redirect.from)]
+        : []
+    ),
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>
         toRoute(withBasePath(basePath, redirect.from))

package/src/core/locale-links.ts

@@ -1,5 +1,6 @@
 import {
   isInternalPath,
+  mountBasePath,
   normalizePath,
   stripBasePath,
   withBasePath,
@@ -120,7 +121,10 @@ export const localizeHref = (
   if (localized === based) {
     return href;
   }
-  return `${withBasePath(options.deployBase, localized)}${suffix}`;
+  // The base came off above, so it goes back on unconditionally: a localized
+  // path that starts with the base's own name (`/ja/…` under base `/ja`) is
+  // still served under it.
+  return `${mountBasePath(options.deployBase, localized)}${suffix}`;
 };
 
 /** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */

package/src/core/localizable.ts

@@ -0,0 +1,26 @@
+import type { LocalizableLabel } from "./schema.ts";
+
+/** A label is either one string for every locale or a per-locale map. */
+const isSingleLabel = (label: LocalizableLabel): label is string =>
+  typeof label === "string";
+
+/**
+ * Resolve a possibly-per-locale label to the string a locale renders: the
+ * active locale's entry, else the default locale's, else the map's first
+ * entry (which is also what a single-locale site gets).
+ */
+export const resolveLocalizable = (
+  label: LocalizableLabel,
+  locale?: string,
+  defaultLocale?: string
+): string => {
+  if (isSingleLabel(label)) {
+    return label;
+  }
+  return (
+    (locale === undefined ? undefined : label[locale]) ??
+    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
+    Object.values(label)[0] ??
+    ""
+  );
+};