blume 2.0.0 → 2.0.2

package/src/core/diagnostics.ts

@@ -98,50 +98,237 @@ const isKeySegment = (segment: string | number): segment is string =>
   typeof segment === "string";
 
 /**
- * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`) in
- * the raw config / frontmatter text. Narrows key-by-key — finding each string
- * segment as a `key:`/`key =` at or after the previous match — so a nested key
- * lands under its parent. Array indices are skipped. Returns 1-based line/column,
- * or undefined when nothing matches.
+ * Where a located value's children are searched. `object` and `array` are the
+ * inside of a `{…}`/`[…]` literal, searched entry by entry so a key or an index
+ * only matches a direct child. `block` has no brackets — the whole file at the
+ * top, or a YAML key's indented lines — and is searched at any depth.
  */
-const stepSegment = (
+interface Scope {
+  end: number;
+  /** A literal's direct entries (keys or elements), in source order. */
+  entries: number[];
+  kind: "array" | "block" | "object";
+  start: number;
+}
+
+/** A located key or element: where it starts, and where its value starts. */
+interface Step {
+  index: number;
+  next: number;
+}
+
+const QUOTES = new Set(['"', "'", "`"]);
+const OPENERS = new Set(["(", "[", "{"]);
+const CLOSERS = new Set([")", "]", "}"]);
+const WHITESPACE = /\s/u;
+
+/**
+ * The index just past a comment starting at `index`, or `index` when none does.
+ * A `//` after a `:` is a URL scheme in YAML (`href: https://…`), not a comment.
+ */
+const skipComment = (source: string, index: number): number => {
+  if (source.startsWith("//", index) && source.charAt(index - 1) !== ":") {
+    const end = source.indexOf("\n", index);
+    return end === -1 ? source.length : end;
+  }
+  if (source.startsWith("/*", index)) {
+    const end = source.indexOf("*/", index + 2);
+    return end === -1 ? source.length : end + 2;
+  }
+  return index;
+};
+
+/**
+ * The index just past a string literal starting at `index`, or `index` when
+ * none does. A `'`/`"` that doesn't close on its own line is an apostrophe in
+ * plain YAML text, not a string.
+ */
+const skipString = (source: string, index: number): number => {
+  const quote = source.charAt(index);
+  if (!QUOTES.has(quote)) {
+    return index;
+  }
+  let cursor = index + 1;
+  while (cursor < source.length) {
+    const char = source.charAt(cursor);
+    if (char === quote) {
+      return cursor + 1;
+    }
+    if (char === "\n" && quote !== "`") {
+      return index;
+    }
+    cursor += char === "\\" ? 2 : 1;
+  }
+  return index;
+};
+
+/** Where a literal closes, and where each of its direct entries starts. */
+interface LiteralScan {
+  end: number;
+  entries: number[];
+}
+
+/**
+ * Walk the `{…}`/`[…]` literal opened at `open`: where each direct entry starts
+ * (a key, or an array element) and where the literal closes. Nested brackets,
+ * strings, and comments are stepped over, so only the literal's own commas
+ * separate its entries.
+ */
+const scanLiteral = (source: string, open: number): LiteralScan => {
+  const entries: number[] = [];
+  let depth = 0;
+  let pending = true;
+  let index = open + 1;
+  while (index < source.length) {
+    const afterComment = skipComment(source, index);
+    const char = source.charAt(index);
+    if (afterComment !== index || WHITESPACE.test(char)) {
+      index = Math.max(afterComment, index + 1);
+      continue;
+    }
+    if (depth === 0 && CLOSERS.has(char)) {
+      return { end: index, entries };
+    }
+    if (depth === 0 && pending) {
+      entries.push(index);
+      pending = false;
+    }
+    const afterString = skipString(source, index);
+    if (afterString !== index) {
+      index = afterString;
+      continue;
+    }
+    if (OPENERS.has(char)) {
+      depth += 1;
+    } else if (CLOSERS.has(char)) {
+      depth -= 1;
+    } else if (char === "," && depth === 0) {
+      pending = true;
+    }
+    index += 1;
+  }
+  return { end: source.length, entries };
+};
+
+/**
+ * The lines indented deeper than the key at `anchor` — a YAML mapping's
+ * children — up to the first line that isn't, or `limit`.
+ */
+const indentedBlock = (
   source: string,
-  segment: string | number,
-  cursor: number
-) => {
-  // A non-string path segment (array index) is skipped without moving on.
-  if (!isKeySegment(segment)) {
-    return { index: -1, next: cursor, stop: false };
+  anchor: number,
+  limit: number
+): Scope => {
+  const column = anchor - (source.lastIndexOf("\n", anchor - 1) + 1);
+  const lineEnd = source.indexOf("\n", anchor);
+  const start = lineEnd === -1 ? limit : Math.min(lineEnd + 1, limit);
+  let end = start;
+  while (end < limit) {
+    const next = source.indexOf("\n", end);
+    const after = next === -1 || next >= limit ? limit : next + 1;
+    const line = source.slice(end, after);
+    if (line.trim() !== "" && line.length - line.trimStart().length <= column) {
+      break;
+    }
+    end = after;
   }
-  // The negative lookbehind keeps a segment like `title` from matching the
-  // tail of an unrelated key such as `subtitle:`.
-  const matcher = new RegExp(
-    `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
-    "gu"
-  );
-  matcher.lastIndex = cursor;
-  const match = matcher.exec(source);
-  if (!match) {
-    return { index: -1, next: cursor, stop: true };
+  return { end, entries: [], kind: "block", start };
+};
+
+/** A value's lead-in before its literal: spaces, or an adapter call's `vercel(`. */
+const VALUE_LEAD = /[\s\w$.(]*/uy;
+
+/**
+ * The scope holding the children of the key or element at `anchor`, whose
+ * value starts at `from`. A `{…}`/`[…]` literal — written directly, or as the
+ * first argument of a call like `vercel({…})` — is walked entry by entry;
+ * anything else falls back to the lines indented under `anchor` (YAML's
+ * nesting), within the enclosing scope's `limit`.
+ */
+const valueScope = (source: string, step: Step, limit: number): Scope => {
+  VALUE_LEAD.lastIndex = step.next;
+  VALUE_LEAD.exec(source);
+  const open = VALUE_LEAD.lastIndex;
+  const char = source.charAt(open);
+  if (open < limit && (char === "{" || char === "[")) {
+    const literal = scanLiteral(source, open);
+    return {
+      end: literal.end,
+      entries: literal.entries,
+      kind: char === "{" ? "object" : "array",
+      start: open,
+    };
   }
-  return { index: match.index, next: matcher.lastIndex, stop: false };
+  return indentedBlock(source, step.index, limit);
 };
 
+/**
+ * Find `segment` as a `key:`/`key =` (bare or quoted) in `scope`: among an
+ * object literal's own entries, or anywhere in a block. The negative lookbehind
+ * keeps `title` from matching the tail of an unrelated key such as `subtitle:`.
+ */
+const findKey = (
+  source: string,
+  scope: Scope,
+  segment: string
+): Step | undefined => {
+  const key = escapeRegExp(segment);
+  const pattern = `(?<![\\w$])(?:${key}|"${key}"|'${key}')\\s*[:=]`;
+  if (scope.kind === "block") {
+    const matcher = new RegExp(pattern, "gu");
+    matcher.lastIndex = scope.start;
+    const match = matcher.exec(source);
+    return match && match.index < scope.end
+      ? { index: match.index, next: matcher.lastIndex }
+      : undefined;
+  }
+  // Sticky: the key must start exactly where the entry does.
+  const matcher = new RegExp(pattern, "uy");
+  for (const entry of scope.kind === "object" ? scope.entries : []) {
+    matcher.lastIndex = entry;
+    if (matcher.test(source)) {
+      return { index: entry, next: matcher.lastIndex };
+    }
+  }
+  return undefined;
+};
+
+/** The element at `position` of an array literal; a block can't be indexed. */
+const findElement = (scope: Scope, position: number): Step | undefined => {
+  const index = scope.kind === "array" ? scope.entries[position] : undefined;
+  return index === undefined ? undefined : { index, next: index };
+};
+
+/**
+ * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`,
+ * `["redirects", 2, "status"]`) in the raw config / frontmatter text. Narrows
+ * segment by segment: a key is found among its parent's own entries (or, where
+ * there are no brackets, in the parent's indented lines), an index picks that
+ * element of an array literal. A segment that isn't there — a missing key —
+ * stops the walk at its parent, so the position never escapes into a sibling.
+ * Returns 1-based line/column, or undefined when not even the first segment
+ * matches.
+ */
 const locatePath = (
   source: string,
   path: readonly (string | number)[]
 ): { column: number; line: number } | undefined => {
-  let cursor = 0;
+  let scope: Scope = {
+    end: source.length,
+    entries: [],
+    kind: "block",
+    start: 0,
+  };
   let found = -1;
   for (const segment of path) {
-    const step = stepSegment(source, segment, cursor);
-    if (step.stop) {
+    const step = isKeySegment(segment)
+      ? findKey(source, scope, segment)
+      : findElement(scope, segment);
+    if (!step) {
       break;
     }
-    cursor = step.next;
-    if (step.index >= 0) {
-      found = step.index;
-    }
+    found = step.index;
+    scope = valueScope(source, step, scope.end);
   }
   if (found < 0) {
     return;

package/src/core/graph.ts

@@ -1,17 +1,22 @@
-import { withBasePath } from "./base-path.ts";
+import { mountBasePath, withBasePath } from "./base-path.ts";
 import {
   localizeInternalPath,
   localizeRoute,
   resolveFallbackLocale,
 } from "./i18n.ts";
-import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
-import { buildNavigation } from "./navigation.ts";
+import {
+  validateNavIcons,
+  validateNavStructure,
+  validateSidebarItems,
+} from "./nav-diagnostics.ts";
+import { buildNavigation, isPageRef, pagesByRef } from "./navigation.ts";
 import type {
   FolderMeta,
   LocalizableLabel,
   ResolvedConfig,
   ResolvedI18nConfig,
   ResolvedVersionsConfig,
+  SidebarItemConfig,
 } from "./schema.ts";
 import type {
   ContentGraph,
@@ -23,6 +28,8 @@ import type {
 import { versionizeRoute } from "./versions.ts";
 
 interface BuildContentGraphOptions {
+  /** The banner's link target as configured (`banner.link.href`), if any. */
+  bannerHref?: string;
   /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
   basePath?: string;
   /** The header brand link as configured (`logo.href`, default `/`). */
@@ -83,7 +90,7 @@ const localePagesFor = (
         ...source,
         fallback: true,
         locale: code,
-        route: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        route: mountBasePath(basePath, localizeRoute(key, code, i18n)),
       });
     }
   }
@@ -115,6 +122,28 @@ const resolveLabel = (
   );
 };
 
+/**
+ * An explicit sidebar with every item's `href` passed through `localize` (page
+ * refs and `root`s resolve against each locale's own pages already).
+ */
+const localizeSidebarHrefs = (
+  items: SidebarItemConfig[],
+  localize: (href: string) => string
+): SidebarItemConfig[] =>
+  items.map((item) => {
+    if (isPageRef(item)) {
+      return item;
+    }
+    const localized = { ...item };
+    if (item.href !== undefined) {
+      localized.href = localize(item.href);
+    }
+    if (item.items) {
+      localized.items = localizeSidebarHrefs(item.items, localize);
+    }
+    return localized;
+  });
+
 /** Resolve every localizable label in the configured tabs for one locale. */
 const resolveTabLabels = (
   tabs: BuildContentGraphOptions["navigation"]["tabs"],
@@ -130,6 +159,18 @@ const resolveTabLabels = (
     label: resolveLabel(tab.label, 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
+ * — a custom page, the generated changelog index — which answers only at its
+ * own path.
+ */
+const mountConfiguredLink = (
+  path: string,
+  basePath: string,
+  extraRoutes: ReadonlySet<string>
+): string => (extraRoutes.has(path) ? path : withBasePath(basePath, path));
+
 /**
  * Build one locale's navigation tree from its own pages and folder meta.
  * `version` is the archived version id when building a snapshot's tree
@@ -217,8 +258,15 @@ const buildLocaleNavigation = (
   // next to the originals and `guides/meta.ts` applies to every locale —
   // prefixing would look up keys that can never exist. Inside a snapshot the
   // version dir is hoisted in front (`v1.0/fr`), matching `discoverFolderMeta`.
-  const localeDir =
-    i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
+  const localeDirOf = (locale: string): string =>
+    i18n.parser === "dir" && locale !== i18n.defaultLocale ? locale : "";
+  const localeDir = localeDirOf(code);
+  // A locale padded from the fallback locale mirrors that locale's folder meta
+  // for any folder it has no meta of its own for.
+  const fallbackMetaPrefix =
+    fallback && code !== fallback
+      ? [version, localeDirOf(fallback)].filter(Boolean).join("/")
+      : undefined;
   // Internal featured and header hrefs are localized like tab paths — a pinned
   // `/changelog` link rendered on `/fr/…` pages must stay inside the reader's
   // locale, not kick them back to the default one.
@@ -227,6 +275,7 @@ const buildLocaleNavigation = (
     href: localizeServed(item.href, false),
   });
   const { actions, cta, featured } = options.navigation;
+  const sidebarItems = options.navigation.sidebar.items;
 
   const navigation = buildNavigation(localePages, {
     actions: actions?.map(localizeHref),
@@ -235,6 +284,7 @@ const buildLocaleNavigation = (
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
+    fallbackMetaPrefix,
     featured: featured?.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
@@ -250,13 +300,43 @@ const buildLocaleNavigation = (
     sharedMetaPrefix: version,
     // A configured explicit sidebar describes the current docs; a frozen
     // snapshot's structure comes from the snapshot itself, so archived trees
-    // always build from the filesystem.
-    sidebar: version ? undefined : options.navigation.sidebar.items,
+    // always build from the filesystem. Its `href` links are localized like
+    // featured links.
+    sidebar:
+      version || !sidebarItems
+        ? undefined
+        : localizeSidebarHrefs(sidebarItems, (href) =>
+            localizeServed(href, false)
+          ),
+    // Tab paths are written against the current docs' root, which a
+    // snapshot's versionized `localizedRoot` no longer is.
+    tabRoot: localizeRoute("/", code, i18n),
     tabs,
   });
-  return options.brandHref === undefined
-    ? navigation
-    : { ...navigation, brandHref: localizeServed(options.brandHref, false) };
+  // `serves` checked the localized brand link against based routes, and
+  // unlike tab and header links it isn't rebased later, so a localized one
+  // takes the base here (`/fr` is served at `/docs/fr`).
+  const localizedBrand = (href: string): string => {
+    const localized = localizeServed(href, false);
+    return localized === href ? localized : withBasePath(basePath, localized);
+  };
+  const branded =
+    options.brandHref === undefined
+      ? navigation
+      : { ...navigation, brandHref: localizedBrand(options.brandHref) };
+  // The banner link is authored like a featured href — in the default
+  // locale's path space, as if mounted at root — so it is localized the same
+  // way before it is mounted.
+  return options.bannerHref === undefined
+    ? branded
+    : {
+        ...branded,
+        bannerHref: mountConfiguredLink(
+          localizeServed(options.bannerHref, false),
+          basePath,
+          extraRoutes
+        ),
+      };
 };
 
 /**
@@ -348,6 +428,8 @@ const buildVersionNavigation = (
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
       sharedMetaPrefix: id,
+      // Tab paths are written against the current docs' root.
+      tabRoot: "/",
       // A configured explicit sidebar describes the current docs; a snapshot's
       // structure comes from the snapshot itself.
       tabs: resolveTabLabels(options.navigation.tabs, ""),
@@ -398,6 +480,16 @@ export const buildContentGraph = (
       // entry on a single-locale site.
       tabs: resolveTabLabels(options.navigation.tabs, ""),
     });
+    if (options.bannerHref !== undefined) {
+      navigation = {
+        ...navigation,
+        bannerHref: mountConfiguredLink(
+          options.bannerHref,
+          options.basePath ?? "",
+          options.extraRoutes ?? new Set<string>()
+        ),
+      };
+    }
   }
 
   const navigationByVersion: Record<string, Record<string, Navigation>> = {};
@@ -417,6 +509,23 @@ export const buildContentGraph = (
     ...validateNavIcons(navigation),
     ...validateNavStructure(navigation, currentPages)
   );
+  // Checked once against every locale's pages, not per locale tree: a page
+  // missing from one locale's sidebar is an untranslated page, not a typo.
+  const sidebarItems = options.navigation.sidebar.items;
+  if (sidebarItems) {
+    const byRef = pagesByRef(
+      currentPages,
+      options.basePath ?? "",
+      Boolean(i18n)
+    );
+    const extraRoutes = options.extraRoutes ?? new Set<string>();
+    diagnostics.push(
+      ...validateSidebarItems(
+        sidebarItems,
+        (route) => byRef.has(route) || extraRoutes.has(route)
+      )
+    );
+  }
 
   return {
     diagnostics,

package/src/core/i18n-ui.ts

@@ -15,7 +15,6 @@ const uiStringsObject = z.object({
     .object({
       addToCursor: z.string().default("Add to Cursor"),
       addToVscode: z.string().default("Add to VS Code"),
-      askAI: z.string().default("Ask AI about this page"),
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
@@ -40,7 +39,7 @@ const uiStringsObject = z.object({
       scrollToTop: z.string().default("Scroll to top"),
     })
     .prefault({}),
-  ask: z
+  assistant: z
     .object({
       ai: z.string().default("AI"),
       clear: z.string().default("Clear conversation"),
@@ -52,7 +51,7 @@ const uiStringsObject = z.object({
       placeholder: z.string().default("Ask a question…"),
       send: z.string().default("Send"),
       tip: z.string().default("Tip: You can open and close chat with"),
-      title: z.string().default("Ask AI"),
+      title: z.string().default("Assistant"),
       you: z.string().default("You"),
     })
     .prefault({}),
@@ -73,11 +72,32 @@ const uiStringsObject = z.object({
     .prefault({}),
   content: z
     .object({
+      // `<Component>`'s source tab.
+      code: z.string().default("Code"),
       // A `<Color.Item>` swatch's accessible name; `{name}` and `{value}` are
       // replaced with the color's name and the value it shows.
       copyColor: z.string().default("Copy {name} color {value}"),
       copyPrompt: z.string().default("Copy prompt"),
+      // `<TypeTable>`: a row's default-value label.
+      default: z.string().default("Default"),
       diagramError: z.string().default("Could not render this diagram."),
+      // `<GithubInfo>`: the screen-reader labels of the fork and star counts.
+      forks: z.string().default("Forks"),
+      // `<Component>`'s live-preview tab, also its frame's title.
+      preview: z.string().default("Preview"),
+      // `<TypeTable>`: the property-name column.
+      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`.
+      showMore: z.string().default("Show more"),
+      stars: z.string().default("Stars"),
+      // An untitled tab's label; `{n}` is replaced with its position.
+      tab: z.string().default("Tab {n}"),
+      // `<TypeTable>`: the type column and a row's type label.
+      type: z.string().default("Type"),
+      // `<Update>`'s heading when it sets no `label` or `title`.
+      update: z.string().default("Update"),
     })
     .prefault({}),
   feedback: z
@@ -142,14 +162,19 @@ const uiStringsObject = z.object({
       all: z.string().default("All"),
       allLanguages: z.string().default("All languages"),
       allVersions: z.string().default("All versions"),
-      askAi: z.string().default("Ask AI"),
-      askAiHint: z.string().default("Get an instant answer from AI"),
+      assistant: z.string().default("Assistant"),
+      assistantHint: z.string().default("Get an instant answer from AI"),
       button: z.string().default("Search"),
       devOnly: z
         .string()
         .default("Search is available in the production build."),
+      // The section a hit falls under when its page sits in no sidebar group.
+      docs: z.string().default("Docs"),
       error: z.string().default("Something went wrong. Please try again."),
       label: z.string().default("Search docs"),
+      // The version tag on a result from the current docs in an all-versions
+      // search (a result from an archived version shows its version id).
+      latest: z.string().default("latest"),
       navigate: z.string().default("navigate"),
       noResults: z.string().default("No results found."),
       open: z.string().default("open"),
@@ -204,11 +229,38 @@ export const uiStringsOverrideSchema = z.record(
 
 export type UIStringsOverride = z.infer<typeof uiStringsOverrideSchema>;
 
+/**
+ * UI string keys renamed when Ask AI became the assistant, as `group` or
+ * `group.key`, each with its new name. Unknown keys merge harmlessly, so an
+ * override under an old name would otherwise be dropped without a word.
+ */
+const RENAMED_UI_KEYS = new Map([
+  ["ask", "assistant"],
+  ["search.askAi", "search.assistant"],
+  ["search.askAiHint", "search.assistantHint"],
+]);
+
 /** Per-locale UI overrides supplied in `i18n.ui`. */
-export const uiLocaleOverridesSchema = z.record(
-  z.string(),
-  uiStringsOverrideSchema
-);
+export const uiLocaleOverridesSchema = z
+  .record(z.string(), uiStringsOverrideSchema)
+  .superRefine((value, ctx) => {
+    for (const [locale, override] of Object.entries(value)) {
+      const keys = Object.entries(override).flatMap(([group, strings]) => [
+        group,
+        ...Object.keys(strings).map((key) => `${group}.${key}`),
+      ]);
+      for (const key of keys) {
+        const renamed = RENAMED_UI_KEYS.get(key);
+        if (renamed) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `i18n.ui.${locale}.${key} was renamed to i18n.ui.${locale}.${renamed}.`,
+            path: [locale, ...key.split(".")],
+          });
+        }
+      }
+    }
+  });
 
 /** Merge an override's string leaves onto a base dictionary (two levels deep). */
 const mergeUI = (base: UIStrings, override?: UIStringsOverride): UIStrings => {
@@ -255,11 +307,20 @@ const packFor = (code: string): UIStringsOverride | undefined => {
   );
 };
 
+/** Whether a locale code is English (`en`, `en-GB`, `en_US`), in any case. */
+const isEnglish = (code: string): boolean =>
+  code.toLowerCase().split(/[-_]/u)[0] === "en";
+
 /**
  * Resolve the active dictionary for a locale. Layers, in order:
  * English baseline ← default-locale pack ← default-locale override ←
  * locale pack ← locale override. So a missing key falls back to the default
  * locale's translation, then to English.
+ *
+ * English has no pack because the baseline is its complete translation, so an
+ * English locale (`en`, `en-GB`) skips the default-locale layers: on a site
+ * whose default is German, English pages keep English chrome instead of
+ * inheriting the German strings.
  */
 export const resolveUIStrings = (
   locale: string,
@@ -270,8 +331,10 @@ export const resolveUIStrings = (
 ): UIStrings => {
   const { defaultLocale, overrides } = options;
   let dict = EN_UI;
-  dict = mergeUI(dict, packFor(defaultLocale));
-  dict = mergeUI(dict, overrides?.[defaultLocale]);
+  if (!isEnglish(locale) || isEnglish(defaultLocale)) {
+    dict = mergeUI(dict, packFor(defaultLocale));
+    dict = mergeUI(dict, overrides?.[defaultLocale]);
+  }
   if (locale !== defaultLocale) {
     dict = mergeUI(dict, packFor(locale));
     dict = mergeUI(dict, overrides?.[locale]);

package/src/core/i18n.ts

@@ -187,12 +187,19 @@ export const localePlacement = (
  * (`x.en.mdx`) swaps it for the target's (`x.fr.mdx`) — same case-insensitive
  * last-dot-inside-filename logic as `localePlacement`, so both spellings of a
  * default-locale file resolve to one canonical target.
+ *
+ * Under `dir`, `folders` are the content root's existing top-level folders: one
+ * that names the locale in another casing (`pt-br/` for a configured `pt-BR`)
+ * is the locale's folder already, since {@link detectLocale} matches it case-
+ * insensitively. Writing beside it into a second `pt-BR/` would, on a case-
+ * sensitive filesystem, publish the page twice.
  */
 export const localeTargetPath = (
   rel: string,
   ext: string,
   locale: string,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  folders: readonly string[] = []
 ): string => {
   if (i18n.parser === "dot") {
     let base = rel.slice(0, rel.length - ext.length);
@@ -205,7 +212,11 @@ export const localeTargetPath = (
     }
     return `${base}.${locale}${ext}`;
   }
-  return `${locale}/${rel}`;
+  const folder = folders.includes(locale)
+    ? locale
+    : (folders.find((name) => name.toLowerCase() === locale.toLowerCase()) ??
+      locale);
+  return `${folder}/${rel}`;
 };
 
 /**