fix(analytics): translate the hotspot detail lines on /es

The analytics page shipped its per-hotspot "why" line as a prebuilt English
sentence built inside lib/analytics/confusion-hotspots.ts, so on /es every
heading, badge and footer translated while the line carrying the actual
finding stayed in English:

  4 of 5 student(s) still failing on their latest attempt · average 52%
  3 of 5 student(s) missed it on their latest submission · 60% miss rate

Caught by rendering the page under /es for the QA screenshots, not by a test —
the strings were correct, just not translatable.

Hotspot now carries numbers only (`totalAttempts` replaces `evidence`) and the
page formats them through next-intl. Each signal counts something different, so
each scope gets its own message rather than one generic sentence that would
read wrong for three scopes out of four.

The MCP tool keeps its English `evidence` string on purpose: its reader is a
model, not a localised UI. Noted in the twin-implementation header.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VqQTE7LDYPx7d15BcWLGfC

Author: guillermoscript

app/[locale]/dashboard/teacher/courses/[courseId]/analytics/page.tsx

@@ -47,6 +47,38 @@ function hotspotHref(courseId: string, h: Hotspot): string | null {
   return null
 }
 
+/**
+ * The one-line "why this is a hotspot" under each item.
+ *
+ * Built here rather than in the analytics module so it can be translated: each
+ * signal counts something different, so each gets its own message instead of a
+ * generic one that would read wrong for three scopes out of four.
+ */
+function hotspotEvidence(h: Hotspot, t: Awaited<ReturnType<typeof getTranslations>>): string {
+  if (h.scope === 'practice') {
+    return t('hotspots.evidencePractice', {
+      attempts: h.totalAttempts ?? 0,
+      students: h.studentsAttempted,
+      avg: h.avgScore ?? 0,
+      below: h.studentsAffected,
+    })
+  }
+  if (h.scope === 'exam_question') {
+    return t('hotspots.evidenceExam', {
+      missers: h.studentsAffected,
+      students: h.studentsAttempted,
+      rate: Math.round((h.studentsAffected / Math.max(h.studentsAttempted, 1)) * 100),
+    })
+  }
+  // Exercises and checkpoints share a shape: latest attempt decides "stuck".
+  const base = t('hotspots.evidenceStuck', {
+    stuck: h.studentsAffected,
+    students: h.studentsAttempted,
+    attempts: (h.avgAttempts ?? 0).toFixed(1),
+  })
+  return h.avgScore == null ? base : `${base} · ${t('hotspots.evidenceAvg', { avg: h.avgScore })}`
+}
+
 export default async function CourseAnalyticsPage({ params, searchParams }: PageProps) {
   const { courseId } = await params
   const { days: daysParam } = await searchParams
@@ -265,7 +297,9 @@ export default async function CourseAnalyticsPage({ params, searchParams }: Page
                               <span className="text-sm font-medium">{h.label}</span>
                             )}
                           </div>
-                          <p className="mt-1 text-xs text-muted-foreground">{h.evidence}</p>
+                          <p className="mt-1 text-xs text-muted-foreground">
+                            {hotspotEvidence(h, t)}
+                          </p>
                         </div>
                         <SeverityBar value={h.severity} label={t('hotspots.severity')} />
                       </div>

lib/analytics/confusion-hotspots.ts

@@ -27,6 +27,13 @@
  *   query; the tool was left alone to keep a shipped payload stable. So the
  *   page can surface a hotspot the tool will not — never the reverse.
  *
+ *   The second difference is presentational: this module returns only numbers
+ *   per hotspot, never a prebuilt sentence, because the page renders in `en`
+ *   and `es`. (It first returned an `evidence` string, which left every hotspot
+ *   detail line stuck in English on `/es` while the rest of the page
+ *   translated.) The MCP tool keeps its English `evidence` string — its reader
+ *   is a model, not a localised UI.
+ *
  * RLS
  *   Every read below runs as the signed-in teacher. Each source table has a
  *   teacher-scoped SELECT policy (`teachers_view_tenant_evaluations`,
@@ -61,7 +68,8 @@ export interface Hotspot {
   avgAttempts: number | null
   /** Course lesson this item belongs to, when known — lets the page deep-link. */
   lessonId: number | null
-  evidence: string
+  /** Total attempts behind this row, where the signal counts them (practice only). */
+  totalAttempts: number | null
 }
 
 export type DifficultyLabel = 'easy' | 'medium' | 'hard'
@@ -344,7 +352,7 @@ async function loadPractice(
       avgScore: Math.round(avg),
       avgAttempts: null,
       lessonId: b.lessonId,
-      evidence: `${b.scores.length} attempt(s) by ${b.users.size} student(s) · average ${Math.round(avg)}% · ${b.struggling.size} below ${LOW_SCORE}%`,
+      totalAttempts: b.scores.length,
     })
   }
   return { hotspots, rowCount: rows.length }
@@ -538,7 +546,7 @@ function rollUpAttempts<K extends string | number>(
       avgScore: avgScore == null ? null : Math.round(avgScore),
       avgAttempts: Math.round(avgAttempts * 10) / 10,
       lessonId: d.lessonId,
-      evidence: `${b.stuck.size} of ${b.attempted.size} student(s) still failing on their latest attempt · ${avgAttempts.toFixed(1)} attempt(s) each on average${avgScore == null ? '' : ` · average ${Math.round(avgScore)}%`}`,
+      totalAttempts: null,
     })
   }
   return out
@@ -644,7 +652,7 @@ async function loadExamQuestionMisses(
       avgScore: null,
       avgAttempts: null,
       lessonId: null,
-      evidence: `${b.missers.size} of ${b.attempts} student(s) missed it on their latest submission · ${Math.round(missRate * 100)}% miss rate`,
+      totalAttempts: null,
     })
   }
   return { hotspots, submissionCount: subById.size }

messages/en.json

@@ -1649,7 +1649,11 @@
           "severity": "Severity",
           "allClear": "No hotspots in this window — nobody is stuck on an exercise, checkpoint, drill or exam question.",
           "noData": "No student activity in this window yet. Once students attempt exercises, checkpoints, practice drills or exams, their results appear here.",
-          "sources": "Based on {practice} practice attempts, {exercises} exercise attempts, {checkpoints} checkpoint attempts and {exams} exam submissions in the last {days} days."
+          "sources": "Based on {practice} practice attempts, {exercises} exercise attempts, {checkpoints} checkpoint attempts and {exams} exam submissions in the last {days} days.",
+          "evidencePractice": "{attempts} attempt(s) by {students} student(s) · average {avg}% · {below} below 70%",
+          "evidenceStuck": "{stuck} of {students} student(s) still failing on their latest attempt · {attempts} attempt(s) each on average",
+          "evidenceAvg": "average {avg}%",
+          "evidenceExam": "{missers} of {students} student(s) missed it on their latest submission · {rate}% miss rate"
         }
       }
     },

messages/es.json

@@ -1649,7 +1649,11 @@
           "severity": "Gravedad",
           "allClear": "Sin puntos de confusión en este periodo: nadie está atascado en un ejercicio, checkpoint, práctica o pregunta de examen.",
           "noData": "Aún no hay actividad de estudiantes en este periodo. Cuando intenten ejercicios, checkpoints, prácticas o exámenes, sus resultados aparecerán aquí.",
-          "sources": "Basado en {practice} intentos de práctica, {exercises} intentos de ejercicio, {checkpoints} intentos de checkpoint y {exams} entregas de examen en los últimos {days} días."
+          "sources": "Basado en {practice} intentos de práctica, {exercises} intentos de ejercicio, {checkpoints} intentos de checkpoint y {exams} entregas de examen en los últimos {days} días.",
+          "evidencePractice": "{attempts} intento(s) de {students} estudiante(s) · promedio {avg}% · {below} por debajo del 70%",
+          "evidenceStuck": "{stuck} de {students} estudiante(s) siguen fallando en su último intento · {attempts} intento(s) cada uno en promedio",
+          "evidenceAvg": "promedio {avg}%",
+          "evidenceExam": "{missers} de {students} estudiante(s) la fallaron en su última entrega · {rate}% de fallo"
         }
       }
     },

tests/unit/confusion-hotspots.test.ts

@@ -116,7 +116,8 @@ describe('exercise hotspots', () => {
     const hot = bySc(await run(db), 'exercise')[0]
     // u1 peaked at attempt 6, u2 at attempt 1 → mean 3.5
     expect(hot.avgAttempts).toBe(3.5)
-    expect(hot.evidence).toContain('3.5 attempt(s)')
+    // Attempt totals are a practice-only counter; exercises report the mean.
+    expect(hot.totalAttempts).toBeNull()
   })
 
   it('reports no hotspot when everyone eventually passes', async () => {
@@ -245,6 +246,9 @@ describe('practice-topic hotspots', () => {
     expect(hot.avgScore).toBe(60)
     expect(hot.studentsAffected).toBe(2)
     expect(hot.lessonId).toBe(4)
+    // The page renders this count, so it must be attempts and not students.
+    expect(hot.totalAttempts).toBe(3)
+    expect(hot.studentsAttempted).toBe(3)
   })
 
   it('excludes attempts older than the look-back window', async () => {