<!-- source: openspec/changes/add-muse-translation-mode/proposal.md -->

# Add Muse translation mode — chat-as-translation-medium for polyglot collaboration

> **⚠ Schema-rename overlay — RAP-1170 (Wave 1, 2026-05-22).** This change was drafted against the pre-rename `canvas_*` table names. Before implementing, apply the rename map from `openspec/current/canvas.md § Naming clarification`: `canvas_sessions → ideas`, `canvas_messages → messages`, `canvas_files → files`, `canvas_invitees → spec_invitees`, and `canvas_ideas` / `canvas_attachments` / `canvas_instructions` / `canvas_tool_uses` / `canvas_stage_events` / `canvas_daily_costs` dropped — see the post-rename schema in `openspec/current/db/entities.md § Project → spec → idea hierarchy`. Inline `canvas_*` references in this folder's `proposal.md` / `design.md` / `tasks.md` / `verification.md` are deliberately left unmodified to preserve drafting context.

> **Status:** proposed.
> **Owner:** Pavel Rapoport <pavel@rapoport.studio>.
> **Linear issue:** RAP-1131 (epic RAP-1124 — Unpack studio product model).
> **Opened:** 2026-05-20.
> **Authority:** D-PM-6 value 4 (Polyglot collaboration) in `openspec/archive/2026-05-21-define-studio-product-model/design.md`; `_internal/platform/manifesto.md § Values § 4`.
> **Affects code:** new `intent: 'translation'` on `packages/muse/src/modes/architect`; chat surface gains a per-message language indicator + optional translated-view toggle; `canvas_messages` gains a nullable `source_locale text` column.
> **Affects spec at archive:** `openspec/current/canvas.md` — chat-message contract amends with `source_locale` + translation semantics; `openspec/current/muse/research.md` (or wherever Muse intents are documented) — `'translation'` added to the intent union.
> **Blast radius:** medium. New Muse intent + a chat-surface affordance + one nullable DB column. Behind a per-canvas opt-in flag in v1 (no default-on); existing canvases unaffected until the flag flips.
> **Capability prefix:** `MTM` (Muse Translation Mode). Decisions ratify as `D-MTM-N`.

---

## Why

Manifesto value 4 (polyglot collaboration) commits to bridging founder ↔ specialist when they don't share a working language. Today's chat assumes a single working language per canvas; a founder writing Russian and a specialist replying in English produces two parallel streams that never reconcile in the artefact.

Three real engagements already hit the seam:
1. Moldovan founder (RU) + EU specialist (EN) — current workaround is the founder switching to broken English, which the specialist then has to interpret-twice (broken EN → intended RU → engineering response).
2. Romanian founder (RO) writing in RO, expecting the spec to land in EN for the global market.
3. RU-native founder collaborating with EU specialists (EN) on regulated workflows — terminology drift across languages produces silent contract errors.

A chat that mediates the translation — both sides write in their own language, Muse translates each turn into the other's working language, the artefact lands in the canonical project language — turns the seam into a feature.

## Scope

Seven decisions, ratified as `D-MTM-1..7`. See `design.md` for the full text.

* **D-MTM-1 — Translation provider.** Anthropic-native — same Claude API the existing Muse turn already calls. No new vendor, no separate API key, no on-device model in v1. Translation is a system-prompt-shaped subroutine of the existing turn.
* **D-MTM-2 — Surface.** Inline per message — each `canvas_messages` row stores the original text + a translated view. UI renders the original by default with an inline "show in English" toggle (or whichever the viewer's working language is). No side-by-side pane in v1.
* **D-MTM-3 — Persistence.** Both — original text (canonical, immutable, in the writer's language) lives in `canvas_messages.content`. The translated view is rendered on demand from a new `canvas_messages.translated_content jsonb` map keyed by target locale, populated lazily by Muse on first viewer request.
* **D-MTM-4 — Source locale column.** `canvas_messages` gains a nullable `source_locale text`. NULL = legacy row, locale unknown; new rows always populate it from the writer's session locale.
* **D-MTM-5 — Per-brand client_vocabulary integration.** Translation prompts include the brand's `client_vocabulary` (from `openspec/brands/<slug>/identity.md § Vocabulary`) as a forced-term mapping. Domain words preserve their canonical form across languages — e.g., a Romanian/Russian fintech where "compliance" must always translate to a specific brand-blessed term, not the LLM's default.
* **D-MTM-7 — Locale set (v1: RU / EN / RO).** Hebrew is intentionally excluded in v1. HE was removed from the studio's chrome locale set on 2026-05-16 because the prior shipment was AI-translated with no native review (RAP-893 archive). RTL-capable primitives are preserved for a future properly-translated locale; until then the translation mode covers LTR pairings only.
* **D-MTM-6 — Opt-in flag.** `canvas_sessions.translation_enabled boolean default false`. Founder opts in at canvas creation (or later via settings). Existing canvases are not migrated.

## Out of scope

* On-device / offline translation — defer until proven Anthropic-API-bound cost is material.
* Side-by-side pane UI — adds layout complexity without proven need; promote when the inline toggle proves insufficient.
* Real-time / streaming translation per token — translation is a per-message subroutine, not per-token.
* Voice / audio translation — text-only in v1.
* Per-participant locale overrides — viewer's working language comes from session locale per D-MTM-2; per-canvas-per-participant overrides are a future affordance.
* Migration of existing canvases to default-on — D-MTM-6 keeps it opt-in.

## Verification

See `verification.md` — file-existence + reviewer-confirms for D-MTM-1..7.

## Lessons consulted

* `cookie_law_jurisdictions_research.md` — locale handling already touches CNIL-grade behaviour; new locales added here don't trigger new consent surfaces (translation is per-canvas, not telemetry).
* `feedback_muse_architect_naming.md` — user-facing copy uses "Muse Architect" full form on the translation-mode surface, not the bare "Muse".
* `rap_893_complete.md` — Hebrew locale was removed 2026-05-16 (AI-translated chrome, no native review); v1 locale set is RU/EN/RO LTR-only per D-MTM-7.
* `openspec_bundle_tripwire_gzipped.md` — change adds markdown only at scaffold time; no bundle impact.
