From a35717ddf37c587fb39061d656a2e09372b77873 Mon Sep 17 00:00:00 2001
From: Dan Stillman <dstillman@zotero.org>
Date: Tue, 21 Jul 2026 14:26:58 -0400
Subject: [PATCH] Explain the semantic search model choice in the preferences

The model names alone don't say how to choose. Add a caption under the
menu with the trade-off, since switching later means a full reindex.
---
 chrome/content/zotero/preferences/preferences_advanced.xhtml | 2 ++
 chrome/locale/en-US/zotero/preferences.ftl                   | 1 +
 scss/preferences/_advanced.scss                              | 4 ++++
 3 files changed, 7 insertions(+)

diff --git a/chrome/content/zotero/preferences/preferences_advanced.xhtml b/chrome/content/zotero/preferences/preferences_advanced.xhtml
index 03eb77b692..7e9a9a7fab 100644
--- a/chrome/content/zotero/preferences/preferences_advanced.xhtml
+++ b/chrome/content/zotero/preferences/preferences_advanced.xhtml
@@ -306,6 +306,8 @@
 					</menupopup>
 				</menulist>
 			</hbox>
+			<description id="semantic-search-model-description"
+				data-l10n-id="preferences-advanced-semantic-search-model-description"/>
 			<vbox id="semantic-search-status" hidden="true">
 				<hbox align="center">
 					<label data-l10n-id="preferences-advanced-semantic-search-status"/>
diff --git a/chrome/locale/en-US/zotero/preferences.ftl b/chrome/locale/en-US/zotero/preferences.ftl
index f5e9dd6b11..5493591294 100644
--- a/chrome/locale/en-US/zotero/preferences.ftl
+++ b/chrome/locale/en-US/zotero/preferences.ftl
@@ -100,6 +100,7 @@ preferences-advanced-semantic-search-english =
     .label = English
 preferences-advanced-semantic-search-multilingual =
     .label = Multilingual
+preferences-advanced-semantic-search-model-description = “{ preferences-advanced-semantic-search-english.label }” gives the best results for libraries with English-language content. “{ preferences-advanced-semantic-search-multilingual.label }” supports searching in and across many languages.
 preferences-advanced-semantic-search-downloading = Downloading model…
 preferences-advanced-semantic-search-indexing = Indexing…
 preferences-advanced-semantic-search-stopping = Stopping…
diff --git a/scss/preferences/_advanced.scss b/scss/preferences/_advanced.scss
index 8c402083e1..9ab813f512 100644
--- a/scss/preferences/_advanced.scss
+++ b/scss/preferences/_advanced.scss
@@ -111,6 +111,10 @@
 	}
 }
 
+#semantic-search-model-description {
+	margin-bottom: 10px;
+}
+
 #semantic-search-libraries {
 	padding-top: 10px;
 }
\ No newline at end of file