The garden learns which language a card is in, and read-aloud stops guessing

Phase 28 (c), the last of the phase. A word met inside a Portuguese
document is a Portuguese card: migration 0018 mirrors documents.doc_lang
onto vocab_words, set server-side from the ownership lookup capture was
already making. Every card still reviews — filtering the queue to the
half she is learning would drop the words she actually met.

Read-aloud was the larger surprise. detectLang routed Han/kana to
Chinese and everything else to en-US, so the zh pair was accidentally
right and every Latin pair wrong. doc_lang now reaches the client
read-only on the document JSON, and docLang(text, verdict) answers for a
passage taken out of it — with the script test still winning, because
quoted Chinese must never be spelled out one "Chinese letter" at a time.

Claude-Session: https://claude.ai/code/session_01GJHNvirh7Hzhc9RL3HAvz7

web/src/App.tsx

@@ -615,6 +615,7 @@ export default function App() {
                   <EditorCore
                     key={`${currentDoc.id}:${editorEpoch}`}
                     docId={currentDoc.id}
+                    docLang={currentDoc.doc_lang}
                     initialContent={currentDoc.content}
                     onChange={handleEditorChange}
                     segmenter={segmenter}

web/src/api/client.ts

@@ -44,8 +44,18 @@ export interface Document {
   // When true, this document's automatic snapshots are never pruned, so its
   // full writing trail survives as authorship evidence (see the passport).
   preserve_history: boolean
+  // Which language this document is written in, as decided server-side by the
+  // checkpoint pass: '' | 'en' | 'pair' ('' reads as English). Read-only — the
+  // editor never sends it. It is here so read-aloud can use the right voice on a
+  // document written in her own language.
+  doc_lang: DocLang
 }
 
+// The document-language verdict, shared by documents and garden cards. 'pair'
+// names the writer's own language rather than a language code, so changing her
+// pair re-reads her documents instead of stranding a stale name on them.
+export type DocLang = '' | 'en' | 'pair'
+
 // Fields the editor sends on auto-save. All optional so a rename can send title
 // alone; the editor sends the full set.
 export interface DocUpdate {
@@ -125,6 +135,9 @@ export interface VocabWord {
   phonetic: string
   example: string
   doc_id: string | null
+  // The language of the document this word was met in — the card's own language
+  // (migration 0018). Read-aloud needs it: "comum" is unguessable from letters.
+  lang: DocLang
   due_at: string
   interval_days: number
   ease: number

web/src/audio/speech.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { nativeLang, speak, stopSpeech } from './speech'
+import { docLang, nativeLang, speak, stopSpeech } from './speech'
 import { resetPackForTests, setPackLang } from '../i18n'
 
 // Read-aloud has two jobs beyond "make a sound": ask for the right pace, and ask
@@ -85,3 +85,33 @@ describe('nativeLang', () => {
     expect(bodies.at(-1)).toMatchObject({ text: 'chat', lang: 'fr-FR' })
   })
 })
+
+describe('docLang', () => {
+  // The document's verdict is the answer for a passage lifted out of it, because
+  // for a Latin pair there is no other answer available: an English sentence and
+  // a Portuguese one are the same letters.
+  it('reads a flipped document in her own language', () => {
+    setPackLang('pt-PT')
+    expect(docLang('Ontem foi difícil.', 'pair')).toBe('pt-PT')
+  })
+
+  it('reads an English document in English, and treats the backfill as English', () => {
+    setPackLang('pt-PT')
+    expect(docLang('Yesterday was hard.', 'en')).toBe('en-US')
+    expect(docLang('Yesterday was hard.', '')).toBe('en-US')
+  })
+
+  it('lets the script win over the verdict, so quoted Chinese is never spelled out', () => {
+    // An English document quoting Chinese is 'en' by verdict, and the English
+    // voice reads Han characters one "Chinese letter" at a time — the one
+    // failure worse than silence.
+    setPackLang('zh')
+    expect(docLang('你好世界', 'en')).toBe('zh-CN')
+  })
+
+  it('is what the editor selection and the garden card ask for', () => {
+    setPackLang('fr')
+    speak('Le chat dort.', docLang('Le chat dort.', 'pair'))
+    expect(bodies.at(-1)).toMatchObject({ text: 'Le chat dort.', lang: 'fr-FR' })
+  })
+})

web/src/audio/speech.ts

@@ -90,6 +90,24 @@ export function nativeLang(): string {
   return pack().locale
 }
 
+// docLang turns a document-language verdict ('' | 'en' | 'pair', decided
+// server-side — see internal/suggestions/doclang.go) into a locale for a passage
+// taken out of that document. It is what the editor's read-aloud and the garden's
+// review card ask instead of guessing.
+//
+// The script test still wins, and that is not redundant with the verdict. A
+// Chinese sentence quoted inside an English document is 'en' by verdict and
+// still has to be read by the Chinese voice: the English voice spells Han
+// characters out one "Chinese letter" at a time, which is the one failure loud
+// enough to be worse than no audio. In the other direction there is nothing to
+// test — an English sentence inside Portuguese prose looks exactly like the
+// Portuguese around it — so the document's verdict is the only answer available,
+// and it is the answer this phase decided on.
+export function docLang(text: string, verdict: string): string {
+  if (CJK.test(text)) return 'zh-CN'
+  return verdict === 'pair' ? pack().locale : 'en-US'
+}
+
 // speak reads `text` aloud, cancelling anything already in flight so rapid taps
 // don't queue up. `lang` defaults to a guess from the text (Chinese vs English)
 // so callers can just pass the selection; pass an explicit locale to override.

web/src/components/Editor/EditorCore.tsx

@@ -33,8 +33,8 @@ import { Composition } from './Composition'
 import { RewritePreview, type RewriteStatus } from './RewritePreview'
 import { planBatch } from './acceptBatch'
 import { entryId, idAfterRemoval, stepId, type Direction, type Span } from './triage'
-import { api, type Suggestion, type SuggestionType, type WordInfo } from '../../api/client'
-import { speak, speechSupported } from '../../audio/speech'
+import { api, type DocLang, type Suggestion, type SuggestionType, type WordInfo } from '../../api/client'
+import { docLang as docLocale, speak, speechSupported } from '../../audio/speech'
 import type { SpellChecker } from '../../hooks/useSpellChecker'
 import { fromIME } from '../../lib/ime'
 import type { Segmenter } from '../../lib/segment'
@@ -65,6 +65,13 @@ export interface EditorChange {
 interface Props {
   // Changing docId reloads the editor with that document's content.
   docId: string
+  // Which language this document is written in, as the server decided it
+  // ('' | 'en' | 'pair'). Read-aloud is the only thing here that reads it: a
+  // Portuguese selection has to be read by the Portuguese voice, and nothing in
+  // the letters says so. Updated by the server on save, so it trails a language
+  // flip by one auto-save — a passage read in the old voice once is the whole
+  // cost of not blocking the editor on a check.
+  docLang: DocLang
   initialContent: string
   onChange: (change: EditorChange) => void
   // LLM suggestions to highlight; accept/dismiss notify the parent for the API
@@ -255,6 +262,7 @@ interface RewriteState {
 // decoration layer. Hovering a highlight opens its SuggestionCard.
 export function EditorCore({
   docId,
+  docLang,
   initialContent,
   onChange,
   suggestions,
@@ -1532,8 +1540,10 @@ export function EditorCore({
           <SelectionBubble
             style={{ top: selection.top, left: selection.left, transform: 'translateY(calc(-100% - 8px))' }}
             onRewrite={handleRewrite}
-            onSpeak={speechSupported() ? () => speak(selection.text) : null}
-            onSpeakSlow={speechSupported() ? () => speak(selection.text, undefined, true) : null}
+            onSpeak={speechSupported() ? () => speak(selection.text, docLocale(selection.text, docLang)) : null}
+            onSpeakSlow={
+              speechSupported() ? () => speak(selection.text, docLocale(selection.text, docLang), true) : null
+            }
           />
         )}
         {rewrite && (

web/src/components/Garden/GardenPanel.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { api, type VocabGrade, type VocabWord } from '../../api/client'
-import { speak, speechSupported, stopSpeech } from '../../audio/speech'
+import { docLang as docLocale, speak, speechSupported, stopSpeech } from '../../audio/speech'
 import { useFocusTrap } from '../../hooks/useFocusTrap'
 import { usePack, type Line } from '../../i18n'
 import { JournalView } from './JournalView'
@@ -314,7 +314,21 @@ function GardenView({
                       {blossom(w.reps)}
                     </span>
                     <span className="flex min-w-0 flex-1 flex-col">
-                      <span className="truncate text-sm font-bold text-plum">{w.word}</span>
+                      <span className="flex min-w-0 items-center gap-1.5">
+                        <span className="truncate text-sm font-bold text-plum">{w.word}</span>
+                        {/* Only a card in her own language is marked. An English
+                            garden with a badge on every blossom would be a
+                            garden with no badges at all; the marker exists so
+                            the rare Portuguese word is legible among them. */}
+                        {w.lang === 'pair' && (
+                          <span
+                            className="shrink-0 rounded-full px-1.5 py-0.5 text-[9px] font-bold lowercase"
+                            style={{ background: 'var(--color-surface-alt)', color: 'var(--color-muted)' }}
+                          >
+                            {t.nativeName}
+                          </span>
+                        )}
+                      </span>
                       {(w.gloss || w.definition) && (
                         <span
                           className="truncate text-xs"
@@ -354,7 +368,7 @@ function GardenView({
                         {speechSupported() && (
                           <button
                             type="button"
-                            onClick={() => speak(w.word)}
+                            onClick={() => speak(w.word, docLocale(w.word, w.lang))}
                             className="rounded-full px-2.5 py-1 text-xs font-semibold"
                             style={{ background: 'var(--color-surface-alt)' }}
                           >
@@ -477,7 +491,7 @@ function ReviewSession({
                 <>
                   <button
                     type="button"
-                    onClick={() => speak(card.word)}
+                    onClick={() => speak(card.word, docLocale(card.word, card.lang))}
                     aria-label={`Pronounce ${card.word}`}
                     className="flex h-6 w-6 items-center justify-center rounded-full text-xs"
                     style={{ background: 'var(--color-surface)' }}
@@ -488,7 +502,7 @@ function ReviewSession({
                       worth hearing stretched out. */}
                   <button
                     type="button"
-                    onClick={() => speak(card.word, undefined, true)}
+                    onClick={() => speak(card.word, docLocale(card.word, card.lang), true)}
                     aria-label={`Pronounce ${card.word} slowly`}
                     title={t.garden.readSlowly}
                     className="flex h-6 w-6 items-center justify-center rounded-full text-xs"