Add-on template: add support for custom speech pronunciation dictionaries (NVDA 2026.2)

buildVars.py

@@ -99,5 +99,14 @@
 # Each key is the name of the dictionary,
 # with keys inside recording the following attributes:
 # displayName (name of the speech dictionary shown to users and translatable),
-# mandatory (True when always enabled, False when not.
+# mandatory (True when always enabled, False when not).
 symbolDictionaries: SymbolDictionaries = {}
+
+# Custom speech dictionaries (distinct from symbol dictionaries above)
+# Speech dictionary files reside in the speechDicts folder and are named `name.dic`.
+# If your add-on includes custom speech (pronunciation) dictionaries (most will not), fill out this dictionary.
+# Each key is the name of the dictionary,
+# with keys inside recording the following attributes:
+# displayName (name of the speech dictionary shown to users and translatable),
+# mandatory (True when always enabled, False when not).
+speechDictionaries: SpeechDictionaries = {}

readme.md

@@ -142,6 +142,19 @@ Information on custom symbol dictionaries must be specified in buildVars under `
 
 Note: you must fill out this dictionary if at least one custom symbol dictionary is included in the add-on. If not, leave the dictionary empty.
 
+###### Speech pronunciation dictionaries
+
+Information on custom speech (pronunciation) dictionaries must be specified in buildVars under `speechDictionaries` dictionary as follows:
+
+* Dictionary name (string key for a nested dictionary): each `symbolDictionaries` entry is a name for the included custom speech dictionary placed in `speechDicts` folder inside `addon` folder.
+The file is named `<dictionary_name>.dic`.
+This nested dictionary should specify:
+	* displayName (string): the name of the dictionary shown to users and is translatable.
+	* mandatory (True/False): Always enabled (True) or optional and visible in the GUI (False)
+
+Note: you must fill out this dictionary if at least one custom speech dictionary is included in the add-on.
+If not, leave the dictionary empty.
+
 ### To manage documentation files for your addon:
 
 1. Copy the `readme.md` file for your add-on to the first created folder, where you copied `buildVars.py`. You can also copy `style.css` to improve the presentation of HTML documents.

sconstruct

@@ -61,6 +61,7 @@ env.Append(
 	addon_info=buildVars.addon_info,
 	brailleTables=buildVars.brailleTables,
 	symbolDictionaries=buildVars.symbolDictionaries,
+	speechDictionaries=buildVars.speechDictionaries,
 )
 
 if env["dev"]:

site_scons/site_tools/NVDATool/__init__.py

@@ -13,6 +13,7 @@
 - addon_info: .typing.AddonInfo
 - brailleTables: .typings.BrailleTables
 - symbolDictionaries: .typings.SymbolDictionaries
+- speechDictionaries: .typings.SpeechDictionaries
 
 The following environment variables are required to build the HTML:
 
@@ -49,6 +50,7 @@ def generate(env: Environment):
 
 	env.SetDefault(brailleTables={})
 	env.SetDefault(symbolDictionaries={})
+	env.SetDefault(speechDictionaries={})
 
 	manifestAction = env.Action(
 		lambda target, source, env: generateManifest(
@@ -57,6 +59,7 @@ def generate(env: Environment):
 			addon_info=env["addon_info"],
 			brailleTables=env["brailleTables"],
 			symbolDictionaries=env["symbolDictionaries"],
+			speechDictionaries=env["speechDictionaries"],
 		)
 		and None,
 		lambda target, source, env: f"Generating manifest {target[0]}",
@@ -75,6 +78,7 @@ def generate(env: Environment):
 			addon_info=env["addon_info"],
 			brailleTables=env["brailleTables"],
 			symbolDictionaries=env["symbolDictionaries"],
+			speechDictionaries=env["speechDictionaries"],
 		)
 		and None,
 		lambda target, source, env: f"Generating translated manifest {target[0]}",

site_scons/site_tools/NVDATool/manifests.py

@@ -2,7 +2,7 @@
 import gettext
 from functools import partial
 
-from .typings import AddonInfo, BrailleTables, SymbolDictionaries
+from .typings import AddonInfo, BrailleTables, SymbolDictionaries, SpeechDictionaries
 from .utils import format_nested_section
 
 
@@ -12,6 +12,7 @@ def generateManifest(
 	addon_info: AddonInfo,
 	brailleTables: BrailleTables,
 	symbolDictionaries: SymbolDictionaries,
+	speechDictionaries: SpeechDictionaries,
 ):
 	# Prepare the root manifest section
 	with codecs.open(source, "r", "utf-8") as f:
@@ -26,6 +27,10 @@ def generateManifest(
 	if symbolDictionaries:
 		manifest += format_nested_section("symbolDictionaries", symbolDictionaries)
 
+	# Custom speech pronunciation dictionaries
+	if speechDictionaries:
+		manifest += format_nested_section("speechDictionaries", speechDictionaries)
+
 	with codecs.open(dest, "w", "utf-8") as f:
 		f.write(manifest)
 
@@ -38,6 +43,7 @@ def generateTranslatedManifest(
 	addon_info: AddonInfo,
 	brailleTables: BrailleTables,
 	symbolDictionaries: SymbolDictionaries,
+	speechDictionaries: SpeechDictionaries,
 ):
 	with open(mo, "rb") as f:
 		_ = gettext.GNUTranslations(f).gettext
@@ -63,5 +69,9 @@ def generateTranslatedManifest(
 	if symbolDictionaries:
 		manifest += _format_section_only_with_displayName("symbolDictionaries", symbolDictionaries)
 
+	# Custom speech pronunciation dictionaries
+	if speechDictionaries:
+		manifest += _format_section_only_with_displayName("speechDictionaries", speechDictionaries)
+
 	with codecs.open(dest, "w", "utf-8") as f:
 		f.write(manifest)

site_scons/site_tools/NVDATool/typings.py

@@ -30,8 +30,14 @@ class SymbolDictionaryAttributes(TypedDict):
 	mandatory: bool
 
 
+class SpeechDictionaryAttributes(TypedDict):
+	displayName: str
+	mandatory: bool
+
+
 BrailleTables = dict[str, BrailleTableAttributes]
 SymbolDictionaries = dict[str, SymbolDictionaryAttributes]
+SpeechDictionaries = dict[str, SpeechDictionaryAttributes]
 
 
 class Strable(Protocol):