Whale-school: hover translation cards for cross-language identifiers

[Hmbown]

Problem. As of 205370106 feat(agents): deterministic whale-species naming for sub-agents, sub-agent identifiers render in any of several languages — names like 海氏矮海豚, 侏儒抹香鯨, 小须鲸, and Melon-headed now appear side by side in the agents panel. The same will be true of model family names (通义千问/Qwen, 深度求索/DeepSeek), command names, and any other identifier that doesn't naturally translate. Today an English speaker can't say 海氏矮海豚 and a Mandarin speaker can't read Melon-headed. For a project that's deliberately cross-cultural — DeepSeek-first, China-region-aware, global by default — this is a missed identity-and-pedagogy feature.

Shape — hover translation cards. Hover (TUI focus / desktop mouse / mobile long-press) any identifier rendered in a language other than the user's primary language. A small bordered card appears:

• Original term
• Native-language gloss
• IPA transcription with tone marks for tonal languages (Mandarin, Cantonese, Vietnamese, Yoruba)
• One-line pedagogical breakdown — e.g. for 海氏矮海豚:

  hǎi-shì = "Heaviside" (English surname, after the 19th-c. mathematician); ǎi = "short"; hǎi-tún = "porpoise", literally "sea-pig"

• "Pin to whale-school deck" affordance (lands fully in sibling issue for the learning sidebar)
• Audio glyph (deferred to a follow-up — text first)

Where it shows up.

• Sub-agent species names (immediate win — the trigger).
• Model family names in the picker, paired with the family palette.
• Slash commands when the user's language ≠ the command's natural language.
• Error strings that survive untranslated.

Architecture sketch.

• New module crates/agent/src/translation.rs:

  pub struct TranslationCard {
      pub term: String,
      pub gloss: String,
      pub ipa: Option<String>,
      pub etymology: Option<String>,
      pub source_lang: Lang,
      pub target_lang: Lang,
      pub source: TranslationSource,
  }
  pub trait TranslationProvider: Send + Sync {
      fn lookup(&self, term: &str, src: Lang, tgt: Lang) -> Option<TranslationCard>;
  }

• Seed dictionary crates/agent/data/whale-species-translations.toml, deterministically covering every whale species the deterministic-naming feature can produce, for at least en ↔ zh ↔ ja ↔ es.
• Optional online backend (config-gated) — provider trait impl that calls a configured translation API or a local LLM via the existing tool_agent lane.
• Cards source-cited — no silent hallucinations. If neither seed dict nor backend has the term, the card honestly says "translation not available — configure [translation.backend] in config.toml".

Acceptance.

• TUI hover over a Chinese species name renders pinyin + IPA + tone marks + etymology.
• TUI hover over an English species name with a Mandarin primary language renders the corresponding pinyin+gloss.
• Every entry in the seed dict passes a structural unit test (term + gloss + IPA + source-language tag, all present).
• Same widget renders in the Tauri desktop shell via serve --http — one source of truth in crates/agent.
• Config knob [translation] enabled = true, primary_lang = "en", learn_langs = ["zh", "ja"] honored.
• Card content is deterministic for terms in the seed dict.

Notes.

• Defer until the model family palette lands so we have the family-identity scaffolding to hang language metadata on.
• This is the kind of feature that defines codewhale's identity: cross-language pedagogy as a first-class affordance, not an afterthought.

Far-out — milestone v0.9.0. Building toward the whale-school sidebar issue.

Slate item 17/18. Tracking doc: .private/issue-slate.md (maintainer-only).