@stackql/docusaurus-plugin-aeo 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.5.1
+
+Localized sites (Docusaurus i18n) and sites with a non-root `baseUrl`. Raised against stackql.io when it gained a `de` locale.
+
+### Fixed
+
+- **Companions and alternate links on a site whose `baseUrl` is not `/`.** Docusaurus permalinks carry `siteConfig.baseUrl` but the build output tree is rooted at it, and in a localized build the plugin runs once per locale with `baseUrl: '/<locale>/'` and `outDir: build/<locale>`. Feature 1 joined `outDir` with the full permalink, so a `de` site wrote its companions to `build/de/de/foo.md`, and feature 1b looked for the page's HTML at the same wrong path and injected nothing. Both now strip the base URL from the route before touching the file system (`outputRoute` in `src/companionPath.js`); the companion URLs, the `Source:` lines, `llms.txt` and the `_headers` routes keep the full route as before. A localized build therefore emits `/<locale>/foo.md`, `/<locale>/llms.txt` and `/<locale>/llms-full.txt` from the translated sources with no configuration.
+- **Route patterns in a localized build or under a non-root `baseUrl`.** `companions.exclude`, `llmsTxt.exclude` and `llmsTxt.include` were matched against the full permalink, which carries `siteConfig.baseUrl`: `exclude: ['/docs/internal/**']` skipped the page in the default locale and kept `/de/docs/internal/...` in the `de` build, and the default `llmsTxt.exclude` list had the same gap. A pattern now matches a route with or without the base URL in front of it (`src/routeGlob.js`), so one configuration covers every locale. A pattern that spells the base out (`/de/blog/**`, or `/docs/guide/**` on a site built at `/docs/`) matches as before and can single out one locale. The Ask AI button follows, since it shows on the routes that have a companion.
+- **`aiRoutes.validate` under a base URL.** The `/ai/*` convention was looked for at the start of the permalink, so pages at `/de/ai/...` or `/docs/ai/...` were never validated. It is now relative to `siteConfig.baseUrl`.
+- **`_headers` for a non-default locale** (`companions.linkHeader`). Each build wrote its rules to `<outDir>/_headers`, which for a non-default locale is `build/<locale>/_headers`. Netlify and Cloudflare Pages document the file at the root of the published directory, so rules in a sub-directory cannot be relied on. In a build of several locales, the rules of every locale now go in the one `_headers` at the build root (Docusaurus builds the default locale first, so the file is there). A locale built on its own (`docusaurus build --locale de`) or given its own `baseUrl` keeps the file in its `outDir`. A rule already in the file is not appended a second time.
+
+### Changed
+
+- The Ask AI button's visible strings ("Ask AI about this page", "Ask Claude", "Ask ChatGPT", "Ask Perplexity") go through `translate()` with the ids `aeo.askAi.button` and `aeo.askAi.provider.<key>`, so `docusaurus write-translations` extracts them into `i18n/<locale>/code.json` and a localized site can translate them.
+- `{pageUrl}` in the Ask AI prompt ends with a slash on a root: the site root (`https://site/`, previously `https://site`) and a base URL such as `https://site/de/`, as the `Source:` lines already did. Other pages are unchanged (no trailing slash), and so is the default prompt, which uses `{companionUrl}`.
+- The Ask AI button's hover background is a 4% tint of the site's `--ifm-color-primary` instead of a fixed colour.
+
+### Added
+
+- `aiRoutePatterns(baseUrl)` in `@stackql/docusaurus-plugin-aeo/helpers`, and an optional `baseUrl` argument on `isAiRoute` and `buildStructuredDataAiExcludes`. `AI_ROUTE_PATTERNS` and `sitemapExclude` are unchanged and describe a site at the root with one locale; a site with a non-root `baseUrl` or several locales builds its list with `['/', '/de/'].flatMap(aiRoutePatterns)`.
+- README: hosting notes. Which hosts `companions.linkHeader` applies to (those that read `_headers`: Netlify, Cloudflare Pages, with Cloudflare's 100-rule limit), where the file is written, `.nojekyll` on GitHub Pages, and absolute URLs on preview deployments.
+- Tests for all of the above and for the rest of this release: companion files and `llms.txt` under a base URL, the plugin run once per locale, and the Ask AI button rendered in Node (`test/companions.test.js`, `test/localizedBuild.test.js`, `test/askAiButton.test.js`, `test/routeGlob.test.js`, `test/aiHelpers.test.js`).
+
 ## 0.5.0
 
 Plain-markdown companions, one rule for where a companion lives, and the companion advertised from its page. Raised against stackql.io, where the Ask AI prompt on the homepage read `https://stackql.io.md` and every `.md` URL returned raw MDX (imports, MUI components, tab definitions and inline SVG path data before the first sentence), and from an independent agent-readiness audit of the built site (alternate link, `llms-full.txt` reference and size, `Source:` URLs, the `how-tos` alias).

package/README.md

@@ -1,4 +1,5 @@
-[![NPM Version](https://img.shields.io/npm/v/%40stackql%2Fdocusaurus-plugin-aeo)](https://www.npmjs.com/package/@stackql/docusaurus-plugin-aeo)
+[![NPM Version](https://img.shields.io/npm/v/%40stackql%2Fdocusaurus-plugin-aeo)](https://www.npmjs.com/package/@stackql/docusaurus-plugin-aeo) 
+[![NPM Downloads](https://img.shields.io/npm/d18m/%40stackql%2Fdocusaurus-plugin-aeo)](https://www.npmjs.com/package/@stackql/docusaurus-plugin-aeo)
 
 # @stackql/docusaurus-plugin-aeo
 
@@ -47,7 +48,7 @@ module.exports = {
 
 ## Feature 1: `.md` companion files
 
-For each doc or blog post with a readable source file, this plugin writes a sibling `.md` file unless its permalink matches `companions.exclude`. The companion mirrors the HTML layout: a page at `/docs/intro` gets `/docs/intro/index.md` (or `/docs/intro.md` if `siteConfig.trailingSlash` is `false`). A doc or blog post at the site root gets `/index.md`. The same URL rule (`src/companionPath.js`) is used by `llms.txt` and the Ask AI button.
+For each doc or blog post with a readable source file, this plugin writes a sibling `.md` file unless its route matches `companions.exclude` (see [Route patterns](#route-patterns)). The companion mirrors the HTML layout: a page at `/docs/intro` gets `/docs/intro/index.md` (or `/docs/intro.md` if `siteConfig.trailingSlash` is `false`). A doc or blog post at the site root gets `/index.md`. The same URL rule (`src/companionPath.js`) is used by `llms.txt` and the Ask AI button.
 
 Two modes:
 
@@ -86,10 +87,33 @@ inserted into the built HTML in `postBuild` (the same pattern `@stackql/docusaur
 | Option | Default | Description |
 | --- | --- | --- |
 | `companions.alternateLink` | `true` | Insert the `<link rel="alternate" type="text/markdown">` tag into each page that has a companion. |
-| `companions.linkHeader` | `false` | Also write the relation as an HTTP header for Netlify-style hosts: a `_headers` file in the build root with `Link: <url>; rel="alternate"; type="text/markdown"` per route (appended to a `_headers` your `static/` already ships). Requires `companions.alternateLink: true`. |
+| `companions.linkHeader` | `false` | Also send the relation as an HTTP response header, on hosts that read a `_headers` file (Netlify, Cloudflare Pages): one `Link: <url>; rel="alternate"; type="text/markdown"` rule per page, written to `_headers` in the build root (appended to a `_headers` your `static/` already ships). It has no effect on other hosts; see [Hosting notes](#hosting-notes). Requires `companions.alternateLink: true`. |
 
 Generated category indexes, custom React pages and blog listing pages do not get companions. `verbose: true` logs unreadable source files and missing HTML during alternate-link insertion.
 
+### Localized sites and non-root `baseUrl`
+
+The plugin works from `siteConfig.url` and `siteConfig.baseUrl` as Docusaurus reports them for the build, so a site at the root, a site built at `/docs/` and a site with several locales are configured the same way.
+
+On a site with Docusaurus i18n the plugin runs once per locale, like every plugin, and needs no extra configuration: each locale gets its own companions (`/de/docs/intro.md` from the translated source, or from the default-locale source when a page has no translation), its own `/de/llms.txt` and `/de/llms-full.txt`, and alternate links and `Source:` lines that carry the locale prefix. The localized home page `/de/` is a root, so its companion is `/de/index.md`. The same holds for a site built at a non-root `baseUrl`: files are written relative to the build directory, URLs carry the base.
+
+### Route patterns
+
+`companions.exclude`, `llmsTxt.exclude` and `llmsTxt.include` take glob patterns for routes. `**` matches across path segments; `*` and `?` match within a single segment.
+
+Write a pattern for the route as it is on the site, without the base URL: `/docs/internal/**`. Docusaurus permalinks carry the base URL (`/de/docs/internal/notes` in a `de` build, `/docs/guide/setup` on a site built at `/docs/`), so a pattern is matched against the route both with and without it. One list therefore applies to every locale, and a pattern that includes the base still works and can target a single locale:
+
+```js
+companions: {
+  exclude: [
+    '/docs/internal/**',  // every locale: /docs/internal/..., /de/docs/internal/...
+    '/de/blog/**',        // the de locale only
+  ],
+},
+```
+
+A page excluded from companions has no `.md` file, no alternate link, no `llms.txt` entry and no Ask AI button.
+
 ## Feature 2: `llms.txt` and `llms-full.txt`
 
 With the defaults enabled, the plugin writes two files to the build root after emitting companions. Both use the emitted companion list, filtered by `llmsTxt.include` and `llmsTxt.exclude`. If companions are disabled, `llms.txt` contains only the site title, tagline and optional header; no page entries or `llms-full.txt` are emitted.
@@ -132,7 +156,7 @@ Options:
 | `llmsTxt.fullTxt` | `true` | Emit `llms-full.txt`. `true` is every section, uncapped. The object form `{ include?: string[], maxBytes?: number }` limits it: `include` names the content instances to concatenate (`'<pluginName>@<pluginId>'` keys, e.g. `'docusaurus-plugin-content-docs@ai'`; with per-type grouping the keys are `docs`, `blog`, `pages`), in `llms.txt` section order; `maxBytes` stops appending once the next page would cross the cap, so the file always ends on a whole page. The budget includes section headings and separators. If the first page exceeds it, the file is empty. An omitted or empty `include` selects all sections. |
 | `llmsTxt.linkFullTxt` | `true` | Add the `## Optional` section to `llms.txt` with a link to `llms-full.txt`. |
 
-Glob patterns are matched against route permalinks. `**` matches across path segments; `*` matches within a single segment.
+`exclude` and `include` follow the rules in [Route patterns](#route-patterns): a pattern matches a route with or without the base URL, so the defaults apply to every locale.
 
 ### Per-instance sectioning
 
@@ -237,7 +261,7 @@ Template placeholders:
 | Placeholder | Value |
 | --- | --- |
 | `{companionUrl}` | The page's `.md` companion, by the same rule feature 1 writes it: `https://site/index.md` for the homepage, `https://site/foo.md` or `https://site/foo/index.md` depending on `trailingSlash`. With feature 1 disabled, the page URL. |
-| `{pageUrl}` | The page itself: canonical URL, no trailing slash. |
+| `{pageUrl}` | The page itself: canonical URL, no trailing slash, except on a root (`https://site/`, or a base URL such as `https://site/de/`). |
 | `{pageUrl}.md` | Still honoured for templates written against v0.4, and resolves to `{companionUrl}`. (On its own it produced `https://site.md` for the homepage and the wrong path on sites that build `/foo/index.html`.) |
 
 The button only renders on pages that have a companion. Generated category index pages, React pages and blog list pages have no `.md` file, so on those the button is not shown rather than sending the reader to a 404. (The list of routes comes from `allContentLoaded`; with feature 1 disabled, the companion-route filter is disabled and the prompt uses the page URL wherever the button is rendered.)
@@ -254,10 +278,23 @@ Options:
 | --- | --- | --- |
 | `askAi.enabled` | `true` | When `false`, the theme components are not registered. |
 | `askAi.providerOrder` | `['claude', 'chatgpt', 'perplexity']` | Order of items in the dropdown. Omit providers to hide them; an empty array falls back to the default order. Valid values: `'claude'`, `'chatgpt'`, `'perplexity'`. |
-| `askAi.promptTemplate` | `'Read {companionUrl} and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper.'` | Prompt sent to each provider. `{companionUrl}` is the page's `.md` companion (the page URL when feature 1 is disabled); `{pageUrl}` is the page's canonical URL (no trailing slash). See the placeholder table above. |
+| `askAi.promptTemplate` | `'Read {companionUrl} and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper.'` | Prompt sent to each provider. `{companionUrl}` is the page's `.md` companion (the page URL when feature 1 is disabled); `{pageUrl}` is the page's canonical URL (no trailing slash except on a root). See the placeholder table above. |
 | `askAi.placement` | `'breadcrumb-row'` | `'breadcrumb-row'` puts the button at the top of every doc/blog page (docs breadcrumb row, or above the blog title). `'none'` disables all bundled theme components, including the `@theme/AskAiButton` alias. See custom placement below. |
 
-The button is built from [MUI](https://mui.com) primitives - outlined `Button` with a `KeyboardArrowDownIcon` caret as the trigger, and a `Menu` of `MenuItem` rows for the providers. Theming reads `--ifm-color-primary` and `--ifm-font-family-base` via MUI's `sx` prop, so dark/light mode work automatically. The MUI `Menu` handles click-outside-to-close and Esc-to-close natively.
+The button is built from [MUI](https://mui.com) primitives - outlined `Button` with a `KeyboardArrowDownIcon` caret as the trigger, and a `Menu` of `MenuItem` rows for the providers. Theming reads `--ifm-color-primary` and `--ifm-font-family-base` via MUI's `sx` prop, so the button takes the site's own colours and dark/light mode work automatically. The MUI `Menu` handles click-outside-to-close and Esc-to-close natively.
+
+### Translating the button
+
+The visible strings go through Docusaurus `translate()`, so `docusaurus write-translations --locale <locale>` extracts them into `i18n/<locale>/code.json` with the rest of the theme's strings:
+
+| Id | Default |
+| --- | --- |
+| `aeo.askAi.button` | Ask AI about this page |
+| `aeo.askAi.provider.claude` | Ask Claude |
+| `aeo.askAi.provider.chatgpt` | Ask ChatGPT |
+| `aeo.askAi.provider.perplexity` | Ask Perplexity |
+
+A locale with no translation for an id shows the default. The prompt itself is `askAi.promptTemplate`; in a localized build its URLs point at that locale's page and companion.
 
 ### Peer dependencies
 
@@ -345,21 +382,36 @@ ai-content/
 
 With default filters, these docs appear in `llms.txt` and `llms-full.txt`. Their companions follow the same URL rule: `/ai/faqs/<slug>/index.md`, or `/ai/faqs/<slug>.md` when `trailingSlash: false`.
 
+The convention is relative to the site's base URL: on a site built at `/docs/` the routes are `/docs/ai/*`, and in a `de` build they are `/de/ai/*`.
+
 ### Optional validation
 
-Set `aiRoutes.validate: true` to warn when docs at `/ai/faqs/*`, `/ai/howto/*`, or `/ai/apps/*` lack the corresponding frontmatter payload (`faq`, `howTo`, `softwareApplication`). Validation uses route permalinks, not source directories, and does not fail the build. Set `verbose: true` for per-page details. Off by default.
+Set `aiRoutes.validate: true` to warn when docs at `/ai/faqs/*`, `/ai/howto/*`, or `/ai/apps/*` lack the corresponding frontmatter payload (`faq`, `howTo`, `softwareApplication`). Validation uses route permalinks (relative to the base URL, so every locale is checked), not source directories, and does not fail the build. Set `verbose: true` for per-page details. Off by default.
 
 ### Helpers
 
 ```js
 const {
   AI_ROUTE_PATTERNS,             // ['/ai', '/ai/**'] - glob patterns
+  aiRoutePatterns,               // (baseUrl) => the same patterns under a base URL
   sitemapExclude,                // { ignorePatterns: AI_ROUTE_PATTERNS }
-  isAiRoute,                     // true for /ai/*; false for /ai itself
-  buildStructuredDataAiExcludes, // (routePaths[]) => string[]
+  isAiRoute,                     // (route, baseUrl?) true for /ai/*; false for /ai itself
+  buildStructuredDataAiExcludes, // (routePaths[], baseUrl?) => string[]
 } = require('@stackql/docusaurus-plugin-aeo/helpers');
 ```
 
+`AI_ROUTE_PATTERNS` and `sitemapExclude` describe a site at the root with one locale. These helpers run in your config, where other plugins match the full route path, base URL included (the Docusaurus docs say as much of the sitemap plugin's `ignorePatterns`). With a non-root `baseUrl` or several locales, build the list from `aiRoutePatterns`, one call per base URL:
+
+```js
+const { aiRoutePatterns } = require('@stackql/docusaurus-plugin-aeo/helpers');
+
+// a site with en at / and de at /de/
+const ignorePatterns = ['/', '/de/'].flatMap(aiRoutePatterns);
+// ['/ai', '/ai/**', '/de/ai', '/de/ai/**']
+```
+
+`isAiRoute` and `buildStructuredDataAiExcludes` take the base URL as an optional second argument.
+
 **Heads-up on the structured-data plugin.** `@stackql/docusaurus-plugin-structured-data`'s `themeConfig.structuredData.excludedRoutes` compares routes with strict equality, so glob patterns like `/ai/**` do not work there. Use one of these approaches:
 
 - List the exact `/ai/*` permalinks you want skipped by hand (works if your `/ai/*` tree is small and stable).
@@ -379,6 +431,16 @@ const {
 
 The `sitemapExclude` helper, by contrast, does work with globs because `@docusaurus/plugin-sitemap` uses `ignorePatterns` (micromatch under the hood).
 
+## Hosting notes
+
+Everything the plugin produces is a static file or an edit to the built HTML, so companions, `llms.txt`, `llms-full.txt`, the alternate link tag and the Ask AI button work on any static host with no host configuration. A few things do depend on where the site is deployed:
+
+- **`Content-Type` of `.md` files.** Set by the host; see the MIME type note under Feature 1.
+- **GitHub Pages.** GitHub Pages runs published files through Jekyll by default. Jekyll builds sites from Markdown, so `.md` companions may be turned into pages instead of being published as they are. Add an empty `.nojekyll` file to `static/`, as the [Docusaurus deployment guide](https://docusaurus.io/docs/deployment) recommends. A project site is served under `/<repo>/`: set `baseUrl` as usual and the plugin follows it.
+- **`companions.linkHeader` is for hosts that read `_headers`.** That is Netlify and Cloudflare Pages. Vercel documents response headers through `vercel.json`, and GitHub Pages has no server-side configuration for them, so the option does nothing there. The alternate link tag, on by default, needs nothing from the host and is the portable way to advertise a companion. The file gets one rule per page that has a companion; Cloudflare Pages documents a limit of 100 header rules, so leave the option off there on a larger site.
+- **Where `_headers` is written.** At the root of the build directory, which is where both hosts document the file. A build of several locales (`docusaurus build`, one deployment serving `/` and `/de/`) puts every locale's rules in that one file. A locale built on its own (`docusaurus build --locale de`) or given its own `baseUrl` is a separate deployment and gets the file in its own output directory.
+- **Preview deployments.** Companion URLs, `Source:` lines, `llms.txt` links and the Ask AI prompt are absolute and come from `siteConfig.url`, so on a deploy preview they point at the production site.
+
 ## Full options reference
 
 ```js
@@ -389,7 +451,7 @@ The `sitemapExclude` helper, by contrast, does work with globs because `@docusau
     format: 'plain',          // 'plain' ('clean' is a synonym) | 'raw'
     exclude: [],              // route glob patterns to skip
     alternateLink: true,      // <link rel="alternate" type="text/markdown"> in each page
-    linkHeader: false,        // also a Link: header via a Netlify _headers file
+    linkHeader: false,        // also a Link: header via a _headers file (Netlify, Cloudflare Pages)
   },
 
   // Feature 2
@@ -448,10 +510,12 @@ npm ci
 npm test
 ```
 
-`npm test` runs every `test/*.test.js` file with Node's test runner: companion paths, Ask AI prompts, plain Markdown, alternate links/headers, `llms.txt`, and AI route classification.
+`npm test` runs every `test/*.test.js` file with Node's test runner: companion paths and files, route patterns, Ask AI prompts and the rendered button, plain Markdown, alternate links/headers, `llms.txt`, AI route classification and helpers, and the plugin run once per locale as Docusaurus runs it (`test/localizedBuild.test.js`). Shared fixtures and the loader that renders theme components in Node are in `test/helpers/`. There are no dev dependencies: the tests use the peer dependencies and the Babel setup that comes with `@docusaurus/core`.
 
 The [Tests workflow](.github/workflows/tests.yml) runs on every pull request targeting `main` and on pushes to `main`, using the committed lockfile and Node 24.x. To make it a merge gate, require the **Tests (Node 24)** status check in the branch protection rule or ruleset for `main`. Until that rule is enabled, a failed check does not block merging.
 
+When `npm audit` reports advisories, they are almost always in the Docusaurus toolchain, which is installed here only because it is a peer dependency. Do not run `npm audit fix`: it clears the report by downgrading the `@docusaurus/core` peer to an older release with a different set of advisories. Update the named packages instead (`npm update <package> ...`), which moves them within the ranges Docusaurus already allows, then re-run `npm audit` and `npm test`.
+
 The plain-markdown converter lives in `src/features/plainMarkdown.js` and is exercised by `test/plainMarkdown.test.js` with small MDX fixtures; add a fixture there when a new construct needs handling.
 
 ## Composing with `@stackql/docusaurus-plugin-structured-data`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/docusaurus-plugin-aeo",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "AEO (Answer Engine Optimization) helpers for Docusaurus: .md companion files, llms.txt / llms-full.txt, an Ask AI dropdown, and /ai/* route conventions.",
   "main": "src/index.js",
   "exports": {
@@ -80,5 +80,8 @@
   "homepage": "https://github.com/stackql-labs/docusaurus-plugin-aeo#readme",
   "engines": {
     "node": ">=18.0"
+  },
+  "allowScripts": {
+    "core-js": false
   }
 }

package/src/askAiPrompt.js

@@ -2,7 +2,8 @@
 // can bundle it and the tests can require it.
 //
 //   {companionUrl}  the page's .md companion (absolute URL)
-//   {pageUrl}       the page itself (canonical, no trailing slash)
+//   {pageUrl}       the page itself (canonical: no trailing slash, except
+//                   on a root - the site root or a base URL such as '/de/')
 //
 // The v0.4 idiom `{pageUrl}.md` is still honoured so a custom template
 // keeps working. It was wrong for the homepage (`https://site.md`) and for

package/src/companionPath.js

@@ -19,37 +19,71 @@ function normalizeRoute(routePath) {
   return cleaned === '' ? '/' : cleaned;
 }
 
+// Every function below takes an optional `baseUrl` (siteConfig.baseUrl).
+// Docusaurus permalinks and location.pathname carry it, and the part of
+// the route that is the base is a root, not a page: on a site built at
+// '/docs/' or in a localized build (baseUrl '/de/') the route '/de/' is the
+// home page, whose companion is '/de/index.md', not '/de.md'. With the
+// default '/' nothing changes.
+function withBase(baseUrl, sitePath) {
+  return `${String(baseUrl || '/').replace(/\/+$/, '')}${sitePath}`;
+}
+
 // Site-relative companion path for a route, e.g. '/foo.md'. Always starts
 // with '/'.
-function companionPath(routePath, trailingSlash) {
-  const route = normalizeRoute(routePath);
-  if (route === '/') return '/index.md';
-  return trailingSlash === false ? `${route}.md` : `${route}/index.md`;
+function companionPath(routePath, trailingSlash, baseUrl) {
+  const route = outputRoute(routePath, baseUrl);
+  const rel = route === '/'
+    ? '/index.md'
+    : trailingSlash === false ? `${route}.md` : `${route}/index.md`;
+  return withBase(baseUrl, rel);
 }
 
 // Absolute companion URL for a route, e.g. 'https://example.com/foo.md'.
-// `siteUrl` is siteConfig.url; the route already carries siteConfig.baseUrl
-// (Docusaurus permalinks and location.pathname both include it).
-function companionUrl(siteUrl, routePath, trailingSlash) {
-  return `${String(siteUrl || '').replace(/\/+$/, '')}${companionPath(routePath, trailingSlash)}`;
+// `siteUrl` is siteConfig.url.
+function companionUrl(siteUrl, routePath, trailingSlash, baseUrl) {
+  return `${String(siteUrl || '').replace(/\/+$/, '')}${companionPath(routePath, trailingSlash, baseUrl)}`;
 }
 
 // Site-relative path of the HTML file Docusaurus writes for a route, the
 // same rule as @docusaurus/core's pathnameToFilename once the route has
 // been normalised: '/foo.html' when trailingSlash is false, '/foo/index.html'
 // otherwise, '/index.html' for the root.
-function htmlPath(routePath, trailingSlash) {
-  const route = normalizeRoute(routePath);
-  if (route === '/') return '/index.html';
-  return trailingSlash === false ? `${route}.html` : `${route}/index.html`;
+function htmlPath(routePath, trailingSlash, baseUrl) {
+  const route = outputRoute(routePath, baseUrl);
+  const rel = route === '/'
+    ? '/index.html'
+    : trailingSlash === false ? `${route}.html` : `${route}/index.html`;
+  return withBase(baseUrl, rel);
 }
 
 // Absolute URL of the page itself: canonical, no trailing slash except on
-// the root.
-function pageUrl(siteUrl, routePath) {
+// the root (the site root, or the localized root '/de/').
+function pageUrl(siteUrl, routePath, baseUrl) {
   const base = String(siteUrl || '').replace(/\/+$/, '');
-  const route = normalizeRoute(routePath);
-  return route === '/' ? `${base}/` : `${base}${route}`;
+  const route = outputRoute(routePath, baseUrl);
+  return `${base}${withBase(baseUrl, route)}`;
+}
+
+// The route relative to the build output tree. Docusaurus permalinks carry
+// siteConfig.baseUrl, but the output tree is rooted at it: a site with
+// baseUrl '/docs/' writes /docs/intro to build/intro.html, and a localized
+// build (baseUrl '/de/', outDir build/de) writes /de/intro to
+// build/de/intro.html. URLs keep the full route (pass baseUrl to the
+// functions above); file paths under outDir use this route with no base.
+function outputRoute(routePath, baseUrl) {
+  return stripBase(normalizeRoute(routePath), baseUrl);
+}
+
+// A route with siteConfig.baseUrl removed and nothing else changed (a
+// trailing slash stays): '/de/blog/post/' under '/de/' is '/blog/post/', and
+// the base itself is '/'. A route outside the base is returned as is.
+function stripBase(routePath, baseUrl) {
+  const route = String(routePath || '');
+  const base = String(baseUrl || '/').replace(/\/+$/, '');
+  if (base === '') return route;
+  if (route === base) return '/';
+  return route.startsWith(`${base}/`) ? route.slice(base.length) : route;
 }
 
-module.exports = { companionPath, companionUrl, htmlPath, pageUrl, normalizeRoute };
+module.exports = { companionPath, companionUrl, htmlPath, pageUrl, outputRoute, stripBase, normalizeRoute };

package/src/features/aiRoutes.js

@@ -12,6 +12,8 @@
 // Anything else under /ai/* is permitted without a payload (consumer can
 // extend this with additional checks if needed).
 
+const { outputRoute } = require('../companionPath');
+
 const KIND_FOR_DIR = {
   faqs: 'faq',
   faq: 'faq',
@@ -24,10 +26,14 @@ const KIND_FOR_DIR = {
   applications: 'softwareApplication',
 };
 
-function classify(permalink) {
-  // permalink like "/ai/faqs/foo"
-  if (!permalink.startsWith('/ai/')) return null;
-  const segments = permalink.split('/').filter(Boolean); // ["ai", "faqs", "foo"]
+// `baseUrl` is siteConfig.baseUrl. The convention is relative to it: on a
+// site built at '/docs/' the routes are '/docs/ai/...', and in a localized
+// build '/de/ai/...'.
+function classify(permalink, baseUrl) {
+  // route like "/ai/faqs/foo"
+  const route = outputRoute(permalink, baseUrl);
+  if (!route.startsWith('/ai/')) return null;
+  const segments = route.split('/').filter(Boolean); // ["ai", "faqs", "foo"]
   if (segments.length < 2) return null;
   const dir = segments[1].toLowerCase();
   return KIND_FOR_DIR[dir] || null;
@@ -45,7 +51,7 @@ function collectDocs(content) {
   return out;
 }
 
-function validateAiRoutes({ loadedContentByPlugin, verbose }) {
+function validateAiRoutes({ loadedContentByPlugin, baseUrl, verbose }) {
   const problems = [];
   for (const [, entry] of loadedContentByPlugin) {
     if (entry.pluginName !== 'docusaurus-plugin-content-docs') continue;
@@ -53,7 +59,7 @@ function validateAiRoutes({ loadedContentByPlugin, verbose }) {
     for (const doc of docs) {
       const permalink = doc.permalink;
       if (!permalink) continue;
-      const expectedKey = classify(permalink);
+      const expectedKey = classify(permalink, baseUrl);
       if (!expectedKey) continue;
       const fm = doc.frontMatter || {};
       const value = fm[expectedKey];

package/src/features/alternateLinks.js

@@ -6,9 +6,12 @@
 //
 // inserted into its built HTML before </head>, so an agent that lands on
 // the page can find the markdown without guessing the URL. Optionally the
-// same relation is written as an HTTP header for Netlify-style hosts via a
-// `_headers` file (`Link: <url>; rel="alternate"; type="text/markdown"`),
-// for agents that read headers before bodies.
+// same relation is written as an HTTP header via a `_headers` file
+// (`Link: <url>; rel="alternate"; type="text/markdown"`), for agents that
+// read headers before bodies. Only hosts that read `_headers` use it
+// (Netlify, Cloudflare Pages); elsewhere the file is inert and the <link>
+// tag is what advertises the companion. The file sits at the root of the
+// build directory, shared by every locale built into it.
 //
 // Same approach as @stackql/docusaurus-plugin-structured-data, which also
 // post-processes the built HTML in postBuild: the file is a string, the
@@ -16,7 +19,7 @@
 
 const path = require('path');
 const fs = require('fs').promises;
-const { htmlPath, companionUrl } = require('../companionPath');
+const { htmlPath, companionUrl, outputRoute } = require('../companionPath');
 
 const MARK = 'rel="alternate" type="text/markdown"';
 
@@ -28,6 +31,25 @@ function headerBlock(route, href) {
   return `${route}\n  Link: <${href}>; rel="alternate"; type="text/markdown"\n`;
 }
 
+// Where `_headers` goes. The hosts that read the file (Netlify, Cloudflare
+// Pages) document it at the root of the published directory, so that is
+// the only place it can be relied on. A build of several locales puts
+// every locale but the default in a sub-directory of the build directory
+// named after the locale (baseUrl '/de/' or '/docs/de/' -> build/de), so
+// that locale's rules belong one level up, in the file the default
+// locale's build wrote (Docusaurus builds the default locale first). This
+// assumes the build directory is deployed as one site. Every other build
+// is its own root: one locale, a locale built on its own (`--locale de`,
+// baseUrl '/'), a locale given its own baseUrl, or a core that passes no
+// i18n.
+function headersDir({ outDir, siteConfig, i18n }) {
+  const locale = i18n && i18n.currentLocale;
+  if (!locale || locale === i18n.defaultLocale) return outDir;
+  const base = String(siteConfig.baseUrl || '/').replace(/\/+$/, '');
+  const nested = base.endsWith(`/${locale}`) && path.basename(outDir) === locale;
+  return nested ? path.dirname(outDir) : outDir;
+}
+
 async function readIfExists(file) {
   try {
     return await fs.readFile(file, 'utf8');
@@ -52,8 +74,13 @@ module.exports = async function injectAlternateLinks({
   const headerBlocks = [];
 
   for (const item of emittedCompanions) {
-    const href = companionUrl(siteUrl, item.permalink, trailingSlash);
-    const file = path.join(outDir, htmlPath(item.permalink, trailingSlash));
+    const href = companionUrl(siteUrl, item.permalink, trailingSlash, siteConfig.baseUrl);
+    // The HTML lives under outDir at the route without siteConfig.baseUrl
+    // (see outputRoute); the URL and the _headers route keep the full one.
+    const file = path.join(
+      outDir,
+      htmlPath(outputRoute(item.permalink, siteConfig.baseUrl), trailingSlash),
+    );
     const html = await readIfExists(file);
     if (html === null) {
       skipped++;
@@ -75,20 +102,26 @@ module.exports = async function injectAlternateLinks({
       injected++;
     }
     if (linkHeader) {
-      // Netlify matches the route as requested; with trailingSlash false
-      // that is the bare route, otherwise the route with its slash.
-      const route = htmlPath(item.permalink, trailingSlash).replace(/index\.html$/, '').replace(/\.html$/, '');
+      // A `_headers` rule matches the path as requested; with
+      // trailingSlash false that is the bare route, otherwise the route
+      // with its slash.
+      const route = htmlPath(item.permalink, trailingSlash, siteConfig.baseUrl).replace(/index\.html$/, '').replace(/\.html$/, '');
       headerBlocks.push(headerBlock(route === '' ? '/' : route, href));
     }
   }
 
   if (linkHeader && headerBlocks.length > 0) {
-    // Append to a `_headers` the site may already ship from static/.
-    const file = path.join(outDir, '_headers');
+    // Append to a `_headers` the site may already ship from static/, or
+    // that another locale's build has already added its rules to. A rule
+    // already in the file is not written again.
+    const file = path.join(headersDir(props), '_headers');
     const existing = (await readIfExists(file)) || '';
-    const banner = '# @stackql/docusaurus-plugin-aeo: .md companions as Link headers\n';
-    const sep = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
-    await fs.writeFile(file, `${existing}${sep}${banner}${headerBlocks.join('')}`, 'utf8');
+    const fresh = headerBlocks.filter((block) => !existing.includes(block));
+    if (fresh.length > 0) {
+      const banner = '# @stackql/docusaurus-plugin-aeo: .md companions as Link headers\n';
+      const sep = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
+      await fs.writeFile(file, `${existing}${sep}${banner}${fresh.join('')}`, 'utf8');
+    }
   }
 
   if (verbose) {

package/src/features/companions.js

@@ -1,45 +1,10 @@
 const path = require('path');
 const fs = require('fs').promises;
 const matter = require('gray-matter');
-const { companionPath, pageUrl } = require('../companionPath');
+const { companionPath, pageUrl, outputRoute } = require('../companionPath');
+const { matchAny, matchesRoute } = require('../routeGlob');
 const { toPlainMarkdown, resolveFormat } = require('./plainMarkdown');
 
-// Minimal glob matcher for route paths. Patterns like "/blog/tags/**",
-// "/search". Avoids pulling micromatch directly.
-function matchAny(value, patterns) {
-  if (!patterns || patterns.length === 0) return false;
-  for (const p of patterns) {
-    if (toRegExp(p).test(value)) return true;
-  }
-  return false;
-}
-
-function toRegExp(glob) {
-  // Minimal globstar -> regex translation. Supports: **, *, ?, character
-  // classes left untouched. Good enough for route paths like
-  // "/blog/tags/**" and "/search".
-  let re = '';
-  for (let i = 0; i < glob.length; i++) {
-    const c = glob[i];
-    if (c === '*') {
-      if (glob[i + 1] === '*') {
-        re += '.*';
-        i++;
-        if (glob[i + 1] === '/') i++;
-      } else {
-        re += '[^/]*';
-      }
-    } else if (c === '?') {
-      re += '[^/]';
-    } else if ('.+^$()|{}[]\\'.includes(c)) {
-      re += '\\' + c;
-    } else {
-      re += c;
-    }
-  }
-  return new RegExp('^' + re + '$');
-}
-
 function collectFromDocs(content, pluginName, pluginId) {
   // Docs plugin loaded content shape:
   //   { loadedVersions: [{ docs: [{ id, permalink, source, title, description, frontMatter }] }] }
@@ -91,8 +56,10 @@ function collectFromBlog(content, pluginName, pluginId) {
 // minus `companions.exclude`. Generated category indexes, React pages and
 // blog list/tag/author pages have no source and are not in this list. Used
 // by postBuild to emit the files and by allContentLoaded to tell the Ask AI
-// button which routes have one.
-function collectCompanionItems(loadedContentByPlugin, options) {
+// button which routes have one. `baseUrl` is siteConfig.baseUrl: an exclude
+// pattern matches a route with or without it (see src/routeGlob.js), so the
+// same patterns apply in every locale's build.
+function collectCompanionItems(loadedContentByPlugin, options, baseUrl) {
   const items = [];
   for (const [, entry] of loadedContentByPlugin) {
     const { pluginName, pluginId, content } = entry;
@@ -104,7 +71,7 @@ function collectCompanionItems(loadedContentByPlugin, options) {
     // Custom pages plugin emits React components, not markdown. Skip silently.
   }
   const exclude = (options && options.exclude) || [];
-  return items.filter((item) => !matchAny(item.permalink, exclude));
+  return items.filter((item) => !matchesRoute(item.permalink, exclude, baseUrl));
 }
 
 function resolveSourcePath(sourceRef, siteDir) {
@@ -162,7 +129,7 @@ module.exports = async function emitCompanions({
   const format = options.format === 'clean' ? 'plain' : options.format;
   const markdownConfigFormat = siteConfig.markdown && siteConfig.markdown.format;
 
-  const items = collectCompanionItems(loadedContentByPlugin, options);
+  const items = collectCompanionItems(loadedContentByPlugin, options, siteConfig.baseUrl);
 
   const emitted = [];
   let fallbacks = 0;
@@ -211,11 +178,17 @@ module.exports = async function emitCompanions({
         result.markdown,
         item.title,
         item.description,
-        pageUrl(siteConfig.url, item.permalink),
+        pageUrl(siteConfig.url, item.permalink, siteConfig.baseUrl),
       );
     }
 
-    const target = path.join(outDir, companionPath(item.permalink, trailingSlash));
+    // The permalink carries siteConfig.baseUrl (localized to /<locale>/ in a
+    // localized build, whose outDir is build/<locale>); the file goes under
+    // outDir at the route without it.
+    const target = path.join(
+      outDir,
+      companionPath(outputRoute(item.permalink, siteConfig.baseUrl), trailingSlash),
+    );
     await ensureDir(target);
     await fs.writeFile(target, body, 'utf8');
 

package/src/features/llmsTxt.js

@@ -1,37 +1,7 @@
 const path = require('path');
 const fs = require('fs').promises;
 const { companionUrl, pageUrl } = require('../companionPath');
-
-function matchAny(value, patterns) {
-  if (!patterns || patterns.length === 0) return false;
-  for (const p of patterns) {
-    if (toRegExp(p).test(value)) return true;
-  }
-  return false;
-}
-
-function toRegExp(glob) {
-  let re = '';
-  for (let i = 0; i < glob.length; i++) {
-    const c = glob[i];
-    if (c === '*') {
-      if (glob[i + 1] === '*') {
-        re += '.*';
-        i++;
-        if (glob[i + 1] === '/') i++;
-      } else {
-        re += '[^/]*';
-      }
-    } else if (c === '?') {
-      re += '[^/]';
-    } else if ('.+^$()|{}[]\\'.includes(c)) {
-      re += '\\' + c;
-    } else {
-      re += c;
-    }
-  }
-  return new RegExp('^' + re + '$');
-}
+const { matchesRoute } = require('../routeGlob');
 
 function groupKind(kind, pluginId) {
   if (kind === 'docs') return 'docs';
@@ -172,8 +142,8 @@ function renderLlmsTxt({ siteConfig, siteUrl, trailingSlash, sections, options,
       // Absolute, as the llms.txt spec's examples are: the file is read
       // away from the site, where a relative link has no base.
       const url = companionsEnabled
-        ? companionUrl(siteUrl, item.permalink, trailingSlash)
-        : pageUrl(siteUrl, item.permalink);
+        ? companionUrl(siteUrl, item.permalink, trailingSlash, siteConfig.baseUrl)
+        : pageUrl(siteUrl, item.permalink, siteConfig.baseUrl);
       const desc = item.description || siteConfig.tagline || '';
       const titleText = item.title || item.permalink;
       if (desc) {
@@ -191,8 +161,10 @@ function renderLlmsTxt({ siteConfig, siteUrl, trailingSlash, sections, options,
   if (options.fullTxt && options.linkFullTxt !== false && companionsEnabled) {
     lines.push('## Optional');
     lines.push('');
+    // Next to this file: under the locale's base in a localized build.
+    const base = String(siteConfig.baseUrl || '/').replace(/\/+$/, '');
     lines.push(
-      `- [Full text of every page](${siteUrl}/llms-full.txt): one file with the content of every page listed above`,
+      `- [Full text of every page](${siteUrl}${base}/llms-full.txt): one file with the content of every page listed above`,
     );
     lines.push('');
   }
@@ -204,8 +176,8 @@ function renderLlmsTxt({ siteConfig, siteUrl, trailingSlash, sections, options,
 // the title, when the body does not already open with it). A plain
 // companion already carries both, so the header is skipped and the body
 // is emitted as is.
-function fullTxtBlock({ body, item, siteUrl }) {
-  const url = pageUrl(siteUrl, item.permalink);
+function fullTxtBlock({ body, item, siteUrl, baseUrl }) {
+  const url = pageUrl(siteUrl, item.permalink, baseUrl);
   const head = body.trimStart().split('\n', 8);
   const hasH1 = /^#\s+\S/.test(head[0] || '');
   const hasSource = head.some((l) => /^Source: \S/.test(l));
@@ -228,12 +200,14 @@ module.exports = async function emitLlmsTxt({
   const trailingSlash = siteConfig.trailingSlash;
   const siteUrl = (siteConfig.url || '').replace(/\/+$/, '');
 
-  // Filter the companions through include/exclude rules.
+  // Filter the companions through include/exclude rules. A pattern matches
+  // a route with or without siteConfig.baseUrl (see src/routeGlob.js), so
+  // the same patterns apply in every locale's build.
   const filtered = emittedCompanions.filter((item) => {
-    if (options.include && !options.include.some((p) => toRegExp(p).test(item.permalink))) {
+    if (options.include && !matchesRoute(item.permalink, options.include, siteConfig.baseUrl)) {
       return false;
     }
-    if (matchAny(item.permalink, options.exclude)) {
+    if (matchesRoute(item.permalink, options.exclude, siteConfig.baseUrl)) {
       return false;
     }
     return true;
@@ -297,7 +271,7 @@ module.exports = async function emitLlmsTxt({
           }
           continue;
         }
-        const block = fullTxtBlock({ body, item, siteUrl });
+        const block = fullTxtBlock({ body, item, siteUrl, baseUrl: siteConfig.baseUrl });
         const chunk = `${sectionOpen ? SEP : `${out ? SEP : ''}## ${section.title}\n\n`}${block}`;
         const bytes = Buffer.byteLength(chunk, 'utf8');
         if (full.maxBytes && size + bytes > full.maxBytes) {

package/src/helpers.js

@@ -3,18 +3,36 @@
 // These are pure data helpers - consumers spread them into other plugin
 // configs so that /ai/* routes don't pollute artifacts aimed at humans
 // (sitemaps, breadcrumb graphs, etc.).
+//
+// The convention is relative to the site's base URL. Docusaurus routes
+// carry it, so on a site built at '/docs/' the routes are '/docs/ai/...'
+// and in a localized build they are '/de/ai/...'. Every helper takes the
+// base URL as an optional argument; without one it means '/'.
+
+const { stripBase } = require('./companionPath');
 
-// Glob patterns matching the /ai/* convention. Suitable for plugins whose
-// exclude lists accept globs (notably @docusaurus/plugin-sitemap, which
-// uses `ignorePatterns`).
-const AI_ROUTE_PATTERNS = ['/ai', '/ai/**'];
+// Glob patterns matching the /ai/* convention under a base URL:
+// aiRoutePatterns('/de/') is ['/de/ai', '/de/ai/**']. Suitable for plugins
+// whose exclude lists accept globs and match full route paths (notably
+// @docusaurus/plugin-sitemap's `ignorePatterns`). One list can cover every
+// locale of a site:
+//   ignorePatterns: ['/', '/de/'].flatMap(aiRoutePatterns)
+function aiRoutePatterns(baseUrl) {
+  const base = String(baseUrl || '/').replace(/\/+$/, '');
+  return [`${base}/ai`, `${base}/ai/**`];
+}
 
-// Sitemap slice for @docusaurus/plugin-sitemap (standalone or via preset).
-// Usage:
+// The patterns for a site at the root with one locale.
+const AI_ROUTE_PATTERNS = aiRoutePatterns('/');
+
+// Sitemap slice for @docusaurus/plugin-sitemap (standalone or via preset),
+// for a site at the root with one locale. Usage:
 //   [
 //     '@docusaurus/plugin-sitemap',
 //     { ...sitemapExclude, /* your other sitemap options */ },
 //   ]
+// With a base URL or several locales, build `ignorePatterns` from
+// aiRoutePatterns instead.
 const sitemapExclude = {
   ignorePatterns: [...AI_ROUTE_PATTERNS],
 };
@@ -23,8 +41,8 @@ const sitemapExclude = {
 // excludedRoutes list for plugins that don't accept globs (e.g.
 // @stackql/docusaurus-plugin-structured-data, whose `excludedRoutes`
 // is an exact-match array).
-function isAiRoute(permalink) {
-  return typeof permalink === 'string' && permalink.startsWith('/ai/');
+function isAiRoute(permalink, baseUrl) {
+  return typeof permalink === 'string' && stripBase(permalink, baseUrl).startsWith('/ai/');
 }
 
 // Build an exact-match exclude list for @stackql/docusaurus-plugin-
@@ -48,13 +66,19 @@ function isAiRoute(permalink) {
 // If you don't have the route list at config time, list the known
 // /ai/* parents by hand (e.g. ['/ai', '/ai/faqs/install', ...]); the
 // glob-based AI_ROUTE_PATTERNS will NOT work for that plugin.
-function buildStructuredDataAiExcludes(allRoutePaths) {
+//
+// With a base URL, pass it as the second argument: the routes are matched
+// under it and the parent route returned is '<baseUrl>ai'.
+function buildStructuredDataAiExcludes(allRoutePaths, baseUrl) {
   if (!Array.isArray(allRoutePaths)) return [];
-  return allRoutePaths.filter(isAiRoute).concat(['/ai']);
+  return allRoutePaths
+    .filter((permalink) => isAiRoute(permalink, baseUrl))
+    .concat([aiRoutePatterns(baseUrl)[0]]);
 }
 
 module.exports = {
   AI_ROUTE_PATTERNS,
+  aiRoutePatterns,
   sitemapExclude,
   isAiRoute,
   buildStructuredDataAiExcludes,

package/src/index.js

@@ -182,6 +182,12 @@ module.exports = function pluginAeo(context, rawOptions) {
   const options = normalizeOptions(rawOptions);
   validateOptions(options);
 
+  // siteConfig.baseUrl for this build. Docusaurus constructs the plugin
+  // once per locale, and a localized build has its own base URL ('/de/');
+  // routes carry it, and the route conventions below are relative to it.
+  const baseUrl =
+    (context && ((context.siteConfig && context.siteConfig.baseUrl) || context.baseUrl)) || '/';
+
   // Captured from contentLoaded for downstream postBuild use.
   // Map<pluginName, { plugin: { name, id }, content: any }>
   const loadedContentByPlugin = new Map();
@@ -229,6 +235,7 @@ module.exports = function pluginAeo(context, rawOptions) {
       if (options.aiRoutes.validate) {
         validateAiRoutes({
           loadedContentByPlugin,
+          baseUrl,
           verbose: options.verbose,
         });
       }
@@ -238,7 +245,7 @@ module.exports = function pluginAeo(context, rawOptions) {
       // category indexes, React pages). Same list postBuild emits from.
       if (actions && typeof actions.setGlobalData === 'function') {
         const companionRoutes = options.companions.enabled
-          ? collectCompanionItems(loadedContentByPlugin, options.companions).map(
+          ? collectCompanionItems(loadedContentByPlugin, options.companions, baseUrl).map(
               (item) => item.permalink,
             )
           : [];

package/src/routeGlob.js

@@ -0,0 +1,60 @@
+// Route glob matching for the `exclude` / `include` options.
+//
+// A pattern describes a route of the site: '/blog/tags/**', '/search'.
+// Docusaurus permalinks carry siteConfig.baseUrl, and that differs between
+// builds of the same site: a localized build runs with baseUrl '/de/', so
+// the page a pattern names is '/de/blog/tags/x' there. A pattern is
+// therefore tried against the route with the base URL removed as well as
+// the route as Docusaurus reports it:
+//
+//   - one configuration covers every locale and any baseUrl, and
+//   - a pattern that spells the base out keeps working ('/docs/guide/**' on
+//     a site built at '/docs/') and can single out one locale
+//     ('/de/blog/**').
+//
+// Minimal matcher, to avoid pulling micromatch in directly: `**` matches
+// across path segments, `*` and `?` within one.
+
+const { stripBase } = require('./companionPath');
+
+function toRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if ('.+^$()|{}[]\\'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// True when `value` matches at least one glob. No patterns, no match.
+function matchAny(value, patterns) {
+  if (!patterns || patterns.length === 0) return false;
+  for (const p of patterns) {
+    if (toRegExp(p).test(value)) return true;
+  }
+  return false;
+}
+
+// True when a permalink matches at least one glob, with or without
+// `baseUrl` (siteConfig.baseUrl) in front of it.
+function matchesRoute(permalink, patterns, baseUrl) {
+  if (matchAny(permalink, patterns)) return true;
+  const relative = stripBase(permalink, baseUrl);
+  return relative !== permalink && matchAny(relative, patterns);
+}
+
+module.exports = { toRegExp, matchAny, matchesRoute };

package/src/theme/AskAiButton/index.jsx

@@ -8,6 +8,7 @@ import KeyboardArrowDownIcon from '@mui/icons-material/KeyboardArrowDown';
 import { useLocation } from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { usePluginData } from '@docusaurus/useGlobalData';
+import { translate } from '@docusaurus/Translate';
 import icons from './icons.js';
 import styles from './styles.module.css';
 // CommonJS, shared with the Node-side features so the button and the
@@ -15,14 +16,31 @@ import styles from './styles.module.css';
 import companionPathModule from '../../companionPath.js';
 import askAiPromptModule from '../../askAiPrompt.js';
 
-const { companionUrl, normalizeRoute } = companionPathModule;
+const { companionUrl, pageUrl: pageUrlFor, normalizeRoute } = companionPathModule;
 const { fillPrompt } = askAiPromptModule;
 
-const PROVIDER_LABELS = {
-  claude: 'Ask Claude',
-  chatgpt: 'Ask ChatGPT',
-  perplexity: 'Ask Perplexity',
-};
+// Visible strings go through translate() so a localized site can override
+// them in i18n/<locale>/code.json (`docusaurus write-translations` extracts
+// them from this theme component).
+function providerLabels() {
+  return {
+    claude: translate({
+      id: 'aeo.askAi.provider.claude',
+      message: 'Ask Claude',
+      description: 'Ask AI menu entry',
+    }),
+    chatgpt: translate({
+      id: 'aeo.askAi.provider.chatgpt',
+      message: 'Ask ChatGPT',
+      description: 'Ask AI menu entry',
+    }),
+    perplexity: translate({
+      id: 'aeo.askAi.provider.perplexity',
+      message: 'Ask Perplexity',
+      description: 'Ask AI menu entry',
+    }),
+  };
+}
 
 const PROVIDER_URLS = {
   claude: 'https://claude.ai/new?q=',
@@ -47,7 +65,9 @@ export default function AskAiButton() {
 
   const siteUrl = (siteConfig.url || '').replace(/\/+$/, '');
   const route = normalizeRoute(location.pathname);
-  const pageUrl = route === '/' ? siteUrl : `${siteUrl}${route}`;
+  // siteConfig.baseUrl is the locale's base (/de/) in a localized build, so
+  // the localized home page resolves like the site root.
+  const pageUrl = pageUrlFor(siteUrl, route, siteConfig.baseUrl);
 
   // Only pages with a companion get the button: a generated category index
   // or a React page has no .md file, so a prompt pointing at one would
@@ -62,7 +82,7 @@ export default function AskAiButton() {
     if (!known) return null;
   }
   const mdUrl = companionsEnabled
-    ? companionUrl(siteUrl, route, siteConfig.trailingSlash)
+    ? companionUrl(siteUrl, route, siteConfig.trailingSlash, siteConfig.baseUrl)
     : pageUrl;
 
   const promptTemplate = cfg.promptTemplate || DEFAULT_PROMPT_TEMPLATE;
@@ -76,6 +96,7 @@ export default function AskAiButton() {
 
   const handleOpen = (e) => setAnchorEl(e.currentTarget);
   const handleClose = () => setAnchorEl(null);
+  const labels = providerLabels();
 
   return (
     <div className={styles.dropdownWrapper}>
@@ -95,11 +116,16 @@ export default function AskAiButton() {
           color: 'var(--ifm-color-primary)',
           '&:hover': {
             borderColor: 'var(--ifm-color-primary)',
-            backgroundColor: 'rgba(0, 65, 101, 0.04)',
+            // a 4% tint of the site's own primary colour
+            backgroundColor: 'color-mix(in srgb, var(--ifm-color-primary) 4%, transparent)',
           },
         }}
       >
-        Ask AI about this page
+        {translate({
+          id: 'aeo.askAi.button',
+          message: 'Ask AI about this page',
+          description: 'Label of the Ask AI dropdown button',
+        })}
       </Button>
       <Menu
         anchorEl={anchorEl}
@@ -116,7 +142,7 @@ export default function AskAiButton() {
       >
         {order.map((key) => {
           const Icon = icons[key];
-          const label = PROVIDER_LABELS[key];
+          const label = labels[key];
           const base = PROVIDER_URLS[key];
           if (!base || !Icon) return null;
           const href = `${base}${encoded}`;