Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Tasks for 077 key-based interface texts and downloadable languages"
Tasks: Key-Based Interface Texts and Downloadable Languages
Input: Design documents from specs/077-key-based-localization/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
Tests: Included. The spec makes the smoke test part of the feature (FR-006, research R12), and the constitution makes it the PR gate.
Organization: by user story; the stories map onto the three pull requests of the plan (US1 → PR 1 in nota, US2 → PR 2 in nota-translations, US3 + US5 + US4 → PR 3 in nota).
Format: [ID] [P?] [Story] Description
- [P]: can run in parallel (different files, no dependency on an unfinished task)
- [Story]: US1…US5 from spec.md
- Paths: nota paths are relative to the nota repository root;
nota-translations/…paths are relative to a checkout ofnota-daw/nota-translations.
Phase 1: Setup
Purpose: baseline for the "no visible change" proof and the migration tool skeleton.
- T001 Record the pre-migration commit SHA of
developinspecs/077-key-based-localization/quickstart.md§ PR 1 (the--verifybaseline), and capture English + French reference screens with the headless shots harness (NOTA_UI_LANGUAGE=en/fr) into/tmp/nota-077-before/(not committed) - T002 Create
scripts/loc-migrate.py(SPDX header; Python 3 stdlib only) with the CLI--plan,--apply,--verify <commit>and a module docstring citing research R4; no logic yet
Phase 2: Foundational (blocks every story)
Purpose: the format-v2 language layer the app, the migration and the repository checks all share.
- T003 Rework
src/managed/Nota.Application/Localization/TranslationTable.csto contractcontracts/language-file.md:formatVersionmust be2(1 and higher rejected with the message "language file format N is not supported");codelower-case BCP-47 primary tag equal to the file name; keys must match^[a-z0-9_]+(\.[a-z0-9_]+)+$and be ≤ 80 chars; requiredplural(excepten); values a non-empty string or{ "other" required, "one" optional }; invalid entries go to aProblemslist(key, problem)instead of failing the file; removeKeyOf(text, context) - T004 Add key-shape and placeholder validation against a reference table to
TranslationTable(ValidateAgainst(TranslationTable english)): shape mismatch (text vs plural),othermust use exactly the reference's placeholders,onemay drop but not add, unknown keys reported; returns problems and coverage percent (translated valid entries of reference keys ÷ reference keys, rounded down) - T005 Add
KeySetHashtoTranslationTable: SHA-256, lower-case hex, first 16 chars, over the ordinally sorted lineskey \t (text|plural) \t sorted placeholder indices joined by ","joined with\n(contract language-file § Key-set hash) - T006 [P] Replace per-code plural rules in
src/managed/Nota.Application/Localization/UiLanguage.cswith rule ids:Plural(string rule, long n)forone_is_1andone_is_0_1,IsKnownRule(string); keepNormalize/IsPending - T007 Rework
src/managed/Nota.Application/Localization/Loc.cstocontracts/loc-api.md: English built in:en.jsonembedded inNota.Application(logical nameNota.Localization.en.json) and loaded lazily byLoc;Install(TranslationTable? table, string code)unchanged;T(key),F(key, args),Plural(key, n)with lookup running → English → key (+ one log line per key via aMissingKeyevent); plural form by the running table'sPluralRule; removeFCand everycontextparameter; keep the format fallback andUsedBeforeInstall - T008 [P] Update
src/managed/Nota.App/TExtension.csto a key-only markup extension ({app:T menu.file.save_as}), removingContext; update its header comment - T009 [P] Write v2 fixtures in
tests/Nota.SmokeTest/Fixtures/Languages/:en-ref.json(small reference),xx.json(valid,one_is_1),xx-broken.json(bad placeholder, shape mismatch, unknown key, empty value),xx-v1.json(format 1, rejected),xx-badrule.json(unknownplural), plusverdicts.jsonlisting each file's expected load result, problems and coverage (shared with nota-translations, research R11) - T010 Rewrite
DesignTokenCheck.RunLanguageintests/Nota.SmokeTest/DesignTokenCheck.Localization.csfor v2: fixture verdicts fromverdicts.json, plural rules by id, key-set hash stable under English wording change and changed by key add/remove/shape/placeholder change, lookup fallback running → English → key
Implementation notes (PR 1): English moved to src/managed/Nota.Application/Localization/en.json, embedded beside Loc (the smoke test and other projects that do not reference Nota.App need English too). Keys shared by exactly two groups get a key per group; common.* from three groups (research R2). T001: before-screens were not captured; instead --verify proves text equality per call site, and a headless harness (main window, native menu, 10 Preferences pages, mixer, EN + FR) found no key shown and no missing-key event. T021: the allow-list did not change (2644 entries, none stale). T020 also accepts string.Format(culture, Loc.T(key), …) (4 call sites format with NotaNum.Culture). The render-pool "overloaded" smoke checks flaked while the machine was busy; an idle rerun passed.
Checkpoint: the language layer builds and its smoke checks pass on fixtures; call sites are not migrated yet (the build is red until US1's rewrite lands — do Phase 2 and US1 on one branch).
Phase 3: User Story 1 — Change an English text without breaking translations (P1) 🎯 MVP · PR 1
Goal: every interface text is looked up by a stable key; en.json is the only English source; French still embedded; nothing visible changes.
Independent test: quickstart § PR 1 steps 3–6.
Migration tool
- T011 [US1] Implement scanning in
scripts/loc-migrate.py: port theLocT,LocF,LocPlural,LocXamlpatterns fromtests/Nota.SmokeTest/DesignTokenCheck.Localization.cs(lines ~196–203) oversrc/managed/**/*.csandsrc/managed/**/*.axaml; collect (text, context, plural one/other, file, line); exit non-zero listing anyLoc.call it cannot parse (excludingTExtension.cs) - T012 [US1] Implement key generation (research R2) in
scripts/loc-migrate.py: area table from file name (PreferencesWindow*→preferences,ArrangementView*→arrangement,Controls/<X>Views.cs→device.<x>,MainWindow*→main, menus →menu, … — unknown file → fail with the file name so the table is extended); sub-area from the partial suffix; slug = first ≤ 6 ASCII words of the English text, lower-case,_-joined, punctuation and{n}dropped;common.<slug>when the same text and shape is used in ≥ 3 areas; the 3 context calls / 4|keys get distinct keys by context; collisions_2,_3; every key validated against^[a-z0-9_]+(\.[a-z0-9_]+)+$, ≤ 80 chars - T013 [US1] Implement
--planinscripts/loc-migrate.py: writekeymap.tsv(text, context, plural, files, key) at the repo root (git-ignored via.gitignore); read an existingkeymap.tsvback so hand-renamed keys stick; validate uniqueness after edits - T014 [US1] Implement
--applyinscripts/loc-migrate.py: writesrc/managed/Nota.Application/Localization/en.json(formatVersion: 2,code: en,name: English, keys grouped by area, sorted), convertsrc/managed/Nota.App/Languages/fr.jsonto v2 (plural: one_is_0_1, keys via the map,notesupdated, orphans printed not carried), rewrite call sites in place (Loc.T("text"[, "ctx"])→Loc.T("key"),Loc.F("text", …)→Loc.F("key", …),Loc.Plural(n, "one", "other"[, ctx])→Loc.Plural("key", n),{app:T 'text'[, Context=c]}→{app:T key}), preserving surrounding formatting - T015 [US1] Implement
--verify <commit>inscripts/loc-migrate.py: for every call site at<commit>and its migrated counterpart, asserten[key]equals the old English (and plural one/other) andfr[key]equals the old French value; print differences and exit non-zero if any
Run the migration
- T016 [US1] Run
python3 scripts/loc-migrate.py --plan, reviewkeymap.tsvarea by area (rename unclear keys, merge true duplicates intocommon.*), re-run--planuntil clean - T017 [US1] Run
python3 scripts/loc-migrate.py --apply; build; fix any call site the rewrite left uncompilable by hand (list them in the PR description) - T018 [US1] Update
src/managed/Nota.App/Languages/NotaLanguages.csto offer English fromLoc.English(noen.jsoninNota.App/Languagesany more) plus the embeddedfr.json, log an English load error if any; andsrc/managed/Nota.App/App.axaml.csTranslateAppMenuto look the macOS app-menu texts up by key; add theEmbeddedResourceforLocalization/en.jsontosrc/managed/Nota.Application/Nota.Application.csproj - T019 [US1] Run
python3 scripts/loc-migrate.py --verify <T001 SHA>→ 0 differences; spot-check screens against/tmp/nota-077-before/(SC-002)
Smoke checks on keys
- T020 [US1] Rewrite
DesignTokenCheck.RunLocalizationintests/Nota.SmokeTest/DesignTokenCheck.Localization.cs: extract key literals fromLoc.T/F/Pluraland{app:T key}; fail on a computed (non-literal) key, a key missing fromen.json, anen.jsonkey used nowhere, aPluralkey that is not a plural object or aT/Fkey that is one,Fplaceholders not matching the English pattern; keep French coverage / orphan / placeholder checks against the embeddedfr.json(until US3); keep the raw-literal ratchet - T021 [US1] Regenerate
tests/Nota.SmokeTest/LocalizationAllowList.txtwithNOTA_LOC_WRITE_BASELINE=1only if line matching changed; the list must not grow (diff reviewed) - T022 [P] [US1] Update
tests/Nota.SmokeTest/LanguageProjectTests.csto parse the v2fr.jsonwith the newTranslationTable.Parse
Contributor docs
- T023 [P] [US1] Rewrite
CONTRIBUTING.md§ Translating Nota (or the interface-text section): keys and the naming convention (research R2), adding a text = oneen.jsonentry +Loc.T("key"), changing wording edits onlyen.json, changing meaning or placeholders = new key, plurals, no contexts; mentionnota-translationsas "coming in the next release" (finalised in T053) - T024 [P] [US1] Update the header comments of
Loc.cs,TranslationTable.cs,NotaLanguages.cs,TExtension.csto cite spec 077 (keys) instead of "the English source text is the key"
Checkpoint (PR 1): scripts/build.sh green; quickstart § PR 1 passes; open PR 1 (Closes not yet — Part of #476).
Phase 4: User Story 2 — Translate Nota without touching the app (P2) · PR 2 (nota-translations)
Goal: the repository validates languages against Nota's references and publishes index.json.
Independent test: quickstart § PR 2.
- T025 [P] [US2] Add
nota-translations/LICENSE(full AGPL-3.0 text, same as nota'sLICENSE) - T026 [P] [US2] Write
nota-translations/README.md: what the repo is, file shape (link to a copy of the contract innota-translations/FORMAT.md), keys and the English reference (reference/<version>.json,develop.json), plurals and rule ids, placeholders, coverage, how to open a PR, how to preview a file in Nota (Load file…), licence - T027 [P] [US2] Copy
specs/077-key-based-localization/contracts/language-file.mdandcontracts/index.mdintonota-translations/FORMAT.md(translator-facing wording, same rules) - T028 [US2] Write
nota-translations/tools/validate.py(stdlib; SPDX header): implementscontracts/language-file.mdexactly asTranslationTable(T003–T005): parse, key regex, plural rule ids, shape/placeholder checks against eachreference/*.json, unknown key = error when in no reference / warning when only in older ones, coverage per key-set hash;--fixtures tools/fixturesmode compares againstverdicts.json; exit non-zero withlanguages/<code>.json: <key> — <problem>lines - T029 [P] [US2] Copy the fixtures and
verdicts.jsonfromtests/Nota.SmokeTest/Fixtures/Languages/(T009) intonota-translations/tools/fixtures/ - T030 [US2] Write
nota-translations/tools/sync_references.py(stdlib): listnota-daw/notatagsv*and thedevelophead via the public GitHub API, fetchsrc/managed/Nota.Application/Localization/en.jsonat each tag lackingreference/<version>.json(skip tags whose file is missing or format < 2), always refreshreference/develop.json - T031 [US2] Add index generation to
nota-translations/tools/validate.py(--write-index):index.jsonpercontracts/index.md—formatVersion: 1,generated,references(version → key-set hash), per valid languagecode,name,version(previous index version + 1 when the file's sha256 changed, else kept),commit(theHEADbeing indexed),path,size,sha256,coverageper hash - T032 [US2] Add
nota-translations/.github/workflows/check.yml: on pull_request →python3 tools/validate.py --fixtures tools/fixturesandpython3 tools/validate.py languages/*.json; job namecheck - T033 [US2] Add
nota-translations/.github/workflows/publish.yml: on push tomain, daily schedule,workflow_dispatch→ sync references, validate, write index, commitreference/+index.jsonto thepublishedbranch asgithub-actions[bot]only if changed; indexcommit= main's HEAD, which holds the language files - T034 [US2] Move French:
git mv-equivalent import ofsrc/managed/Nota.App/Languages/fr.json(v2, from PR 1) intonota-translations/languages/fr.json, with the commit message crediting its translators fromgit log --format='%an' -- src/managed/Nota.App/Languages/fr.jsonin nota (FR-012) - T035 [US2] Repository settings: after the first green
checkrun, addcheckas a required status check on rulesetmain: PR, squash(id 26514643); generated files go to thepublishedbranch, so no bypass is added - T036 [US2] Push the initial content (README, LICENSE, FORMAT, tools, workflows,
languages/fr.json) as the first commit onmain(sets the default branch), rungh workflow run publish.yml, confirmreference/develop.jsonandindex.jsonland; then open a test PR breaking a placeholder →checkfails naming the key; close it
Checkpoint (PR 2): quickstart § PR 2 passes.
Phase 5: User Story 3 — Get a language from Preferences (P2) · PR 3
Goal: the app lists, downloads, updates and removes languages; ships English only.
Independent test: quickstart § PR 3 steps 1–4, 7–8.
- T037 [P] [US3] Create
src/managed/Nota.Infrastructure/Languages/InstalledLanguages.cs: root<data>/languages(fromNotaPaths); per code<code>.json+<code>.meta.json{ "source": "repository" | "local", "path"?, "version"?, "commit"?, "sha256"?, "installed" };List(),Load(code)(repository → file, local → stored path),InstallFrom(stagingFile, meta)with atomic move,Remove(code), cleanup of leftover.staging-<code>.jsonon start - T038 [US3] Create
src/managed/Nota.Infrastructure/Languages/LanguageCatalog.cs: fetch<base>/published/index.json(<base>=https://raw.githubusercontent.com/nota-daw/nota-translations,NOTA_LANGUAGES_URLoverrides) once per run (cached); ignore an index with a higherformatVersionmajor ("update Nota to see more languages"); fit by own key-set hash, else the newest reference with version ≤ the app's (contracts/index.md § App behaviour);DownloadAsync(entry)viaRegistryClient.DownloadAsync(<base>/<commit>/<path>, size, sha256, staging, …), then parse + validate beforeInstalledLanguages.InstallFrom; any failure leaves the installed copy - T039 [US3] Register
LanguageCatalogandInstalledLanguagesin the app's service setup (whereModelStoreis registered) and exposeUpdateAvailable(code)comparing installedversionwith the index - T040 [US3] Update
src/managed/Nota.App/Languages/NotaLanguages.cs: offered languages = embedded English +InstalledLanguages.List();Find(code)loads installed files throughTranslationTable.Parse+ValidateAgainst(english)(problems logged); no network on this path - T041 [US3] Rebuild
src/managed/Nota.App/PreferencesWindow.Language.cspercontracts/language-row.md: combo items English / installed (· 97%muted, or· local file) / separator / available (· 82%+ download glyph); picking an available one downloads with inlineDownloading…progress, then the existing restart note; failureCouldn't download <Name> — <reason>and the combo returns to the running language;Update available+ Update; Remove;More languages are available onlinewhen the index is unreachable; followsDESIGN.md(Studio) — every new text viaLoc.Twith new keys inen.json - T042 [US3] Network policy (research R10) in
PreferencesWindow.Language.csand the launch path: fetch the index when the row is shown, and at launch with the daily update check only whenSettings.CheckForUpdatesis on; when off, show Show available languages (fetch on click) and never request on Nota's own initiative - T043 [US3] Remove
src/managed/Nota.App/Languages/fr.jsonand its embedding:src/managed/Nota.App/Nota.App.csprojembeds no language file (remove theLanguages\*.jsonitem and its comment at line ~56) - T044 [US3] Smoke: create
tests/Nota.SmokeTest/LanguageCatalogTests.cswith an in-processHttpMessageHandlerserving a fixture index + files (tests/Nota.SmokeTest/Fixtures/Languages/index/): list + fit + coverage, install, checksum mismatch keeps the old copy, higher indexformatVersionignored, offline → installed only, update offered whenversiongrows, remove,CheckForUpdatesoff → zero requests at start; wire intotests/Nota.SmokeTest/Program.cs - T045 [US3] Smoke: in
DesignTokenCheck.RunLocalizationdrop the embedded-French coverage checks (French is validated in nota-translations) and add "the app embeds onlyen.json" (SC-008); switchtests/Nota.SmokeTest/LanguageProjectTests.csfromfr.jsonto thexx.jsonfixture
Checkpoint: quickstart § PR 3 steps 1–4, 7–8 pass.
Phase 6: User Story 5 — Existing French users keep French after updating (P1) · PR 3
Goal: a stored but missing language is fetched in the background and applied after a restart.
Independent test: quickstart § PR 3 step 5.
P1 but placed after US3: it is built on the catalog and installed store from US3.
- T046 [US5] In
src/managed/Nota.App/App.axaml.csafter the main window is shown: ifSettings.Language≠en, has no valid installed file andCheckForUpdatesis on, download it in the background throughLanguageCatalog(start-up never waits); on success raise a "language ready" state shared with the Language row - T047 [US5] Show the " is ready" + Restart notice once per run in the status bar in
src/managed/Nota.App/MainWindow.Updates.cs(same pattern as the app update notice), and in the Language row; offline / checks off → row text<Name> will be downloaded when Nota is onlineor Download (contracts/language-row.md) - T048 [US5] Smoke in
tests/Nota.SmokeTest/LanguageCatalogTests.cs: storedfr, emptylanguages/→ English this run, background install, ready state set; handler offline → English, stored choice kept, no install
Phase 7: User Story 4 — Preview a translation in progress (P3) · PR 3
Goal: load a local file as the running language and see its problems.
Independent test: quickstart § PR 3 step 6.
- T049 [US4] Add Load file… to
src/managed/Nota.App/PreferencesWindow.Language.cs: file picker for.json, parse + validate against English, storesource: local+ path throughInstalledLanguages, select it, restart note; list up to 10key — problemlines then…and N more (see the log); a local language is never replaced by a download - T050 [US4]
NOTA_UI_LANGUAGEaccepts a path to a language file as well as a code (this run only, never saved) inApp.axaml.csInstallLanguage; update its doc comment - T051 [US4] Smoke in
tests/Nota.SmokeTest/LanguageCatalogTests.cs: localxx-broken.json→ loads, valid entries translated, broken ones English, problems matchverdicts.json; missing local path at start → English + problem
Phase 8: Polish & Cross-Cutting
- T052 Delete
scripts/loc-migrate.pyand thekeymap.tsvignore line in.gitignore(research R4) - T053 [P] Finalise
CONTRIBUTING.md§ Translating Nota: translations live innota-daw/nota-translations; adding a text in the app =en.jsononly - T054 [P] Add the "sync references" step (
gh workflow run publish.yml --repo nota-daw/nota-translationsafter the tag build) to.claude/skills/release/SKILL.md, then runscripts/sync-agent-skills.sh - T055 [P] Fixture parity: confirm
tests/Nota.SmokeTest/Fixtures/Languages/verdicts.jsonandnota-translations/tools/fixtures/verdicts.jsonare identical and both checks agree (R11) - T056 Run every step of
specs/077-key-based-localization/quickstart.mdand note results in the PR descriptions
Nota closing tasks (PR gates — run for each nota PR)
- T057 Run
scripts/build.sh(andscripts/build-linux.sh/scripts/build-win.ps1via CI) until native + managed + smoke test are green - T058 AGPL-3.0-only SPDX two-line header on every new source file (
scripts/loc-migrate.py,LanguageCatalog.cs,InstalledLanguages.cs,LanguageCatalogTests.cs, nota-translationstools/*.py) - T059 New dependency: none → N/A
- T060
CHANGELOG.md[Unreleased]: PR 1 → none (no user-visible change; mention in the PR); PR 3 → Changed "Languages other than English are downloaded from Preferences → Language and kept up to date; the app ships with English only" + Added "Load a language file to preview a translation" - T061 FEATURES.md via the
nota-featuresskill and the user manual vianota-docs(EN + RU page on choosing, updating and previewing a language; shots harness usesNOTA_UI_LANGUAGE=<path>for French);nota-docs/scripts/shortcuts.mjsreadsPreferencesWindow.ShortcutGroupsby literal text — make it resolveLoc.T("key")throughsrc/managed/Nota.Application/Localization/en.json(needed as soon as PR 1 is ondevelop); shortcuts: N/A - T062 Engine behaviour change: none → N/A
Dependencies & Execution Order
Phase dependencies
- Setup (1) → Foundational (2) → US1 (3). Phase 2 and US1 share a branch: the build is red between T007 and T017.
- US2 (4) needs US1 merged (it publishes v2 keys from
develop). - US3 (5) needs US2's
index.jsonto exist (tests use fixtures, but the release needs the real repo). - US5 (6) needs US3 (T037–T040). US4 (7) needs T037 and T040.
- Polish (8) after the stories of each PR; T052–T054 in PR 3.
Pull requests
| PR | Tasks |
|---|---|
| 1 (nota) | T001–T024, T057–T059, T062 |
| 2 (nota-translations) | T025–T036 |
| 3 (nota) | T037–T056, T057–T062 |
Within each story
Language layer before call sites; store before catalog; catalog before UI; smoke checks written with the code they cover.
Parallel opportunities
- Phase 2: T006, T008, T009 alongside T003–T005.
- US1: T022, T023, T024 alongside the migration run (different files).
- US2: T025, T026, T027, T029 together; T028/T030/T031 sequential (same tool files).
- US3: T037 alongside T038's design; T044 can be written against the contracts before T041.
- PR 2 can be built while PR 1 is in review (on a v2
fr.jsonproduced by the script).
Parallel example: User Story 2
Task: "Add nota-translations/LICENSE"
Task: "Write nota-translations/README.md"
Task: "Write nota-translations/FORMAT.md from the contracts"
Task: "Copy fixtures into nota-translations/tools/fixtures/"
Implementation strategy
- MVP = PR 1 (US1): keys everywhere,
en.jsonas source, French still embedded. It delivers the issue's priority and stands alone — stop and validate with quickstart § PR 1. - PR 2 (US2): repository and checks; no app change, safe to merge any time after PR 1.
- PR 3 (US3 + US5 + US4): downloads, then the upgrade path, then local preview; merge only with PR 2 live, and ship PR 2's content and PR 3 in the same release.
Phase 9: Convergence
- T063 Offer a Download button in the Language row when the stored language is not installed and Nota may not check on its own, in
src/managed/Nota.App/PreferencesWindow.Language.csper FR-021 (partial) - T064 Separate installed from available languages in the Language combo in
src/managed/Nota.App/PreferencesWindow.Language.csper contracts/language-row.md (partial) - T065 Fetch the language list in the background at start when the running language came from the repository and update checks are on, so Update is offered without a fetch on opening Settings, in
src/managed/Nota.App/LanguageDownloads.csper plan: research R10 (partial) - T066 Run the quickstart steps for PR 3 and note the results in the pull request per T056 (partial)