feat(search): upgrade DocSearch to v4

docs/src/content/docs/guides/site-search.mdx

@@ -199,36 +199,121 @@ Add translations of the modal UI for your language using Starlight’s built-in
 
    ```json title="src/content/i18n/en.json"
    {
-   	"docsearch.searchBox.resetButtonTitle": "Clear the query",
-   	"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
-   	"docsearch.searchBox.cancelButtonText": "Cancel",
-   	"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
+   	"docsearch.searchBox.clearButtonTitle": "Clear the query",
+   	"docsearch.searchBox.clearButtonAriaLabel": "Clear the query",
+   	"docsearch.searchBox.closeButtonText": "Close",
+   	"docsearch.searchBox.closeButtonAriaLabel": "Close",
+   	"docsearch.searchBox.placeholderText": "Search docs",
+   	"docsearch.searchBox.placeholderTextAskAi": "Ask AI: ",
+   	"docsearch.searchBox.placeholderTextAskAiStreaming": "Answering…",
    	"docsearch.searchBox.searchInputLabel": "Search",
+   	"docsearch.searchBox.backToKeywordSearchButtonText": "Back to keyword search",
+   	"docsearch.searchBox.backToKeywordSearchButtonAriaLabel": "Back to keyword search",
 
    	"docsearch.startScreen.recentSearchesTitle": "Recent",
    	"docsearch.startScreen.noRecentSearchesText": "No recent searches",
    	"docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
    	"docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
    	"docsearch.startScreen.favoriteSearchesTitle": "Favorite",
    	"docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",
+   	"docsearch.startScreen.recentConversationsTitle": "Recent conversations",
+   	"docsearch.startScreen.removeRecentConversationButtonTitle": "Remove this conversation from history",
 
    	"docsearch.errorScreen.titleText": "Unable to fetch results",
    	"docsearch.errorScreen.helpText": "You might want to check your network connection.",
 
    	"docsearch.footer.selectText": "to select",
+   	"docsearch.footer.submitQuestionText": "Submit question",
    	"docsearch.footer.selectKeyAriaLabel": "Enter key",
    	"docsearch.footer.navigateText": "to navigate",
    	"docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
    	"docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
    	"docsearch.footer.closeText": "to close",
+   	"docsearch.footer.backToSearchText": "Back to search",
    	"docsearch.footer.closeKeyAriaLabel": "Escape key",
-   	"docsearch.footer.searchByText": "Search by",
+   	"docsearch.footer.poweredByText": "Search by",
 
    	"docsearch.noResultsScreen.noResultsText": "No results for",
    	"docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
    	"docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
-   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know."
+   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know.",
+
+   	"docsearch.resultsScreen.askAiPlaceholder": "Ask AI: ",
+
+   	"docsearch.askAiScreen.disclaimerText": "Answers are generated by AI and may be inaccurate.",
+   	"docsearch.askAiScreen.relatedSourcesText": "Related sources",
+   	"docsearch.askAiScreen.thinkingText": "Thinking…",
+   	"docsearch.askAiScreen.copyButtonText": "Copy",
+   	"docsearch.askAiScreen.copyButtonCopiedText": "Copied!",
+   	"docsearch.askAiScreen.copyButtonTitle": "Copy",
+   	"docsearch.askAiScreen.likeButtonTitle": "Like",
+   	"docsearch.askAiScreen.dislikeButtonTitle": "Dislike",
+   	"docsearch.askAiScreen.thanksForFeedbackText": "Thanks for your feedback!",
+   	"docsearch.askAiScreen.preToolCallText": "Searching…",
+   	"docsearch.askAiScreen.duringToolCallText": "Searching ",
+   	"docsearch.askAiScreen.afterToolCallText": "Searched",
+   	"docsearch.askAiScreen.aggregatedToolCallText": "Searched"
    }
    ```
 
 </Steps>
+
+### Algolia Ask&nbsp;AI
+
+DocSearch v4 introduces an optional **Ask AI** conversational experience. To enable it, pass the `askAi` option to the Starlight DocSearch plugin — either as a plain string (your **assistant ID**) or as an object with overrides:
+
+```ts title="astro.config.mjs" ins={15-20}
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightDocSearch from '@astrojs/starlight-docsearch';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightDocSearch({
+          appId: 'YOUR_APP_ID',
+          apiKey: 'YOUR_SEARCH_API_KEY',
+          indexName: 'YOUR_INDEX_NAME',
+          // simplest form — just the assistant ID
+          // askAi: 'YOUR_ASSISTANT_ID',
+
+          // or full form with per-assistant overrides
+          askAi: {
+            assistantId: 'YOUR_ASSISTANT_ID',
+            // apiKey, appId & indexName default to the top-level values
+            // but can be overridden individually if needed
+            // apiKey: '...',
+            // appId: '...',
+            // indexName: '...',
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+If you want to stick with keyword search only, simply omit the `askAi` property.
+
+#### Translating the Ask AI UI
+
+Ask AI adds a few extra UI texts. Add them to your `i18n` JSON alongside the earlier DocSearch strings:
+
+```json title="src/content/i18n/en.json"{8}
+{
+  // …previous DocSearch strings…
+  "docsearch.resultsScreen.askAiPlaceholder": "Ask AI: ",
+  "docsearch.searchBox.placeholderTextAskAi": "Ask AI: ",
+  "docsearch.askAiScreen.disclaimerText": "Answers are generated by AI and may be inaccurate.",
+  "docsearch.askAiScreen.relatedSourcesText": "Related sources",
+  "docsearch.askAiScreen.thinkingText": "Thinking…",
+  "docsearch.askAiScreen.copyButtonText": "Copy",
+  "docsearch.askAiScreen.copyButtonCopiedText": "Copied!",
+  "docsearch.askAiScreen.thanksForFeedbackText": "Thanks for your feedback!",
+  "docsearch.footer.submitQuestionText": "Submit question",
+  "docsearch.footer.backToSearchText": "Back to search"
+}
+```
+
+See the [Ask AI documentation](https://docsearch.algolia.com/docs/v4/askai) for full details.

packages/docsearch/DocSearch.astro

@@ -1,12 +1,113 @@
 ---
 import '@docsearch/css/dist/modal.css';
-import type docsearch from '@docsearch/js';
 import './variables.css';
 
-type DocSearchTranslationProps = Pick<
-	Parameters<typeof docsearch>[0],
-	'placeholder' | 'translations'
->;
+export interface DocSearchTranslations {
+	button?: ButtonTranslations;
+	modal?: ModalTranslations;
+}
+
+export interface ButtonTranslations {
+	buttonText?: string;
+	buttonAriaLabel?: string;
+}
+
+export interface ModalTranslations extends ScreenStateTranslations {
+	searchBox?: SearchBoxTranslations;
+	footer?: FooterTranslations;
+}
+
+export interface ScreenStateTranslations {
+	errorScreen?: ErrorScreenTranslations;
+	startScreen?: StartScreenTranslations;
+	resultsScreen?: ResultsScreenTranslations;
+	noResultsScreen?: NoResultsScreenTranslations;
+	askAiScreen?: AskAiScreenTranslations;
+}
+
+export interface SearchBoxTranslations {
+	clearButtonTitle?: string;
+	clearButtonAriaLabel?: string;
+	closeButtonText?: string;
+	closeButtonAriaLabel?: string;
+	placeholderText?: string;
+	placeholderTextAskAi?: string;
+	searchInputLabel?: string;
+	placeholderTextAskAiStreaming?: string;
+	backToKeywordSearchButtonText?: string;
+	backToKeywordSearchButtonAriaLabel?: string;
+}
+
+export interface FooterTranslations {
+	selectText?: string;
+	submitQuestionText?: string;
+	selectKeyAriaLabel?: string;
+	navigateText?: string;
+	navigateUpKeyAriaLabel?: string;
+	backToSearchText?: string;
+	navigateDownKeyAriaLabel?: string;
+	closeText?: string;
+	closeKeyAriaLabel?: string;
+	poweredByText?: string;
+}
+
+export interface ErrorScreenTranslations {
+	titleText?: string;
+	helpText?: string;
+}
+
+export interface StartScreenTranslations {
+	recentSearchesTitle?: string;
+	noRecentSearchesText?: string;
+	saveRecentSearchButtonTitle?: string;
+	removeRecentSearchButtonTitle?: string;
+	favoriteSearchesTitle?: string;
+	removeFavoriteSearchButtonTitle?: string;
+	recentConversationsTitle?: string;
+	removeRecentConversationButtonTitle?: string;
+}
+
+export interface ResultsScreenTranslations {
+	askAiPlaceholder?: string;
+}
+
+export interface NoResultsScreenTranslations {
+	noResultsText?: string;
+	suggestedQueryText?: string;
+	reportMissingResultsText?: string;
+	reportMissingResultsLinkText?: string;
+}
+
+export interface AskAiScreenTranslations {
+	disclaimerText?: string;
+	relatedSourcesText?: string;
+	thinkingText?: string;
+	copyButtonText?: string;
+	copyButtonCopiedText?: string;
+	copyButtonTitle?: string;
+	likeButtonTitle?: string;
+	dislikeButtonTitle?: string;
+	thanksForFeedbackText?: string;
+	preToolCallText?: string;
+	duringToolCallText?: string;
+	afterToolCallText?: string;
+	aggregatedToolCallText?: string;
+}
+
+export interface DocSearchProps {
+	appId: string;
+	apiKey: string;
+	indexName: string;
+	placeholder?: string;
+	searchParameters?: any;
+	disableUserPersonalization?: boolean;
+	initialQuery?: string;
+	insights?: boolean;
+	translations?: DocSearchTranslations;
+	askAi?: any;
+	theme?: 'dark' | 'light';
+}
+type DocSearchTranslationProps = Pick<DocSearchProps, 'placeholder' | 'translations'>;
 
 const pick = (keyStart: string) =>
 	Object.fromEntries(
@@ -130,12 +231,59 @@ const docsearchTranslations: DocSearchTranslationProps = {
 			super();
 			window.addEventListener('DOMContentLoaded', async () => {
 				const { default: docsearch } = await import('@docsearch/js');
-				const options = { ...config, container: 'sl-doc-search' };
+				let translations;
 				try {
-					const translations = JSON.parse(this.dataset.translations || '{}');
-					Object.assign(options, translations);
+					translations = JSON.parse(this.dataset.translations || '{}');
 				} catch {}
-				docsearch(options);
+
+				// Extract the page language (e.g. <html lang="en">) and pass it to DocSearch
+				// as an Algolia facet filter so that the search results are scoped to the current
+				// language. If users already defined facet filters we preserve them while appending
+				// the new one.
+				let searchParameters: Record<string, any> | undefined;
+
+				// Rebuild the askAi prop as an object:
+				// If the askAi prop is a string, treat it as the assistantId and use
+				// the default indexName, apiKey and appId from the main options.
+				// If the askAi prop is an object, spread its explicit values.
+				const askAiProp = config.askAi;
+				const isAskAiString = typeof askAiProp === 'string';
+
+				const askAi = askAiProp
+					? {
+							indexName: isAskAiString ? config.indexName : askAiProp.indexName,
+							apiKey: isAskAiString ? config.apiKey : askAiProp.apiKey,
+							appId: isAskAiString ? config.appId : askAiProp.appId,
+							assistantId: isAskAiString ? askAiProp : askAiProp.assistantId,
+							searchParameters: {},
+						}
+					: undefined;
+
+				const pageLang = document.documentElement.getAttribute('lang');
+				if (pageLang) {
+					searchParameters = config.searchParameters || {};
+					const existingFilters = searchParameters?.facetFilters ?? [];
+					// Ensure facetFilters is always an array of strings for simplicity.
+					searchParameters.facetFilters = Array.isArray(existingFilters)
+						? [...existingFilters, `lang:${pageLang}`]
+						: [existingFilters, `lang:${pageLang}`].filter(Boolean);
+
+					if (askAi) {
+						// Re-use the merged facetFilters from the search parameters so that
+						// Ask AI uses the same language filtering as the regular search.
+						askAi.searchParameters = { facetFilters: searchParameters.facetFilters };
+					}
+
+					const options = {
+						...config,
+						container: 'sl-doc-search',
+						translations,
+						searchParameters,
+						askAi,
+					};
+
+					docsearch(options);
+				}
 			});
 		}
 	}

packages/docsearch/README.md

@@ -2,6 +2,8 @@
 
 Algolia DocSearch plugin for the [Starlight][starlight] documentation theme for [Astro][astro].
 
+Supports DocSearch v4 with optional **Ask AI** conversational search.
+
 ## Documentation
 
 See the [Starlight site search guide][docs] for how to use this plugin.