jamdesk 1.1.37 → 1.1.38

package/vendored/app/[[...slug]]/page.tsx

@@ -48,7 +48,6 @@ import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
 import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import fs from 'fs';
 import path from 'path';
-import matter from 'gray-matter';
 import { getContentDir } from '@/lib/docs';
 import type { DocsConfig } from '@/lib/docs-types';
 import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
@@ -61,7 +60,6 @@ import {
   normalizeSlugForContent,
   parseFrontmatter,
   projectExists,
-  type ContentLoader,
 } from '@/lib/content-loader';
 import { getBaseUrl, pathToSlug } from '@/lib/page-isr-helpers';
 import {
@@ -70,6 +68,7 @@ import {
   parseEndpoint,
   generateCodeExamples,
   formatOpenApiWarning,
+  deriveAuthFromSecurity,
   type OpenApiEndpointData,
   type CodeExample,
   type AuthMethod,
@@ -134,6 +133,22 @@ function resolveBaseUrl(
   return process.env.SITE_URL || DEFAULT_SITE_URL;
 }
 
+/**
+ * docs.json override is treated as a UNIT — if method is set, both method and name
+ * come from docs.json, avoiding a stale customer-set `name` pairing with a
+ * spec-derived `method`. Falls back to deriving auth from the OpenAPI security schemes.
+ */
+function resolveAuth(
+  endpoint: OpenApiEndpointData | null | undefined,
+  config: DocsConfig,
+): { method?: AuthMethod; headerName?: string } {
+  const override = config.api?.mdx?.auth;
+  if (override?.method) {
+    return { method: override.method, headerName: override.name };
+  }
+  return endpoint ? deriveAuthFromSecurity(endpoint.security) : {};
+}
+
 /**
  * Frontmatter data from MDX files.
  */
@@ -548,9 +563,9 @@ export default async function DocPage({ params }: PageProps) {
 
       // Generate code examples
       if (openApiEndpointData) {
-        const authMethod = config.api?.mdx?.auth?.method as AuthMethod | undefined;
+        const { method: authMethod, headerName: authHeaderName } = resolveAuth(openApiEndpointData, config);
         const languages = config.api?.examples?.languages;
-        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, languages });
+        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, authHeaderName, languages });
       }
     } catch (err) {
       const typed = classifyOpenApiLoadError(err, lastFailure?.specPath ?? null);
@@ -616,6 +631,9 @@ export default async function DocPage({ params }: PageProps) {
     mdxEndpointData = buildEndpointFromMdx(mdxApiMethod, mdxApiPath, paramFields, fallbackServerUrl);
   }
 
+  const resolvedMdxAuth = resolveAuth(mdxEndpointData, config);
+  const resolvedOpenApiAuth = resolveAuth(openApiEndpointData, config);
+
   // For API pages, wrap the entire content area with ApiPageWrapper
   // so code panels can be positioned as siblings at the page level
   if (isApiPage) {
@@ -653,8 +671,8 @@ export default async function DocPage({ params }: PageProps) {
                   endpoint={mdxEndpointData}
                   playgroundOnly
                   playgroundDisplay={playgroundDisplay}
-                  authMethod={config.api?.mdx?.auth?.method as AuthMethod | undefined}
-                  authHeaderName={config.api?.mdx?.auth?.name}
+                  authMethod={resolvedMdxAuth.method}
+                  authHeaderName={resolvedMdxAuth.headerName}
                   serverUrl={fallbackServerUrl}
                   proxyEnabled={proxyEnabled}
                   languages={config.api?.examples?.languages}
@@ -674,8 +692,8 @@ export default async function DocPage({ params }: PageProps) {
                 endpoint={openApiEndpointData}
                 codeExamples={openApiCodeExamples || undefined}
                 playgroundDisplay={playgroundDisplay}
-                authMethod={config.api?.mdx?.auth?.method as AuthMethod | undefined}
-                authHeaderName={config.api?.mdx?.auth?.name}
+                authMethod={resolvedOpenApiAuth.method}
+                authHeaderName={resolvedOpenApiAuth.headerName}
                 serverUrl={fallbackServerUrl}
                 proxyEnabled={proxyEnabled}
                 languages={config.api?.examples?.languages}

package/vendored/app/api/chat/[project]/route.ts

@@ -30,6 +30,7 @@ import { rewriteQueryForSearch } from '@/lib/query-rewriter';
 import { fetchDocsConfig } from '@/lib/r2-content';
 import { redis } from '@/lib/redis';
 import { CHAT_TOOLS } from '@/lib/chat-tools';
+import { rewriteSlugLinks } from '@/lib/link-rewriter';
 import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
@@ -43,6 +44,7 @@ const MAX_HISTORY = 10;
  *  Used both for searchQuery enrichment and to skip the rewriter. */
 const SHORT_FOLLOWUP_LEN = 60;
 const VALID_ROLES = new Set<string>(['user', 'assistant']);
+const VALID_LOCALE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
 
 export async function POST(
   request: NextRequest,
@@ -75,7 +77,7 @@ export async function POST(
     }
   }
 
-  let body: { message: unknown; history?: unknown[] };
+  let body: { message: unknown; history?: unknown[]; locale?: unknown };
   try {
     body = await request.json();
   } catch {
@@ -88,6 +90,14 @@ export async function POST(
     return Response.json({ error: 'Invalid message' }, { status: 400 });
   }
 
+  let clientLocale: string | undefined;
+  if (body.locale !== undefined) {
+    if (typeof body.locale !== 'string' || !VALID_LOCALE_RE.test(body.locale)) {
+      return Response.json({ error: 'Invalid locale' }, { status: 400 });
+    }
+    clientLocale = body.locale;
+  }
+
   // Sanitize history: only allow valid roles, string content, capped length
   const history = (Array.isArray(rawHistory) ? rawHistory : [])
     .filter((h): h is { role: 'user' | 'assistant'; content: string } => {
@@ -122,6 +132,29 @@ export async function POST(
     fetchDocsConfig(project).catch(() => null),
   ]);
 
+  // Per-project rollout gate. Filter applies ONLY when the client sent a
+  // locale AND the project is opted in. Both default to off so this is a
+  // safe deploy. Set the flag with: redis-cli SET chatLocaleFilter:<slug> true
+  //
+  // Skip the Redis read entirely when no client locale was sent — the filter
+  // can never apply, so the round-trip would just block vector queries for
+  // nothing. This matters because the vector query path below depends on
+  // `effectiveLocale` and would otherwise wait on this read serially.
+  const localeFilterEnabled = clientLocale && redis
+    ? await redis.get(`chatLocaleFilter:${project}`)
+        .then((v) => v === 'true')
+        .catch((err) => {
+          // Fail-open is intentional (don't 500 chat on a Redis blip), but
+          // SREs need a signal — without this log, intermittent Redis
+          // outages silently regress the locale-pollution fix.
+          log('warn', 'chat: locale flag read failed, defaulting filter off', {
+            project, error: String(err),
+          });
+          return false;
+        })
+    : false;
+  const effectiveLocale = (localeFilterEnabled && clientLocale) ? clientLocale : undefined;
+
   // Fully parallel retrieval:
   //   - Original vector query runs immediately.
   //   - Rewriter + rewritten-query vector search are chained into ONE promise,
@@ -130,7 +163,8 @@ export async function POST(
   //     max(original, rewriter) + rewritten_query_time.
   // Any failure in the rewrite path resolves to an empty chunk list — the
   // original query still returns results so chat doesn't fail.
-  const originalQueryPromise = querySimilarChunks(project, searchQuery, 15);
+
+  const originalQueryPromise = querySimilarChunks(project, searchQuery, 15, { locale: effectiveLocale });
 
   // Skipping the rewriter on short follow-ups avoids 500-2000ms of serial
   // Anthropic latency — `searchQuery` above is already enriched with prior-turn
@@ -145,7 +179,7 @@ export async function POST(
             // (which is enriched with prior-turn context for short follow-ups).
             // The rewriter only sees `message`, so a no-op rewrite equals `message`.
             if (!rewritten || rewritten === message) return [];
-            return querySimilarChunks(project, rewritten, 15).catch(() => []);
+            return querySimilarChunks(project, rewritten, 15, { locale: effectiveLocale }).catch(() => []);
           });
 
   let originalChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
@@ -196,6 +230,12 @@ export async function POST(
   const baseUrl = getBaseUrl(project, originalHost);
   const siteName = resolveSiteName(config);
 
+  // Map of pageSlug → canonical absolute URL, consumed by rewriteSlugLinks
+  // after the stream completes to canonicalize Haiku-generated link targets.
+  const slugToUrl: Record<string, string> = Object.fromEntries(
+    chunks.map((c) => [c.pageSlug, `${baseUrl}${docsPath}/${c.pageSlug}`]),
+  );
+
   const systemPrompt = buildSystemPrompt(siteName, chunks, baseUrl, docsPath);
 
   const stream = anthropic.messages.stream({
@@ -344,6 +384,16 @@ export async function POST(
             : explicitSources.length > 0
               ? explicitSources
               : topChunksAsCitations(2, seen);
+
+          // Two-pass URL rewrite: stream raw markdown live (for typing-effect
+          // UX), then emit a `text_replace` event with canonical absolute URLs
+          // once we have the full final markdown. Brief artifact: between the
+          // last text chunk and this event the user sees rendered slug-form
+          // URLs. Skip the event when nothing changed.
+          const rewrittenMarkdown = rewriteSlugLinks(markdownText, slugToUrl);
+          if (rewrittenMarkdown !== markdownText) {
+            controller.enqueue(sendEvent({ type: 'text_replace', content: rewrittenMarkdown }));
+          }
         } else if (toolUse.name === 'ask_clarification') {
           const input = toolUse.input as ClarificationInput;
           const options = Array.isArray(input.options) ? input.options : [];

package/vendored/app/api/docs-search/[project]/search/route.ts

@@ -20,6 +20,9 @@ import { querySimilarChunks } from '@/lib/vector-store';
 import { verifyApiKey } from '@/lib/docs-search-auth';
 import { getBaseUrl, trackServerAnalytics } from '@/lib/route-helpers';
 import { redis } from '@/lib/redis';
+import { fetchDocsConfig } from '@/lib/r2-content';
+import { isMultiLanguageConfig } from '@/lib/navigation-utils';
+import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
 export const maxDuration = 30;
@@ -34,6 +37,11 @@ const MAX_LIMIT = 20;
 const DEFAULT_LIMIT = 5;
 const MAX_QUERY_LENGTH = 500;
 const RATE_LIMIT_PER_MIN = 60;
+/** BCP-47-ish: 2-3 letter primary tag, optional 2-4 letter region/script.
+ *  Matches the chat endpoint's VALID_LOCALE_RE — keep both contracts in sync.
+ *  Limitation: 3-segment tags like `zh-Hant-HK` are rejected. Documented. */
+const VALID_LANGUAGE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
+const DEFAULT_LANGUAGE = 'en';
 
 export async function OPTIONS(_request: NextRequest) {
   return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
@@ -89,7 +97,7 @@ export async function POST(
   }
 
   // --- Parse & validate request body ---
-  let body: { query?: string; limit?: number };
+  let body: { query?: string; limit?: number; language?: unknown };
   try {
     body = await request.json();
   } catch {
@@ -101,6 +109,23 @@ export async function POST(
 
   const { query, limit: rawLimit } = body;
 
+  // Validate language. `null` and `undefined` both default to 'en'
+  // (real-world clients send `language: null` from `?? null` fallbacks —
+  // rejecting them as 400 would be gratuitous). A non-string value or a
+  // string that doesn't match the BCP-47 pattern is a 400.
+  let language: string = DEFAULT_LANGUAGE;
+  let languageWasExplicit = false;
+  if (body.language != null) {
+    if (typeof body.language !== 'string' || !VALID_LANGUAGE_RE.test(body.language)) {
+      return NextResponse.json(
+        { error: 'Invalid language code' },
+        { status: 400, headers: CORS_HEADERS },
+      );
+    }
+    language = body.language;
+    languageWasExplicit = true;
+  }
+
   if (!query || typeof query !== 'string' || query.trim().length === 0) {
     return NextResponse.json(
       { error: 'Missing or empty "query" field' },
@@ -125,11 +150,66 @@ export async function POST(
     MAX_LIMIT,
   );
 
+  // --- Multi-language gate ---
+  // Apply the locale filter only when the project is configured for
+  // multiple languages AND the per-project kill switch is not set.
+  // Single-language projects' chunks have no locale metadata, so the
+  // strict filter would return zero. Run the config fetch and kill-switch
+  // read in parallel — fetchDocsConfig has a 5-min in-memory cache, and
+  // Redis is the bottleneck only on a cold cache. .catch() on the kill
+  // switch keeps a Redis blip from breaking searches.
+  const killSwitchPromise: Promise<boolean> = redis
+    ? redis.get(`searchLocaleFilter:${project}`)
+        .then((v) => v === 'disabled')
+        .catch(() => false)
+    : Promise.resolve(false);
+
+  let config: Awaited<ReturnType<typeof fetchDocsConfig>>;
+  let killSwitch: boolean;
+  try {
+    [config, killSwitch] = await Promise.all([
+      fetchDocsConfig(project),
+      killSwitchPromise,
+    ]);
+  } catch (err) {
+    // R2 outage — config unavailable. Asymmetric fail-mode:
+    //  - Caller sent an explicit language: 503 (don't silently leak
+    //    cross-language results to a caller who asked for filtering).
+    //  - Caller defaulted to 'en': fall back to today's no-filter behavior
+    //    so docs sites keep working through R2 incidents.
+    log('error', 'docs-search: fetchDocsConfig failed', {
+      project,
+      error: String(err),
+      languageWasExplicit,
+    });
+    if (languageWasExplicit) {
+      return NextResponse.json(
+        { error: 'Search temporarily unavailable' },
+        { status: 503, headers: CORS_HEADERS },
+      );
+    }
+    config = null;
+    killSwitch = await killSwitchPromise.catch(() => false);
+  }
+
+  if (killSwitch) {
+    // Operators have flipped the kill switch for this project — log so we
+    // can spot escapes. Not an error, but worth surfacing.
+    log('warn', 'docs-search: locale filter kill switch is enabled', {
+      project,
+    });
+  }
+
+  const applyLocaleFilter = !killSwitch && !!config && isMultiLanguageConfig(config);
+  const effectiveLocale = applyLocaleFilter ? language : undefined;
+
   // --- Semantic vector search ---
   const startMs = Date.now();
   let chunks;
   try {
-    chunks = await querySimilarChunks(project, query.trim(), limit);
+    chunks = await querySimilarChunks(project, query.trim(), limit, {
+      locale: effectiveLocale,
+    });
   } catch (err) {
     console.error('Vector search failed:', err);
     return NextResponse.json(
@@ -162,7 +242,7 @@ export async function POST(
   });
 
   return NextResponse.json(
-    { results, query: query.trim(), total: results.length, durationMs },
+    { results, query: query.trim(), language, total: results.length, durationMs },
     { status: 200, headers: CORS_HEADERS },
   );
 }

package/vendored/components/mdx/OpenApiEndpoint.tsx

@@ -11,6 +11,7 @@ import { CodePanel, CodePanelTab, getStatusColor } from '../ui/CodePanel';
 import { useShikiHighlightMultiple } from '@/hooks/useShikiHighlight';
 import { preloadHighlighter } from '@/lib/shiki-client';
 import ReactMarkdown from 'react-markdown';
+import { resolveServerUrl } from '@/lib/openapi/resolve-server-url';
 // Icons use Font Awesome CSS classes for lightweight rendering
 import type {
   OpenApiEndpointData,
@@ -916,7 +917,7 @@ export function OpenApiEndpoint({
   const headerParams = parameters.filter(p => p.in === 'header');
   const cookieParams = parameters.filter(p => p.in === 'cookie');
 
-  const baseUrl = servers[0]?.url;
+  const baseUrl = resolveServerUrl(servers[0]);
 
   // Playground state
   const showPlayground = playgroundDisplay !== 'none';

package/vendored/components/search/SearchModal.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useState, useRef, type ReactElement } from 'react';
-import { useRouter } from 'next/navigation';
+import { useRouter, usePathname } from 'next/navigation';
 import { getRecentSearches, addRecentSearch, clearRecentSearches } from '@/lib/recent-searches';
 import { useFocusTrap } from '@/hooks/useFocusTrap';
 import { useBodyScrollLock } from '@/hooks/useBodyScrollLock';
@@ -9,16 +9,7 @@ import { getSuggestions } from '@/lib/search-suggestions';
 import { trackSearch } from '@/lib/analytics-client';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import { useProjectSlug } from '@/lib/project-slug-context';
-
-interface SearchResult {
-  id: string;
-  title: string;
-  description?: string;
-  content: string;
-  slug: string;
-  section?: string;
-  type?: 'api' | 'component' | 'guide' | 'help' | 'quickstart';
-}
+import type { SearchResult } from '@/lib/search-client';
 
 interface PopularPage {
   title: string;
@@ -102,6 +93,7 @@ function NoResultsState({ query, onSuggestionClick }: { query: string; onSuggest
 export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: SearchModalProps) {
   const linkPrefix = useLinkPrefix();
   const projectSlug = useProjectSlug();
+  const pathname = usePathname() ?? '';
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<SearchResult[]>([]);
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -210,8 +202,9 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
     const timer = setTimeout(async () => {
       try {
-        const { search } = await import('@/lib/search-client');
-        const searchResults = await search(query, 15);
+        const { search, resolveActiveLocale } = await import('@/lib/search-client');
+        const activeLocale = resolveActiveLocale(pathname);
+        const searchResults = await search(query, 15, activeLocale);
         if (!cancelled) {
           setResults(searchResults);
           setSelectedIndex(0);
@@ -235,7 +228,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [query]);
+  }, [query, pathname]);
 
   // Scroll selected result into view
   useEffect(() => {

package/vendored/hooks/useChat.ts

@@ -3,6 +3,7 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import { createTextStreamPacer, type TextStreamPacer } from './useTextStreamPacer';
 import { useMediaQuery } from './useMediaQuery';
+import { extractLanguageFromPath } from '@/lib/language-utils';
 
 export interface Citation {
   title: string;
@@ -120,13 +121,13 @@ export function useChat(endpoint = '/_chat'): {
   const markRevealComplete = useCallback(
     (
       assistantId: string,
-      pending: { citations?: Citation[]; clarificationOptions?: string[] },
+      pending: { citations?: Citation[]; clarificationOptions?: string[]; replacedContent?: string },
     ): void => {
       setMessages((prev) => {
         const idx = prev.findIndex((m) => m.id === assistantId);
         if (idx === -1) return prev;
         const msg = prev[idx];
-        if (!msg.content) {
+        if (!msg.content && !pending.replacedContent) {
           // Empty bubble — drop it entirely.
           return prev.filter((m) => m.id !== assistantId);
         }
@@ -134,6 +135,7 @@ export function useChat(endpoint = '/_chat'): {
         next[idx] = {
           ...msg,
           isStreaming: false,
+          ...(pending.replacedContent !== undefined ? { content: pending.replacedContent } : {}),
           ...(pending.citations ? { citations: pending.citations } : {}),
           ...(pending.clarificationOptions
             ? { clarificationOptions: pending.clarificationOptions }
@@ -154,7 +156,7 @@ export function useChat(endpoint = '/_chat'): {
       // Citations + clarifications arrive instantly from the server but we
       // want them to appear only after the prose is finished revealing —
       // otherwise the badges/buttons render above text that hasn't been typed.
-      const pending: { citations?: Citation[]; clarificationOptions?: string[] } = {};
+      const pending: { citations?: Citation[]; clarificationOptions?: string[]; replacedContent?: string } = {};
 
       const pacer = createTextStreamPacer({
         reducedMotion,
@@ -210,6 +212,15 @@ export function useChat(endpoint = '/_chat'): {
                 pacer.enqueue(event.content || '');
                 break;
 
+              case 'text_replace':
+                // Server has finalized the markdown (e.g. rewrote slug links to
+                // absolute URLs). Buffer it here and apply at reveal-end so it
+                // doesn't snap mid-typing-animation. Brief artifact: between the
+                // last text chunk and reveal-end, the user sees the pre-rewrite
+                // markdown rendered with non-canonical URLs.
+                pending.replacedContent = event.content || '';
+                break;
+
               case 'citations':
                 pending.citations = event.sources;
                 break;
@@ -304,11 +315,18 @@ export function useChat(endpoint = '/_chat'): {
         ? '/docs/_chat'
         : endpoint;
 
+      // extractLanguageFromPath returns undefined for root-level paths (default
+      // language). We omit `locale` in that case rather than guessing — the server
+      // only filters when a locale is explicitly sent AND the per-project flag is
+      // on, so omitting is the correct "use whatever you have, no filter" signal
+      // that's safe across mid-rollout client deployments.
+      const locale = extractLanguageFromPath(window.location.pathname);
+
       try {
         const response = await fetch(chatUrl, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ message: trimmed, history }),
+          body: JSON.stringify(locale ? { message: trimmed, history, locale } : { message: trimmed, history }),
           signal: controller.signal,
         });
 

package/vendored/lib/chat-prompt.ts

@@ -99,7 +99,7 @@ Rules:
 - Use markdown formatting, including code blocks with language hints when showing code.
 - Never make up information not in the context.
 - Pick one of exactly two response shapes, based on whether any page in the Documentation context below is relevant to the question:
-  (a) RELEVANT PAGE EXISTS → answer by referring to it with a markdown link (e.g., "See [Changelog](.../changelog) for recent releases."). Do NOT prefix with "I don't have information".
+  (a) RELEVANT PAGE EXISTS → answer by referring to it with a markdown link. The link's URL must be either the pageSlug (e.g. "See [OpenAPI Example](api-reference/openapi-example) for a live endpoint page.") OR the full URL from the URL: line of the cited chunk. The system rewrites both forms to the canonical absolute URL automatically. Never invent a URL or use a relative path like ./ or ../. Do NOT prefix with "I don't have information".
   (b) NO RELEVANT PAGE → respond with this exact sentence and stop: "I don't have information about that in the documentation." Do not add "However", "but", "you could try", or any follow-up suggestion after it. The reply ends at the period.
   WRONG: "I don't have information about that in the documentation. However, if you're asking about X, you could..." ← This is forbidden. If the first sentence is true, stop there.
 - Never name a page ("the Changelog", "the API reference", "the Settings page", etc.) unless that page appears in the Documentation context below.

package/vendored/lib/chat-tools.ts

@@ -64,6 +64,9 @@ export const ANSWER_TOOL: AnswerToolSchema = {
         type: 'string',
         description:
           'The answer in markdown. Use code blocks with language hints when showing code. ' +
+          'When linking to a documentation page, prefer the pageSlug (from the [pageSlug: ...] label) as the URL: ' +
+          '[Anchor Text](api-reference/openapi-example). The full URL from the URL: line also works. ' +
+          'The system rewrites either form to the canonical absolute URL after generation. ' +
           'Do not embed citation text like "[Page Title]" — citations are listed in cited_page_slugs.',
       },
       cited_page_slugs: {

package/vendored/lib/embedding-chunker.ts

@@ -6,6 +6,13 @@
  * first, then at sentence boundaries for oversized sections.
  */
 import { extractSections } from './static-artifacts.js';
+import {
+  deriveChunkLocale,
+  normalizeLanguageList,
+  type LanguageEntry,
+} from './locale-helpers.js';
+
+export { normalizeLanguageList };
 
 export interface EmbeddingChunk {
   /** Unique ID: `${pageSlug}#${sectionIndex}` */
@@ -25,6 +32,9 @@ export interface EmbeddingChunk {
   prefix: string;
   /** Page title from frontmatter, or slug-derived fallback */
   pageTitle: string;
+  /** Locale derived from i18n config + leading slug segment. `null` for
+   *  single-language projects (no `i18n.languages` configured). */
+  locale: string | null;
 }
 
 /**
@@ -200,16 +210,21 @@ function sanitizeHeadingText(raw: string): string {
  * Chunk a documentation page into embedding-sized pieces.
  *
  * @param page - Page with file path, raw MDX content, and frontmatter
- * @param maxChars - Maximum characters per chunk (default 2000, ~500 tokens)
+ * @param options - maxChars cap (default 2000, ~500 tokens) and i18n languages
+ *                  (used to derive each chunk's locale tag)
  * @returns Array of embedding chunks with unique IDs
  */
 export function chunkPageForEmbedding(
   page: { path: string; content: string; frontmatter: Record<string, unknown> },
-  maxChars = 2000,
+  options: { maxChars?: number; languages?: LanguageEntry[] } = {},
 ): EmbeddingChunk[] {
+  const maxChars = options.maxChars ?? 2000;
+  const languages = options.languages ?? [];
+
   const slug = page.path.replace(/\.mdx?$/, '').replace(/\\/g, '/');
   const rawTitle = (page.frontmatter.title as string) || titleFromSlug(slug);
   const pageTitle = sanitizeHeadingText(rawTitle) || titleFromSlug(slug);
+  const locale = deriveChunkLocale(page.path, languages);
 
   // Normalize Windows line endings before extracting sections
   const normalizedContent = preprocessUpdateBlocks(page.content.replace(/\r\n/g, '\n'));
@@ -238,6 +253,7 @@ export function chunkPageForEmbedding(
         content: piece,
         prefix,
         pageTitle,
+        locale,
       });
       chunkIndex++;
     }

package/vendored/lib/language-codes.json

@@ -0,0 +1,27 @@
+[
+  "en",
+  "cn", "zh", "zh-Hans", "zh-Hant",
+  "es",
+  "fr", "fr-CA", "fr-ca",
+  "ja", "jp", "ja-jp",
+  "pt", "pt-BR",
+  "de",
+  "ko",
+  "it",
+  "ru",
+  "ro",
+  "cs",
+  "id",
+  "ar",
+  "tr",
+  "hi",
+  "sv",
+  "no",
+  "lv",
+  "nl",
+  "uk",
+  "vi",
+  "pl",
+  "uz",
+  "he"
+]