-
Notifications
You must be signed in to change notification settings - Fork 296
Description
❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.
Overview
Mathlive's screen reader announcements for formula navigation and editing are hardcoded in English (e.g., "start of fraction", "deleted:", "numerator"). This affects accessibility compliance for non-English locales in Studio. We need to monkey-patch mathlive to localize these announcements until the upstream fix lands.
Complexity: High
Target branch: unstable
Context
Mathlive is used in Studio's TipTap rich text editor for math formula editing and display, via three components in contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/:
FormulasMenu.vue— interactive math editor dialog (editable<math-field>)MathNodeView.vue— read-only inline math renderingLazyMathNodeView.vue— lazy-loaded variant
Studio already sets mathlive's locale via useMathLiveLocale.js (sets MathfieldElement.locale and mathVirtualKeyboard.locale), which localizes UI strings and math content speech. However, mathlive's screen reader navigation announcements — generated in src/editor/a11y.ts upstream — are hardcoded in English. Strings like "start of fraction", "deleted:", "numerator", "denominator", "superscript" etc. are not passed through mathlive's l10n system.
Upstream issue: arnog/mathlive#2948
The Change
Monkey-patch mathlive's screen reader announcements to localize the hardcoded English strings until the upstream fix lands (arnog/mathlive#2948).
The announcements use a finite set of English prefix strings ("start of", "end of", "out of", "deleted:", "selected:") and relation names ("numerator", "denominator", "superscript", "fraction", "square root", etc.). A post-processing approach — intercepting the announce hook output and replacing these known strings with their translated equivalents — avoids needing access to mathlive internals.
New translatable strings should be added to the appropriate translator/string definitions for each of the hardcoded English announcement terms, so they go through the standard Studio translation workflow.
This should be clearly marked as a temporary workaround to be removed once the upstream fix is released.
How to Get There
The relevant code is in FormulasMenu.vue — specifically loadMathLive() where mathlive is configured after dynamic import. The announce hook can be accessed via MathfieldElement global config after mathlive loads. The existing useMathLiveLocale.js composable is where locale configuration is currently managed and may be a natural place to add the announcement hook override.
Out of Scope
- Fixing the upstream mathlive issue itself
- Localizing other mathlive UI elements beyond screen reader announcements (already handled by
useMathLiveLocale)
Acceptance Criteria
- Screen reader navigation announcements (e.g., "start of fraction", "end of", "deleted:", "numerator", "denominator", "superscript", etc.) are localized for all Studio-supported locales
- New translatable strings are added to the appropriate translator/string definitions for the hardcoded English announcement terms
- The monkey-patch intercepts mathlive's announce hook output and replaces known English strings with translated equivalents
- The patch is clearly marked as a temporary workaround with a reference to the upstream issue (Editing/navigation screen reader announcements are not localized arnog/mathlive#2948)
- Unit tests verify that known English announcement strings are correctly replaced for non-English locales
- Existing mathlive localization (via
useMathLiveLocale) continues to work as before
References
- Upstream issue: Editing/navigation screen reader announcements are not localized arnog/mathlive#2948
- Affected upstream code:
src/editor/a11y.ts(functions:defaultAnnounceHook,relationName,getRelationshipAsSpokenText,getNextAtomAsSpokenText) - Studio mathlive components:
contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/ - Locale composable:
contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/composables/useMathLiveLocale.js
AI usage
Claude was used to draft this issue. The upstream issue was reviewed, Studio codebase was searched for mathlive usage, and the issue was built section-by-section with human review and input at each step.
