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

Open
#694 0 comments 0 reactions 0 assignees View on GitHub
area:general enhancement needs-info P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.