SaschaCowley · Sep 5, 2025 · Apr 18, 2025 · Apr 22, 2025 · Apr 22, 2025 · Apr 23, 2025
@@ -30,6 +30,7 @@
 import controlTypes
 from controlTypes import TextPosition, TextAlign
 import config
+from config.configFlags import ReportSpellingErrors
 import speech
 import api
 import textInfos
@@ -313,7 +314,7 @@ def _getFormatFieldAnnotationTypes(
 		# Always mutate to a tuple to allow for a generic x in y matching
 		if not isinstance(annotationTypes, tuple):
 			annotationTypes = (annotationTypes,)
-		if formatConfig["reportSpellingErrors"]:
+		if formatConfig["reportSpellingErrors2"] != ReportSpellingErrors.OFF.value:
 			if UIAHandler.AnnotationType_SpellingError in annotationTypes:
 				formatField["invalid-spelling"] = True
 			if UIAHandler.AnnotationType_GrammarError in annotationTypes:
@@ -368,7 +369,7 @@ def _getFormatFieldAtRange(  # noqa: C901
 		if not isinstance(textRange, UIAHandler.IUIAutomationTextRange):
 			raise ValueError("%s is not a text range" % textRange)
 		fetchAnnotationTypes = (
-			formatConfig["reportSpellingErrors"]
+			formatConfig["reportSpellingErrors2"] != ReportSpellingErrors.OFF.value
 			or formatConfig["reportComments"]
 			or formatConfig["reportRevisions"]
 			or formatConfig["reportBookmarks"]

@@ -2,7 +2,7 @@
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 # Copyright (C) 2006-2025 NV Access Limited, Peter Vágner, Joseph Lee, Bill Dengler,
-# Burman's Computer and Education Ltd, Cary-rowen
+# Burman's Computer and Education Ltd, Cary-rowen, Cyrille Bougot
 
 """Mix-in classes which provide common behaviour for particular types of controls across different APIs.
 Behaviors described in this mix-in include providing table navigation commands for certain table rows, terminal input and output support, announcing notifications and suggestion items and so on.
@@ -297,7 +297,7 @@ def _delayedDetection():
 
 	def event_typedCharacter(self, ch: str):
 		if (
-			config.conf["documentFormatting"]["reportSpellingErrors"]
+			config.conf["documentFormatting"]["reportSpellingErrors2"]
 			and config.conf["keyboard"]["alertForSpellingErrors"]
 			and (
 				# Not alpha, apostrophe or control.

@@ -27,6 +27,7 @@
 import logging
 from logging import DEBUG
 from shlobj import FolderId, SHGetKnownFolderPath
+from addonAPIVersion import BACK_COMPAT_TO
 import baseObject
 import easeOfAccess
 from fileUtils import FaultTolerantFile
@@ -35,6 +36,7 @@
 from . import profileUpgrader
 from . import aggregatedSection
 from .configSpec import confspec
+from .configFlags import ReportSpellingErrors
 from .featureFlag import (
 	_transformSpec_AddFeatureFlagDefault,
 	_validateConfig_featureFlag,
@@ -1285,9 +1287,9 @@ def __setitem__(
 		self._cache[key] = val
 
 		# Alias old config items to their new counterparts for backwards compatibility.
-		# Uncomment when there are new links that need to be made.
-		# if BACK_COMPAT_TO < (2026, 1, 0) and NVDAState._allowDeprecatedAPI():
-		# self._linkDeprecatedValues(key, val)
+		# TODO: Comment out in 2026.1.
+		if BACK_COMPAT_TO < (2026, 1, 0) and NVDAState._allowDeprecatedAPI():
+			self._linkDeprecatedValues(key, val)
 
 	def _linkDeprecatedValues(self, key: aggregatedSection._cacheKeyT, val: aggregatedSection._cacheValueT):
 		"""Link deprecated config keys and values to their replacements.
@@ -1315,6 +1317,24 @@ def _linkDeprecatedValues(self, key: aggregatedSection._cacheKeyT, val: aggregat
 		>>> ...
 		"""
 		match self.path:
+			case ("documentFormatting",):
+				match key:
+					case "reportSpellingErrors2":
+						# Alias documentFormatting.reportSpellingErrors2 to documentFormatting.reportSpellingErrors for backwards compatibility.
+						key = "reportSpellingErrors"
+						val = val != ReportSpellingErrors.OFF.value
+					case "reportSpellingErrors":
+						# Alias documentFormatting.reportSpellingErrors to documentFormatting.reportSpellingErrors2 for forwards compatibility.
+						log.warning(
+							"documentFormatting.reportSpellingErrors is deprecated. Use documentFormatting.reportSpellingErrors2 instead.",
+							# Include stack info so testers can report warning to add-on author.
+							stack_info=True,
+						)
+						key = "reportSpellingErrors2"
+						val = ReportSpellingErrors.SPEECH.value if val else ReportSpellingErrors.OFF.value
+					case _:
+						# We don't care about other keys in this section.
+						return
 			case _:
 				# We don't care about other sections.
 				return

@@ -180,6 +180,32 @@ def _displayStringLabels(self):
 		}
 
 
+@unique
+class ReportSpellingErrors(DisplayStringIntEnum):
+	"""Enumeration containing the possible config values to report spelling errors while reading.
+
+	Use ReportSpellingErrors.MEMBER.value to compare with the config;
+	use ReportSpellingErrors.MEMBER.displayString in the UI for a translatable description of this member.
+	"""
+
+	OFF = 0
+	SPEECH = 1
+	SOUND = 2
+
+	@property
+	def _displayStringLabels(self) -> dict["ReportSpellingErrors", str]:
+		return {
+			# Translators: A choice in a combo box in the document formatting dialog to not report spelling errors.
+			ReportSpellingErrors.OFF: pgettext("reportSpellingErrorsSetting", "Off"),
+			# Translators: A choice in a combo box in the document formatting dialog to report spelling errors
+			# with speech.
+			ReportSpellingErrors.SPEECH: pgettext("reportSpellingErrorsSetting", "Speech"),
+			# Translators: A choice in a combo box in the document formatting dialog to report spelling errors
+			# with a sound.
+			ReportSpellingErrors.SOUND: pgettext("reportSpellingErrorsSetting", "Sound"),
+		}
+
+
 @unique
 class ReportTableHeaders(DisplayStringIntEnum):
 	"""Enumeration containing the possible config values to report table headers.

@@ -13,7 +13,7 @@
 #: provide an upgrade step (@see profileUpgradeSteps.py). An upgrade step does not need to be added when
 #: just adding a new element to (or removing from) the schema, only when old versions of the config
 #: (conforming to old schema versions) will not work correctly with the new schema.
-latestSchemaVersion = 18
+latestSchemaVersion = 19
 
 #: The configuration specification string
 #: @type: String
@@ -226,7 +226,10 @@
 	reportAlignment = boolean(default=false)
 	reportLineSpacing = boolean(default=false)
 	reportStyle = boolean(default=false)
+	# Deprecated, and aliased to reportSpellingErrors2, to be removed in 2026.1
 	reportSpellingErrors = boolean(default=true)
+	# 0: Off, 1: Speech, 2: Sound
+	reportSpellingErrors2 = integer(min=0, max=2, default=1)
 	reportPage = boolean(default=true)
 	reportLineNumber = boolean(default=False)
 	# 0: Off, 1: Speech, 2: Tones, 3: Both Speech and Tones

@@ -24,6 +24,7 @@
 	OutputMode,
 	ReportCellBorders,
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ShowMessages,
 	TetherTo,
@@ -597,3 +598,29 @@ def upgradeConfigFrom_17_to_18(profile: ConfigObj) -> None:
 			"dotPad added to braille display auto detection excluded displays due to generic USB PID/VID. "
 			f"List is now: {excludedDisplays}",
 		)
+
+
+def upgradeConfigFrom_18_to_19(profile: ConfigObj):
+	"""Convert report spelling errors configurations from boolean to integer values."""
+
+	section = "documentFormatting"
+	key = "reportSpellingErrors"
+	newKey = "reportSpellingErrors2"
+	try:
+		oldValue: bool = profile[section].as_bool(key)
+	except KeyError:
+		log.debug(f"'{key}' not present in config, no action taken.")
+		return
+	except ValueError:
+		log.error(f"'{key}' is not a boolean, got {profile[section][key]!r}. No action taken.")
+		return
+
+	newValue = ReportSpellingErrors.SPEECH.value if oldValue else ReportSpellingErrors.OFF.value
+	profile[section][newKey] = newValue
+	log.debug(
+		(
+			f"Added '{newKey}' with value {newValue} ({ReportSpellingErrors(newValue).name})."
+			f" The old key '{key}' remains with its original value ({oldValue}) since the two keys are aliased in the"
+			" code."
+		),
+	)
@@ -45,6 +45,7 @@
 	BrailleMode,
 	OutputMode,
 	TypingEcho,
+	ReportSpellingErrors,
 )
 from config.featureFlag import FeatureFlag
 from config.featureFlagEnums import BoolFlag
@@ -788,19 +789,18 @@ def script_toggleReportStyle(self, gesture):
 
 	@script(
 		# Translators: Input help mode message for toggle report spelling errors command.
-		description=_("Toggles on and off the reporting of spelling errors"),
+		description=_("Cycles through options for how to report spelling errors"),
 		category=SCRCAT_DOCUMENTFORMATTING,
 	)
 	def script_toggleReportSpellingErrors(self, gesture):
-		if config.conf["documentFormatting"]["reportSpellingErrors"]:
-			# Translators: The message announced when toggling the report spelling errors document formatting setting.
-			state = _("report spelling errors off")
-			config.conf["documentFormatting"]["reportSpellingErrors"] = False
-		else:
-			# Translators: The message announced when toggling the report spelling errors document formatting setting.
-			state = _("report spelling errors on")
-			config.conf["documentFormatting"]["reportSpellingErrors"] = True
-		ui.message(state)
+		toggleIntegerValue(
+			configSection="documentFormatting",
+			configKey="reportSpellingErrors2",
+			enumClass=ReportSpellingErrors,
+			# Translators: Reported when the user cycles through the choices to report spelling errors.
+			# {mode} will be replaced with the mode; e.g. Off, Speech, Sound.
+			messageTemplate=_("Report spelling errors {mode}"),
+		)
 
 	@script(
 		# Translators: Input help mode message for toggle report pages command.
@@ -2536,7 +2536,7 @@ def _reportFormattingHelper(self, info, browseable=False):
 			"reportColor",
 			"reportStyle",
 			"reportAlignment",
-			"reportSpellingErrors",
+			"reportSpellingErrors2",
 			"reportLineIndentation",
 			"reportParagraphIndentation",
 			"reportLineSpacing",

@@ -41,6 +41,7 @@
 	TetherTo,
 	ParagraphStartMarker,
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ReportCellBorders,
 	OutputMode,
@@ -2124,7 +2125,7 @@ def makeSettings(self, settingsSizer):
 		)
 		self.bindHelpEvent("KeyboardSettingsAlertForSpellingErrors", self.alertForSpellingErrorsCheckBox)
 		self.alertForSpellingErrorsCheckBox.SetValue(config.conf["keyboard"]["alertForSpellingErrors"])
-		if not config.conf["documentFormatting"]["reportSpellingErrors"]:
+		if config.conf["documentFormatting"]["reportSpellingErrors2"] == ReportSpellingErrors.OFF.value:
 			self.alertForSpellingErrorsCheckBox.Disable()
 
 		# Translators: This is the label for a checkbox in the
@@ -2800,11 +2801,18 @@ def makeSettings(self, settingsSizer):
 		self.revisionsCheckBox = docInfoGroup.addItem(wx.CheckBox(docInfoBox, label=revisionsText))
 		self.revisionsCheckBox.SetValue(config.conf["documentFormatting"]["reportRevisions"])
 
-		# Translators: This is the label for a checkbox in the
-		# document formatting settings panel.
-		spellingErrorText = _("Spelling e&rrors")
-		self.spellingErrorsCheckBox = docInfoGroup.addItem(wx.CheckBox(docInfoBox, label=spellingErrorText))
-		self.spellingErrorsCheckBox.SetValue(config.conf["documentFormatting"]["reportSpellingErrors"])
+		self.spellingErrorsCombo = docInfoGroup.addLabeledControl(
+			# Translators: This is the label for a checkbox in the
+			# document formatting settings panel.
+			_("Spelling e&rrors"),
+			wx.Choice,
+			choices=[i.displayString for i in ReportSpellingErrors],
+		)
+		self.bindHelpEvent(
+			"reportSpellingErrors",
+			self.spellingErrorsCombo,
+		)
+		self.spellingErrorsCombo.SetSelection(config.conf["documentFormatting"]["reportSpellingErrors2"])
 
 		# Translators: This is the label for a group of document formatting options in the
 		# document formatting settings panel
@@ -3027,7 +3035,7 @@ def onSave(self):
 		config.conf["documentFormatting"]["reportHighlight"] = self.highlightCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportAlignment"] = self.alignmentCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportStyle"] = self.styleCheckBox.IsChecked()
-		config.conf["documentFormatting"]["reportSpellingErrors"] = self.spellingErrorsCheckBox.IsChecked()
+		config.conf["documentFormatting"]["reportSpellingErrors2"] = self.spellingErrorsCombo.GetSelection()
 		config.conf["documentFormatting"]["reportPage"] = self.pageCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportLineNumber"] = self.lineNumberCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportLineIndentation"] = self.lineIndentationCombo.GetSelection()

@@ -39,6 +39,7 @@
 	EndUtteranceCommand,
 	SuppressUnicodeNormalizationCommand,
 	CharacterModeCommand,
+	WaveFileCommand,
 )
 from .shortcutKeys import getKeyboardShortcutsSpeech
 
@@ -65,6 +66,7 @@
 import config
 from config.configFlags import (
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ReportCellBorders,
 	OutputMode,
@@ -1490,7 +1492,7 @@ def speakTextInfo(
 def getTextInfoSpeech(  # noqa: C901
 	info: textInfos.TextInfo,
 	useCache: Union[bool, SpeakTextInfoState] = True,
-	formatConfig: Dict[str, bool] = None,
+	formatConfig: dict[str, bool | int] | None = None,
 	unit: Optional[str] = None,
 	reason: OutputReason = OutputReason.QUERY,
 	_prefixSpeechCommand: Optional[SpeechCommand] = None,
@@ -1514,7 +1516,7 @@ def getTextInfoSpeech(  # noqa: C901
 	)
 	# For performance reasons, when navigating by paragraph or table cell, spelling errors will not be announced.
 	if unit in (textInfos.UNIT_PARAGRAPH, textInfos.UNIT_CELL) and reason == OutputReason.CARET:
-		formatConfig["reportSpellingErrors"] = False
+		formatConfig["reportSpellingErrors2"] = ReportSpellingErrors.OFF.value
 
 	# Fetch the last controlFieldStack, or make a blank one
 	controlFieldStackCache = speakTextInfoState.controlFieldStackCache if speakTextInfoState else []
@@ -1891,7 +1893,7 @@ def _getTextInfoSpeech_considerSpelling(
 	speechSequence: SpeechSequence,
 	language: str,
 ) -> Generator[SpeechSequence, None, None]:
-	if onlyInitialFields or any(isinstance(x, str) for x in speechSequence):
+	if onlyInitialFields or speechSequence:
 		yield speechSequence
 	if not onlyInitialFields:
 		spellingSequence = list(
@@ -2991,13 +2993,16 @@ def getFormatFieldSpeech(  # noqa: C901
 				# Translators: Reported when text no longer contains a bookmark
 				text = _("out of bookmark")
 				textList.append(text)
-	if formatConfig["reportSpellingErrors"]:
+	if formatConfig["reportSpellingErrors2"] != ReportSpellingErrors.OFF.value:
 		invalidSpelling = attrs.get("invalid-spelling")
 		oldInvalidSpelling = attrsCache.get("invalid-spelling") if attrsCache is not None else None
 		if (invalidSpelling or oldInvalidSpelling is not None) and invalidSpelling != oldInvalidSpelling:
 			if invalidSpelling:
-				# Translators: Reported when text contains a spelling error.
-				text = _("spelling error")
+				if formatConfig["reportSpellingErrors2"] == ReportSpellingErrors.SPEECH.value:
+					# Translators: Reported when text contains a spelling error.
+					text = _("spelling error")
+				else:
+					text = WaveFileCommand(r"waves\textError.wav")
 			elif extraDetail:
 				# Translators: Reported when moving out of text containing a spelling error.
 				text = _("out of spelling error")

@@ -10,6 +10,7 @@
   * Add-ons can be sorted by minimum and last tested NVDA version as well as by installation date. (#18440, #18560, @nvdaes, @CyrilleB79)
   * Minimum and last tested version will now be also shown in the details area for an add-on in the Available Add-ons tab. (#18440, @nvdaes)
   * Installation date will now be also shown in the details area for external add-ons. (#18560, @CyrilleB79)
+* While reading text, spelling errors can now be reported with a sound instead of speech. (#4233, @jcsteh, @CyrilleB79)
 
 ### Changes
 
@@ -56,6 +57,10 @@ Please refer to [the developer guide](https://download.nvaccess.org/documentatio
   * `LP__ULARGE_INTEGER`
   * `SynthDriver.isSpeaking`
 * `easeOfAccess.RegistryKey` and `config.RegistryKey` is deprecated, use `config.registry.RegistryKey` instead. (#18608)
+* The `bool` configuration key `[documentFormatting][reportSpellingErrors]` is deprecated for removal in 2026.1, instead use `[reportSpellingErrors2]`. (#17997, @CyrilleB79)
+  * The new key has an `int` value matching an `ReportSpellingErrors` `enum` with options for off, speech and sound.
+  * API consumers can use the `bool` value as previously, or check the `ReportSpellingErrors` if handling speech or sound specifically.
+  * These keys are currently synchronized until 2026.1.
 
 ## 2025.2