feat(a11y): localize mathlive screen reader announcements (#5743)

Monkey-patch mathlive's hardcoded English screen reader announcements
to support localization for all Studio-supported locales. This is a
temporary workaround until the upstream fix lands (arnog/mathlive#2948).

- Add MathLiveA11yStrings.js with translatable strings for all known
  mathlive announcement patterns (prefixes and relation names)
- Add mathLiveA11yLocalize.js with regex-based post-processing to
  replace English patterns with translated equivalents
- Add useMathLiveA11yAnnounce.js composable using MutationObserver
  to intercept and localize aria-live region updates
- Wire composable into FormulasMenu.vue alongside existing locale setup
- Add comprehensive unit tests for localization logic and observer behavior

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rtibblesbot

contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/FormulasMenu.vue

@@ -112,6 +112,7 @@
   import { getTipTapEditorStrings } from '../../TipTapEditorStrings';
   import { useMathLiveLocale } from '../../composables/useMathLiveLocale';
   import { getFormulasStrings } from './FormulasStrings';
+  import { useMathLiveA11yAnnounce } from './useMathLiveA11yAnnounce';
   import symbolsData from './symbols.json';
 
   export default defineComponent({
@@ -252,6 +253,10 @@
       const currentLocale = ref(navigator.language || 'en');
       useMathLiveLocale(currentLocale);
 
+      // TEMPORARY WORKAROUND: Localize mathlive screen reader announcements
+      // Remove when upstream fix lands: https://github.com/arnog/mathlive/issues/2948
+      useMathLiveA11yAnnounce(mathfieldEl);
+
       return {
         rootEl,
         mathfieldEl,

contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/MathLiveA11yStrings.js

@@ -0,0 +1,187 @@
+import { createTranslator } from 'shared/i18n';
+
+// TEMPORARY WORKAROUND: These strings localize mathlive's hardcoded English
+// screen reader announcements. Remove when upstream fix lands:
+// https://github.com/arnog/mathlive/issues/2948
+
+const ACTION_MESSAGES = {
+  deleted: {
+    message: 'deleted: ',
+    context:
+      'Screen reader announcement prefix when a math element is deleted. The trailing space and colon are intentional formatting.',
+  },
+  selected: {
+    message: 'selected: ',
+    context:
+      'Screen reader announcement prefix when math content is selected. The trailing space and colon are intentional formatting.',
+  },
+  startOf: {
+    message: 'start of {relationName}: ',
+    context:
+      'Screen reader announcement when cursor enters the beginning of a math structure (e.g. "start of fraction: "). {relationName} is the name of the math structure.',
+  },
+  endOf: {
+    message: '{spokenText}; end of {relationName}',
+    context:
+      'Screen reader announcement when cursor reaches the end of a math structure (e.g. "2; end of fraction"). {spokenText} is the current element, {relationName} is the structure name.',
+  },
+  outOf: {
+    message: 'out of {relationName};',
+    context:
+      'Screen reader announcement when cursor exits a math structure (e.g. "out of fraction;"). {relationName} is the name of the math structure being exited.',
+  },
+  endOfMathfield: {
+    message: '{spokenText}; end of mathfield',
+    context:
+      'Screen reader announcement when cursor reaches the end of the entire math input field. {spokenText} is the current element.',
+  },
+};
+
+// Relation names from mathlive's relationName function.
+// Keys are the camelCase version of the English relation name string.
+const RELATION_MESSAGES = {
+  accented: {
+    message: 'accented',
+    context: 'Screen reader name for an accented math element',
+  },
+  array: {
+    message: 'array',
+    context: 'Screen reader name for a math array/matrix',
+  },
+  box: {
+    message: 'box',
+    context: 'Screen reader name for a boxed math element',
+  },
+  chemicalFormula: {
+    message: 'chemical formula',
+    context: 'Screen reader name for a chemical formula element',
+  },
+  delimiter: {
+    message: 'delimiter',
+    context: 'Screen reader name for a math delimiter (parentheses, brackets, etc.)',
+  },
+  crossOut: {
+    message: 'cross out',
+    context: 'Screen reader name for a crossed-out/enclosed math element',
+  },
+  extensibleSymbol: {
+    message: 'extensible symbol',
+    context: 'Screen reader name for an extensible math symbol',
+  },
+  error: {
+    message: 'error',
+    context: 'Screen reader name for a math error element',
+  },
+  first: {
+    message: 'first',
+    context: 'Screen reader name for the first element in a math structure',
+  },
+  fraction: {
+    message: 'fraction',
+    context: 'Screen reader name for a fraction element',
+  },
+  group: {
+    message: 'group',
+    context: 'Screen reader name for a grouped math element',
+  },
+  latex: {
+    message: 'LaTeX',
+    context: 'Screen reader name for a raw LaTeX element',
+  },
+  line: {
+    message: 'line',
+    context: 'Screen reader name for a line element',
+  },
+  subscriptSuperscript: {
+    message: 'subscript-superscript',
+    context: 'Screen reader name for a combined subscript-superscript element',
+  },
+  operator: {
+    message: 'operator',
+    context: 'Screen reader name for a math operator',
+  },
+  overUnder: {
+    message: 'over-under',
+    context: 'Screen reader name for an over-under math element',
+  },
+  placeholder: {
+    message: 'placeholder',
+    context: 'Screen reader name for a placeholder element in a math template',
+  },
+  rule: {
+    message: 'rule',
+    context: 'Screen reader name for a rule/line element',
+  },
+  space: {
+    message: 'space',
+    context: 'Screen reader name for a space element',
+  },
+  spacing: {
+    message: 'spacing',
+    context: 'Screen reader name for a spacing element',
+  },
+  squareRoot: {
+    message: 'square root',
+    context: 'Screen reader name for a square root element',
+  },
+  text: {
+    message: 'text',
+    context: 'Screen reader name for a text element within math',
+  },
+  prompt: {
+    message: 'prompt',
+    context: 'Screen reader name for a prompt element',
+  },
+  mathField: {
+    message: 'math field',
+    context: 'Screen reader name for the math field root element',
+  },
+  // "mathfield" (one word) is also used by mathlive as an alias
+  mathfield: {
+    message: 'math field',
+    context: 'Screen reader name for the math field root element (one-word variant)',
+  },
+  parent: {
+    message: 'parent',
+    context: 'Screen reader name for a generic parent math element',
+  },
+  numerator: {
+    message: 'numerator',
+    context: 'Screen reader name for the numerator of a fraction',
+  },
+  denominator: {
+    message: 'denominator',
+    context: 'Screen reader name for the denominator of a fraction',
+  },
+  index: {
+    message: 'index',
+    context: 'Screen reader name for the index of a root/radical',
+  },
+  superscript: {
+    message: 'superscript',
+    context: 'Screen reader name for a superscript element',
+  },
+  subscript: {
+    message: 'subscript',
+    context: 'Screen reader name for a subscript element',
+  },
+  radicand: {
+    message: 'radicand',
+    context: 'Screen reader name for the body content inside a square root',
+  },
+  superscriptAndSubscript: {
+    message: 'superscript and subscript',
+    context: 'Screen reader name for a combined superscript-and-subscript element',
+  },
+};
+
+// English relation name strings derived from RELATION_MESSAGES, sorted longest-first
+// to prevent partial regex matches (e.g. "superscript and subscript" before "superscript")
+export const RELATION_NAMES = Object.values(RELATION_MESSAGES)
+  .map(m => m.message)
+  .filter((v, i, a) => a.indexOf(v) === i) // dedupe ("math field" appears twice)
+  .sort((a, b) => b.length - a.length);
+
+const MESSAGES = { ...ACTION_MESSAGES, ...RELATION_MESSAGES };
+
+export default createTranslator('MathLiveA11yStrings', MESSAGES);

contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/mathLiveA11yLocalize.js

@@ -0,0 +1,99 @@
+/**
+ * TEMPORARY WORKAROUND: Localizes mathlive's hardcoded English screen reader
+ * announcements by post-processing the announcement text.
+ *
+ * Remove when upstream fix lands:
+ * https://github.com/arnog/mathlive/issues/2948
+ */
+
+import translator, { RELATION_NAMES } from './MathLiveA11yStrings';
+
+/**
+ * Convert an English relation name to its camelCase translator key.
+ * e.g. "square root" -> "squareRoot$", "subscript-superscript" -> "subscriptSuperscript$"
+ */
+function toTranslatorKey(str) {
+  return (
+    str
+      .split(/[\s-]+/)
+      .map((word, i) =>
+        i === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase(),
+      )
+      .join('') + '$'
+  );
+}
+
+// Build regex that matches any English relation name
+const RELATION_NAMES_PATTERN = RELATION_NAMES.map(name =>
+  name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+).join('|');
+
+// Pre-compiled regexes for hot-path use in localizeAnnouncement()
+const OUT_OF_REGEX = new RegExp(`out of (${RELATION_NAMES_PATTERN});`, 'g');
+const START_OF_REGEX = new RegExp(`start of (${RELATION_NAMES_PATTERN}):[ ]?`);
+const END_OF_MATHFIELD_REGEX = /^(.*?); end of mathfield$/;
+const END_OF_REGEX = new RegExp(`(.*?); end of (${RELATION_NAMES_PATTERN})$`);
+
+function translateRelationName(englishName) {
+  const key = toTranslatorKey(englishName);
+  if (translator[key]) {
+    return translator[key]();
+  }
+  return englishName;
+}
+
+// Mathlive appends alternating " \u00A0 " / " \u202F " to force aria-live change detection
+const MATHLIVE_HACK_REGEX = / [\u00A0\u202F] $/;
+
+/**
+ * Localize a mathlive announcement string by replacing known English patterns
+ * with their translated equivalents. Preserves mathlive's trailing aria-live
+ * change hack if present.
+ *
+ * @param {string} text - The English announcement text from mathlive
+ * @returns {string} The localized announcement text
+ */
+export function localizeAnnouncement(text) {
+  if (!text) return text;
+
+  const hackMatch = text.match(MATHLIVE_HACK_REGEX);
+  const cleanText = hackMatch ? text.slice(0, -hackMatch[0].length) : text;
+  if (!cleanText) return text;
+
+  let result = cleanText;
+
+  // Pattern: "deleted: <content>" -> translated prefix + content
+  result = result.replace(/^deleted: /, () => translator.deleted$());
+
+  // Pattern: "selected: <content>" -> translated prefix + content
+  result = result.replace(/^selected: /, () => translator.selected$());
+
+  // Pattern: "<spoken>; end of mathfield" (must check before generic "end of")
+  const endOfMathfieldMatch = result.match(END_OF_MATHFIELD_REGEX);
+  if (endOfMathfieldMatch) {
+    const localized = translator.endOfMathfield$({ spokenText: endOfMathfieldMatch[1] });
+    return hackMatch ? localized + hackMatch[0] : localized;
+  }
+
+  // Pattern: "out of <relation>;" (can appear multiple times)
+  OUT_OF_REGEX.lastIndex = 0;
+  result = result.replace(OUT_OF_REGEX, (_match, name) => {
+    return translator.outOf$({ relationName: translateRelationName(name) });
+  });
+
+  // Pattern: "start of <relation>: "
+  result = result.replace(START_OF_REGEX, (_match, name) => {
+    return translator.startOf$({ relationName: translateRelationName(name) });
+  });
+
+  // Pattern: "<spoken>; end of <relation>"
+  result = result.replace(END_OF_REGEX, (_match, spoken, name) => {
+    return translator.endOf$({
+      spokenText: spoken,
+      relationName: translateRelationName(name),
+    });
+  });
+
+  if (result === cleanText) return text;
+  return hackMatch ? result + hackMatch[0] : result;
+}

contentcuration/contentcuration/frontend/shared/views/TipTapEditor/TipTapEditor/components/math/useMathLiveA11yAnnounce.js

@@ -0,0 +1,71 @@
+/**
+ * TEMPORARY WORKAROUND: Intercepts mathlive's aria-live region writes and
+ * localizes the hardcoded English screen reader text in-place.
+ *
+ * Mathlive's defaultAnnounceHook writes English text directly to the aria-live
+ * element's textContent. We intercept the textContent setter so the English
+ * text is localized before it ever appears in the DOM — screen readers only
+ * see the translated text.
+ *
+ * Remove when upstream fix lands:
+ * https://github.com/arnog/mathlive/issues/2948
+ */
+
+import { onBeforeUnmount, watch } from 'vue';
+import { localizeAnnouncement } from './mathLiveA11yLocalize';
+
+const NODE_TEXT_CONTENT = Object.getOwnPropertyDescriptor(Node.prototype, 'textContent');
+const WHITESPACE_ONLY_REGEX = /^[\s\u00A0\u202F]+$/;
+
+/**
+ * Install a textContent interceptor on the math-field's aria-live element
+ * that localizes mathlive's English announcements before they reach the DOM.
+ *
+ * @param {HTMLElement} mathfield - The <math-field> element
+ * @returns {Function} cleanup - Call to restore original textContent behavior
+ */
+export function setupA11yAnnounceInterceptor(mathfield) {
+  const ariaLiveEl = mathfield.shadowRoot?.querySelector('[aria-live]');
+  if (!ariaLiveEl) return () => {};
+
+  Object.defineProperty(ariaLiveEl, 'textContent', {
+    set(value) {
+      if (typeof value === 'string' && value && !WHITESPACE_ONLY_REGEX.test(value)) {
+        value = localizeAnnouncement(value);
+      }
+      NODE_TEXT_CONTENT.set.call(this, value);
+    },
+    get() {
+      return NODE_TEXT_CONTENT.get.call(this);
+    },
+    configurable: true,
+  });
+
+  return () => delete ariaLiveEl.textContent;
+}
+
+/**
+ * Vue composable that sets up announcement localization for a math-field element.
+ *
+ * @param {import('vue').Ref<HTMLElement|null>} mathfieldRef - Ref to the <math-field> element
+ */
+export function useMathLiveA11yAnnounce(mathfieldRef) {
+  let cleanup = null;
+
+  const teardown = () => {
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+  };
+
+  const setup = () => {
+    teardown();
+    const mathfield = mathfieldRef.value;
+    if (!mathfield) return;
+    cleanup = setupA11yAnnounceInterceptor(mathfield);
+  };
+
+  watch(mathfieldRef, setup, { immediate: true });
+  onBeforeUnmount(teardown);
+}