uttrflow / uttrflow/uttrflow-swift
Terminology drifts between "dictation" and "transcript" and between "tidying" and "clean-up", and the tidying settings are split across three places
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
The same few things are called different names on different screens, and one setting is split across three places. All on `main`.
**The words from one dictation: "dictation" or "transcript"**
| Where | Wording |
|---|---|
| Sidebar, Dictation and History pages, Home | "Dictation", "Every dictation, kept on this Mac." (`Sources/UttrflowUX/HistoryPresentation.swift:136`), "3 dictations today" |
| Settings → Privacy | "Keep transcripts for" (`Sources/UttrflowUX/SettingsPresenter.swift:604`); reset counts "saved transcripts" (`:709`) |
| Settings → General shortcuts | "Paste last transcript", "Copy last transcript" (`Sources/UttrflowUX/ShortcutRegistry.swift:41`, `:46`) |
**What happens to the words after they are heard: "tidying" or "clean-up"**
| Where | Wording |
|---|---|
| Settings → Languages, Style page | group "Tidying up", row "How much Uttrflow tidies" (`SettingsPresenter.swift:265-271`, `Sources/UttrflowUX/StylePagePresentation.swift:130-131`) |
| Settings → Dictation | group "Clean-up steps" (`Sources/UttrflowUX/SettingsDestinations.swift:46`) |
| Menu bar, floating button | "Tidying up…" (`Sources/UttrflowUX/MenuBarPresentation.swift:394`) |
| Dictation and Insights figure | "the clean-up left exactly as you said them" (`Sources/UttrflowUX/MainDictationPresentation.swift:158-161`) |
| Diagnostics | stage "Tidying up", rows "Clean-up steps" and "No clean-up ran" (`Sources/UttrflowUX/DiagnosticsPresentation.swift:328`, `:392`, `:411`) |
| Account plans | "the clean-up models that need a subscription" (`Sources/UttrflowUX/AccountPagePresentation.swift:298`) |
**Where those settings live**
- The tidying level is in Settings → **Languages** and again on the **Style** page.
- The clean-up steps that decide most of what the level actually does (filler words, stammers, self-corrections…) are in Settings → **Dictation**, with no mention of the level, and the level's explanation does not mention the steps.
- The language list is in Settings → Languages and again on the Style page.
**Setting up the speech model**
"Setup hasn't finished" (menu bar, `MenuBarPresentation.swift:389`), "Speech recognition needs to finish setting up before you can dictate." (`Sources/UttrflowCore/Errors/SpeechEngineError.swift:20`), "Speech model" (onboarding rail and Diagnostics), "Setting things up" (onboarding). The recovery button wording is already #561.
#657 asks for a contributor-facing map of internal names (modules, types, documents) for AI suggestions and clean-up. This issue is about the words people read in the app, and where the settings sit.
## Why it matters
Someone looking for "how long are my dictations kept" has to know that the setting says "transcripts". Someone who wants to keep their "um"s looks at "How much Uttrflow tidies" on the Languages tab, and the switch that actually controls filler words is two tabs away under a different name (the Light level's description is also wrong, which is a separate issue). Consistent nouns are also what make localisation (#531) tractable.
## How to reproduce
Read the strings above, or walk the Settings tabs and the main-window pages looking for where filler-word removal is controlled.
## Acceptance criteria
Product decisions (hence `needs-info`):
- One noun for a dictation's saved words (probably "dictation", matching the sidebar) and one for the processing step ("tidying" or "clean-up").
- One home for the tidying level and the clean-up steps, with the other screen linking to it rather than repeating it.
Then:
- The chosen terms are used in every string listed above; a short glossary goes in `Docs/ux-settings-model.md` so new strings follow it.
- Tests that pin the changed strings are updated (`SettingsPresenterTests`, `StylePagePresentationTests`, `MenuBarPresentationTests`, `DiagnosticsPresentationTests`, `ShortcutRegistry` users).
Contributor guide
Research direction
Start by reviewing the listed presentation and settings files, especially SettingsPresenter.swift, StylePagePresentation.swift, SettingsDestinations.swift, and the menu bar, diagnostics, account, shortcut, and error presentations. Check the referenced SettingsPresenterTests, StylePagePresentationTests, MenuBarPresentationTests, DiagnosticsPresentationTests, and ShortcutRegistry users. Done means the product terms and settings location are decided, all listed strings and tests agree, and the glossary is added to Docs/ux-settings-model.md.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- design, desktop
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100