Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Tasks for the interface language selector, English + French (spec 068)"
Tasks: Interface Language Selector (English + French)
Input: Design documents from specs/068-ui-language/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/translation-file.md, contracts/loc-api.md, quickstart.md
Tests: Smoke-test checks are included because the plan relies on them to keep the
translation complete (constitution IV; plan § Testing). They follow the existing
DesignTokenCheck pattern. The UI itself is validated through quickstart.md.
Organization: Grouped by user story. US1 is large, so it is split into four delivery
sub-phases (3a–3d = plan slices 1–4). Each sub-phase lands with English output unchanged and
scripts/build.sh green, and can be its own pull request (constitution V).
Format: [ID] [P?] [Story] Description
- [P]: Can run in parallel (different files, no dependencies)
- [Story]: US1 … US5 from spec.md
- Paths are from the repo root.
src/managed/is shortened tomanaged/where it helps.
Rules that apply to every "wrap and translate" task (3a–3d)
These are written once here so each task can stay short.
- Wrap: a user-visible literal
"Save"becomesLoc.T("Save"); text with values becomes oneLoc.F("Delete {0} clips?", n)pattern; singular/plural becomesLoc.Plural(n, "{0} clip", "{0} clips"). Never glueLoc.Tfragments into a sentence (loc-api guarantee 3). A word with two meanings gets a context:Loc.T("Open", context: "menu"). - Do not wrap: user content (project / track / clip / scene / preset names, tags),
device and parameter names and their value labels (FR-004), proper nouns and product
names, unit symbols and musical notation, log messages, MCP text,
Nota.Remote. Literals that stay raw go intests/Nota.SmokeTest/LocalizationAllowList.txtwith a# data:reason. - English must not change: the English string at the call site is the key, so output is identical. Do not reword English while wrapping; a reword orphans its key.
- Translate: add the French value to
managed/Nota.App/Languages/fr.jsonusing the terms in glossary.md. Placeholders{0},{1}must match the key. Plurals needoneandother(French: 0 and 1 areone).fr.jsonis one shared file, so these edits are never[P]with each other. - Ratchet: delete the now-wrapped literals from
LocalizationAllowList.txt. The check fails on a stale line, so this cannot be forgotten. - Verify: run the smoke test; walk the area in French (
NOTA_UI_LANGUAGE=fr) at 100 % and 150 % interface scale for clipped or overlapping labels.
Phase 1: Setup
- T001 Create the git branch
feat/ui-languagefromdevelop(spec dirspecs/068-ui-language/); confirmscripts/build.shis green before any change (done with the caveats under Notes → Environment) - T002 Write
specs/068-ui-language/glossary.md: the French music vocabulary (piste, clip, scène, envoi, retour, bus, quantification, enveloppe, filtre, arrangement, session, mixeur, …) and the register rule from research R10 (infinitive for actions, e.g. "Enregistrer", "Supprimer la piste"; explanatory text avoids addressing the user directly). Ask the maintainers to confirm it before T022 (the first French text)
Phase 2: Foundational (blocks all stories) — plan slice 0
Purpose: the translation layer, startup install and the checks that keep it honest. No
visible change yet. Pure logic first so the smoke test can walk it, as it does InterfaceScale.
- T003 [P] Add
public string Language { get; set; } = "en";tomanaged/Nota.Application/Settings.csnext toInterfaceScale, with a doc comment in the same style ("Interface language code, lower-case,enorfr; anything else reads asen— spec 068"). Stored with the other Appearance preferences, never in the project - T004 [P] Create
managed/Nota.Application/Localization/UiLanguage.cs(SPDX header + why-comment, pure: no UI, no I/O):Default = "en";Normalize(string? code, IReadOnlyCollection<string> available)returns the lower-cased code if it is inavailable, else"en", never throws;Plural(string code, long n)returnsOneorOther— English:Onewhenn == 1; French:Onewhennis 0 or 1; a language with no rule uses English's;IsPending(stored, running, available)is true exactly whenNormalized stored differs from running (data-model § state) - T005 [P] Create
managed/Nota.Application/Localization/TranslationTable.cs(SPDX header, pure): parse a language file per contracts/translation-file.md —formatVersionmust be1(higher → skipped with an error, not thrown),codelower-case,name,notes,stringsmap of key → string or{ "one", "other" }; keys are the English text, a context-tagged key is"<text>|<context>"; duplicate keys are an error; a malformed file returns an error and no table, never throws. Immutable after construction; lookup is a dictionary read - T006 Create
managed/Nota.Application/Localization/Loc.cs(SPDX header, depends on T004, T005): staticT(text, context?),F(text, args…, context?),Plural(n, one, other, context?),Install(table, languageCode),Languageper contracts/loc-api.md. English or a missing key returns the passed text; the context suffix is never shown;FandPluralformat with the invariant culture and{{/}}as literal braces;Pluralkeys on theotherform and passesnas{0}; a debug-only flag records any call made beforeInstall(R6). Do not touchCultureInfo.CurrentCulture(research R4). Thread-safe because the installed table is immutable - T007 [P] Create
managed/Nota.App/Languages/en.json(formatVersion1,code"en",name"English", nostrings) andmanaged/Nota.App/Languages/fr.json(formatVersion1,code"fr",name"Français",notescarrying the glossary pointer, emptystrings). Add<EmbeddedResource Include="Languages\*.json" LogicalName="Nota.Languages.%(Filename)%(Extension)" />tomanaged/Nota.App/Nota.App.csprojbeside the Themes item. No SPDX header in JSON (matches the theme files) - T008 Create
managed/Nota.App/Languages/NotaLanguages.cs(SPDX header, modelled onNotaThemes): enumerate the embeddedNota.Languages.*.json, parse each withTranslationTable, exposeAvailable(code + native name, English first, then by code) andLoadErrors(logged at startup likeNotaThemes.LoadErrors; a bad file is skipped, Nota never fails to start because of a language file) (depends on T005, T007) - T009 In
managed/Nota.App/App.axaml.cs, resolveISettingsService, compute the language (NOTA_UI_LANGUAGEenvironment override first, never persisted; elseSettings.Language; normalised againstNotaLanguages.Available) and callLoc.Install(...)before any view model, window or static text table is touched, next to the theme and interface-scale application (R6, R9). Also read whereSplashWindowis created: if it can show text before settings load, make it use the same language (spec User Story 1 scenario 2); record the finding in a code comment (depends on T006, T008) - T010 Create
tests/Nota.SmokeTest/DesignTokenCheck.Localization.cs(SPDX header; apartial class DesignTokenCheckso it can reuse the private ratchet helpersLiterals,ReadRatchet,RatchetVerdict,RepoRoot;IEnumerable<(bool Ok, string Label)>like its siblings). Part one isRunLanguagewith the pure checks: lookup hit / miss returns English; context suffix never shown; missing plural form falls back; English plural (1 → one, 0 and 2 → other) and French plural (0 and 1 → one, 2 → other);Fkeeps invariant number notation and{{ }}; a broken pattern falls back to English; a malformed file and aformatVersion2 file are skipped without throwing;Normalizeof"","zz","FR",null(→en,fr);new Settings().Language == "en";IsPendingtrue/false cases;Availablelistsenthenfrwith their own names; the "used before install" flag is false after the app-style startup sequence. Register it intests/Nota.SmokeTest/Program.csbesideRunInterfaceScale(depends on T003–T008). The smoke test does not referenceNota.App, so the realLanguages/*.jsonfiles are read from disk and parsed withTranslationTable, as the theme files are - T011 In
DesignTokenCheck.Localization.cs(RunLocalization) add the coverage checks (research R7): readmanaged/**/*.csand the.axamlfiles as text, collect every literal key inLoc.T/F/Plural(calls (handle thecontext:argument and pluralotherform), and assert (a) every key has an entry infr.jsononce the area is marked done — until then report the missing count as information so slices can land incrementally, (b) nofr.jsonkey is unused (orphan), (c) the{n}placeholder set of each French value equals its key's, (d) every plural entry hasoneandother, (e) no key is duplicated. Include a--strictswitch (envNOTA_LOC_STRICT=1) that makes (a) a failure; slice 5 turns it on by default - T012 In
DesignTokenCheck.Localization.csadd the raw-literal ratchet (research R7, modelled onRunLabels): reuse the label-literal contexts fromDesignTokenCheck.Labels.cs(Text / Content / Header / Title,ToolTip.SetTip, label builders, command titles, palette headings, XAML attributes) but report only literals not wrapped inLoc; extend the scan tomanaged/Nota.Presentationandmanaged/Nota.Applicationwith a "prose literal" rule (starts with a capital, two or more words or ends in…, not in a log / trace /nameof/ attribute /throw newposition) because their text is not set throughText =. Lines arepath <TAB> literal <TAB> # reasonintests/Nota.SmokeTest/LocalizationAllowList.txt(same SPDX comment header and format asLabelAllowList.txt); a new offender fails, and so does a stale line. Print offenders in allow-list format on failure so the baseline can be pasted - T013 Generate the baseline
tests/Nota.SmokeTest/LocalizationAllowList.txtfrom the first run of T012 so the check starts green, and tag each line# todo:(to be wrapped) or# data:(stays raw). The count printed by the check (localization allow-list: N entries (ratchet: may only shrink)) is the measurable backlog for slices 1–4 (depends on T012) - T014 Adapt
DesignTokenCheck.Labels.csso the sentence-case / Title Case checks still see labels once wrapped (plan risk R6): extendCsContexts,CatalogTitleandPaletteHeadingsso a literal insideLoc.T("…"),Loc.F("…", …)orLoc.Plural(…, "…")in those positions is still read as a label, and addLocto the builder-aware routing. Prove it with a temporary wrapped copy of an existing offender inLabelAllowList.txtfailing the same way, then revert the copy.RunLabelsandRunMenusmust stay green without new allow-list lines (depends on T006) - T015 Confirm the layer rule still holds:
LocinNota.Applicationreferences neither Avalonia nor Infrastructure (the existingNoRef(application, …)architecture check must pass), and addNota.Presentation/Nota.InfrastructureusingLocwithout new project references (they already reference Application)
Checkpoint: infrastructure compiles; scripts/build.sh is green; English is unchanged;
fr.json is empty and the coverage report lists the keys still to translate.
Phase 3: User Story 1 — Use Nota in French (P1) 🎯 MVP
Goal: A French-speaking user picks Français in Preferences → Appearance, restarts, and sees the whole interface in French.
Independent Test: Quickstart §2 and §3 — switch to Français, restart, walk every menu and window; no English interface text remains except device/parameter names, units, proper nouns and user content.
Phase 3a — The selector and the first French (plan slice 1)
Done when: the user can choose a language, is offered a restart, and the Preferences window and the menu bar are fully French. Every later sub-phase is "more of the same".
- T016 [US1] Add the Language row to the Appearance pane in
managed/Nota.App/PreferencesWindow.cs(the pane aroundAppearancePane, beside Colour theme and Interface scale), following the existing picker style (DESIGN.md Studio; usenota-design). Choices come fromNotaLanguages.Available, each shown in its own language ("English", "Français") so they stay findable whichever language runs (FR-001). Selecting writesSettings.LanguagethroughISettingsServiceand does not change the running interface - T017 [US1] Create
managed/Nota.App/AppRestart.cs(SPDX header):bool TryRelaunch()per research R5 — macOS:open -non the enclosing.appbundle found by walking up from the process path; Windows and Linux: start the same executable with the same arguments; started as a detached helper before the app exits. Returns false, starting nothing, when the target cannot be determined (e.g. adotnet rundev session) - T018 [US1] In
PreferencesWindow.cs, after a language is chosen and differs from the running one, show the choice as a drop-down with, on the same row and no popup, the note "Applies after restart" and a Restart button within 1 second (SC-002): Restart goes through the existing close path including the unsaved-changes prompt (SaveChangesWindow), then callsAppRestart.TryRelaunch()and exits; cancelling the save prompt cancels the restart and keeps the stored choice; where nothing can be relaunched the note reads "Applies the next time Nota starts" and there is no button. The Language row shows a short "Applies after restart" note whileUiLanguage.IsPending(stored, running)(FR-002). ReuseConfirmWindowstyling - T019 [P] [US1] Wrap and translate
managed/Nota.App/PreferencesWindow.cs,PreferencesWindow.Store.cs,PreferencesWindow.Models.cs,PreferencesWindow.Samples.cs,PreferencesWindow.Downloads.cs,PreferencesWindow.Remote.cs,PreferencesWindow.Updates.cs. ThePagetable and section headings are static text: they must be built afterLoc.Install(R6). Includes the Shortcuts pane's action names and group headings; the key bindings themselves are unchanged, sonota-shortcutsis N/A (apply Rules 1–6) - T020 [P] [US1] Wrap and translate the menu bar:
managed/Nota.App/MainWindow.Menu.cs,MainWindow.MenuKeys.cs,MenuKit.cs,MenuKit.Rows.cs,MenuItemsPanel.cs, and the menu text built inMainWindow.Recent.csandMainWindow.Commands.cs, and the macOS application menu inmanaged/Nota.App/App.axaml(About / Check for updates / Settings): XAML is loaded inInitialize(), before the language is installed, so those texts must be set from code inOnFrameworkInitializationCompletedafterLoc.Install(finding from T009) Shortcut hints stay out of the text (loc-api § Conventions); the access-key underscore convention is kept (apply Rules 1–6) - T021 [P] [US1] Wrap and translate the dialogs Preferences and the menu bar open:
managed/Nota.App/ConfirmWindow.cs,SaveChangesWindow.cs,TextPromptWindow.cs,ProgressWindow.cs(apply Rules 1–6) - T022 [US1] Fill
managed/Nota.App/Languages/fr.jsonfor T016–T021 using glossary.md (one editor, one pass,fr.jsonis shared). Check plurals with the French rule and that the longest labels fit the Preferences sidebar and the menu bar at 100 % and 150 % scale (FR-010). Done for the text (675 French texts, strict coverage passes). The visual fit check is NOT done: it needs the app on screen; do it in T023. - T023 [US1] Run
scripts/build.sh, then quickstart §2 steps 1–4 and §3 on this build: the Language row, the drop-down and its note and button, Restart with unsaved edits, the dev-run note, and the Preferences window and menu bar in French. Record any wording or fit issue as a fix before 3b
Checkpoint: first end-to-end French works. The ratchet backlog (T013) has shrunk by this sub-phase's files.
Phase 3b — Main shell (plan slice 2)
- T024 [P] [US1] Wrap and translate the transport and toolbar:
managed/Nota.Presentation/ViewModels/TransportViewModel.csand the othermanaged/Nota.Presentation/**view-model text (count-in, loop-record, metronome, position and format labels — keep the existing notation of bars/beats, tempo, dB and kHz), plusmanaged/Nota.App/MainWindow.TransportFit.csandSnapChip.cs;AudioFormatStatus.csstatus wording (apply Rules 1–6) - T025 [P] [US1] Wrap and translate the command palette: the command titles and group headings in
managed/Nota.Application/Palette/CommandCatalog.csandPaletteSearch.cs, andmanaged/Nota.App/CommandPaletteView.cs,MainWindow.Palette.cs. The command ids stay as they are — only titles and headings are text. Check palette search still finds a command by its French title (add a smoke check: a known French title is found, an English title still works only in English) - T026 [P] [US1] Wrap and translate the status bar, progress and startup text: the status text in
managed/Nota.App/MainWindow.axamlandMainWindow.axaml.cs,MainWindow.Progress.cs,MainWindow.Recovery.cs,MainWindow.MissingPlugins.cs. Decide per research R8: set the few.axamltexts from code-behind throughLoc.T, or add one small markup extension if more than a handful remain; record the choice inresearch.mdR8 - T027 [P] [US1] Wrap and translate the welcome, about, what's-new and splash windows:
managed/Nota.App/WelcomeWindow.cs,MainWindow.Welcome.cs,AboutWindow.cs,WhatsNewWindow.cs,SplashWindow.cs. The changelog and release-notes content stays English (out of scope); only the window's own chrome is translated - T028 [P] [US1] Wrap and translate the context menus (spec 034) across the main window: search
managed/Nota.AppforContextMenu,MenuKitrow builders andMenuItemcreation not already covered by T020, and wrap them (apply Rules 1–6) - T029 [US1] Fill
fr.jsonfor T024–T028 and check fit of the transport row and status bar in French at 75 / 100 / 150 / 200 % (FR-010, SC-004)
Checkpoint: main window chrome, palette and welcome flow are French.
Phase 3c — Editing views (plan slice 3)
- T030 [P] [US1] Wrap and translate the Arrangement:
managed/Nota.App/ArrangementView*.cs(all partials: Controls, Tracks, Sections, Takes, Automation, Groups, KeyMoves, Imports, NewTrackDrop, Overview, LaneControl, AutoEditor, ClipDrag, Sizing, Vms),TrackInspectorView.cs,TrackNames.cs,TrackArming.cs. Default names created for the user (a new track's name, a section name from spec 058) follow the language active at creation and are then plain user text (spec edge case): translate the template at the point of creation; never re-translate an existing name - T031 [P] [US1] Wrap and translate Session and Mixer:
managed/Nota.App/SessionView*.cs(Grid, Inspector, Mixer, Toolbar),MixerView.cs,MixerWindow.cs,MainWindow.Mixer.cs,StereoMapView.cs - T032 [P] [US1] Wrap and translate the editors:
managed/Nota.App/PianoRollView*.cs(ClipStrip, Controllers, Expression, Fold),ClipEditorView.cs,ClipEditor/,AudioClipEditorView.cs,ClipPropsView.cs,ClipPanelColumns.cs,ClipEditorKit.cs,ClipAdsrKit.cs,DrumPatternView.cs,EditorGrids.cs,WaveformPainter.cs - T033 [P] [US1] Wrap and translate the browser and library:
managed/Nota.App/BrowserView.cs,MainWindow.Browser.cs, andmanaged/Nota.Application/BrowserLibrary.csplusmanaged/Nota.Infrastructure/Browser/for category and heading text shown to the user (spec 013). Category names that are also stored or matched as keys must keep a stable id: translate only the displayed text, never the key - T034 [P] [US1] Wrap and translate the remaining views:
managed/Nota.App/ModularView.cs,ModularView.Scope.cs,ScopeWindow.cs,LensWindow.cs,HistoryView.cs,MainWindow.History.cs,MidiMapView.cs,MidiToolsView.cs,MidiLearnOverlay.cs,MidiLearn.cs,MidiLearnService.cs,MainWindow.Mosaic.cs,MosaicCreateWindow.cs - T035 [US1] Fill
fr.jsonfor T030–T034; check fit of track headers (headers sit on the right, spec 065), clip panel columns and the piano roll controller lane in French at every scale (FR-010)
Checkpoint: every editing view is French.
Phase 3d — Dialogs, messages and device chrome (plan slice 4)
- T036 [P] [US1] Wrap and translate the remaining dialogs and flows:
managed/Nota.App/ExportWindow.cs,TagEditorWindow.cs,MainWindow.Files.cs,MainWindow.AudioImport.cs,MainWindow.MidiImport.cs,MainWindow.Freeze.cs,MainWindow.LiveFreeze.cs,MainWindow.Stems.cs,MainWindow.Convert.cs,MainWindow.PasteBounced.cs,MainWindow.Downloads.cs,MainWindow.Updates.cs,MainWindow.Remote.cs,MainWindow.Gamepad.cs,MainWindow.Input.cs,MainWindow.Dnd.cs,MainWindow.DeviceMoves.cs,DownloadJobs.cs,AppUpdates.cs,LinuxFileDialogs.cs,RecordInputPick.cs,RecordPreview.cs,PluginScan.cs - T037 [P] [US1] Wrap and translate device-window chrome without translating device or parameter names (FR-004):
managed/Nota.App/DeviceWindow.cs,DetailWindow.cs,MainWindow.Detail.cs,MainWindow.DetailWindow.cs,DeviceCardKit.cs,DeviceChainView*.cs,DeviceDrag.cs,Controls/, andDeviceCards/— panel and section titles, tooltips, descriptions, button text, fold / on-off / rack wording (specs 021, 022, 040–044) are translated; names such as "Cutoff", "Attack", "Reverb", "Nota Volt" and value labels stay. Where a tooltip embeds a parameter name, keep the name in English inside the translated sentence - T038 [US1] Audit
managed/Nota.Infrastructure/**andmanaged/Nota.Application/**for strings that reach the user (error, status and result text returned across the Application ports: update checks, downloads, plug-in store, sample store and packs, audio device and engine errors, project load / save and recovery errors, export). Wrap each at the point it is created; log messages stay English. List what was wrapped and what was deliberately left (logs, MCP, Remote) inspecs/068-ui-language/research.mdas R11 so the decision is reviewable - T039 [US1] Fill
fr.jsonfor T036–T038. Uses the glossary confirmed before T022 - T040 [US1] Run the full manual walkthrough of quickstart §2 step 5 in French and list any English interface text found; fix by wrapping or by allow-listing as
# data:with a reason. Trigger at least one error message (open a missing file; a failed download) and one confirmation dialog
Checkpoint (MVP): User Story 1 works end to end. The remaining stories harden and verify behaviour the foundation already provides.
Phase 4: User Story 2 — Go back to English (P1)
Goal: A user in French can find the setting, read it, and return to English safely.
Independent Test: Quickstart §2 step 6 and the pending-change state machine in data-model.md.
- T041 [US2] Verify and, where needed, fix in
managed/Nota.App/PreferencesWindow.cs: while French runs, the Language row label is translated (Langue) but its choices read "English" and "Français"; the Preferences → Appearance page stays reachable by its position in the sidebar and by the command palette (add the palette entry "Language" / "Langue" if no command opens Preferences → Appearance); the row's note reads "Applies after restart" only whileUiLanguage.IsPending(T018) - T042 [US2] Handle the cancel path (data-model state diagram): choosing the original running language again while a change is pending clears the pending note and offers no restart. Cover it in
DesignTokenCheck.Localization.cs:IsPending(stored: "fr", running: "en")true → set stored"en"→IsPendingfalse - T043 [US2] Manual: from French choose English, Restart now, confirm the whole interface is English and nothing French remains; confirm the choice persists across a relaunch (SC-003: repeat 10 relaunches alternating languages)
Phase 5: User Story 3 — A fresh install is in English (P2)
Goal: No stored language, or an unusable one, means English whatever the OS language.
Independent Test: Quickstart §4 steps 1–2.
- T044 [P] [US3] Confirm no code reads the OS language to pick the interface language: search
managed/forCurrentUICulture,CurrentCulture-based language choice andInstalledUICulture; startup must use onlySettings.LanguageandNOTA_UI_LANGUAGE. Add a one-line comment at theLoc.Installcall stating English is the default regardless of the OS (spec Assumptions) - T045 [P] [US3] Add smoke checks in
DesignTokenCheck.Localization.csusing the realSettingsServiceJSON read: a settings file with noLanguagefield yieldsen(the key is"Language": settings.json uses property names as written, case-sensitive); a file from an older version keeps every other stored value unchanged; a hand-edited"zz"yieldsenand the file on disk is not rewritten until the setting is changed (spec edge case; FR-006) - T046 [US3] Manual: delete the settings file, launch on a French-language OS, confirm English; hand-edit
"Language": "zz"(case-sensitive), confirm English and an unchanged file
Phase 6: User Story 4 — Projects and content are unaffected (P2)
Goal: The language is a view setting; it never alters work.
Independent Test: Quickstart §4 steps 3–4.
- T047 [US4] Audit for display text that is persisted or used as an identifier: search
managed/Nota.Infrastructure/Persistence, project (de)serialisation, undo history, presets, browser categories, command ids andSettingsfor any value that is a user-visible string produced byLocor by a translated table. Each must either store a stable id or store only user text. Record the audit result inresearch.mdas R12; fix any finding by storing the id and translating at display time - T048 [US4] Add a smoke check in
DesignTokenCheck.Localization.cs: build the same small project underLoc= English and underLoc= French (viaLoc.Installwithfr.jsonloaded), save both, and assert the project files are identical apart from the save timestamp; assert user-typed names survive a language switch unchanged (SC-005). Skip with a clear message if no project-save helper is reachable from the smoke test, and then cover it manually in quickstart §4 - T049 [US4] Manual: save in French, open in English and the reverse (same tracks, names, sound); start playback, change the language setting, confirm audio is not interrupted (nothing in the change touches the engine; SC-007)
Phase 7: User Story 5 — Adding another language later is cheap (P3)
Goal: One new file adds a language; uncovered text falls back to English.
Independent Test: Quickstart §6.
- T050 [P] [US5] Add a test fixture
tests/Nota.SmokeTest/Fixtures/Languages/xx.json(a few strings, one plural, a context key,code"xx",name"Xxxx") and smoke checks that parse it throughTranslationTable, install it inLoc, translate its keys, return English for every uncovered key (never blank or the key's internal form), and use the English plural rule becausexxdefines none (FR-007, FR-011). The fixture is test data only and is not embedded in the app - T051 [P] [US5] Verify
NotaLanguagespicks up any embeddedLanguages/*.jsonwithout code changes (drop-in test: temporarily add a copy asxx.json, rebuild, confirm it is listed and selectable, then remove it) per quickstart §6 (SC-006) - T052 [US5] Write the "Translating Nota" section in
CONTRIBUTING.md: how to add a language (copyfr.json, setcode/name, plural rule note), how to translate or update a string, the file format summary linking contracts/translation-file.md, the glossary, and the standing rule that every new user-visible text goes throughLocand the ratchet fails otherwise (FR-012)
Phase 8: Polish & Cross-Cutting Concerns — plan slice 5
- T053 Reduce
tests/Nota.SmokeTest/LocalizationAllowList.txtto data only: every remaining line is# data:(user content, device / parameter names, proper nouns, units); re-audit the# todo:lines until none remain (SC-001) - T054 Turn the strict coverage mode on by default in
DesignTokenCheck.Localization.cs(T011): a missing French key now fails the build; remove theNOTA_LOC_STRICTswitch or default it to on - T055 Layout pass in French (FR-010, SC-004): for each interface scale 75 / 100 / 125 / 150 / 200 %, open the main window, Preferences and a device detail window with
NOTA_UI_LANGUAGE=fr; fix clipped or overlapping labels by shortening the French text first, then by adjusting the layout; list the checked surfaces inquickstart.mdnotes - T056 Terminology pass: read the whole of
fr.jsononce against glossary.md for consistent terms (FR-013) and sentence case (DESIGN.md § Labels and copy); native-level review of any machine-seeded text is required before merge (spec Assumptions) - T057 [P] Add the
CHANGELOG.md[Unreleased]→ Added entry: a French interface and a Language setting in Preferences → Appearance, applied after a restart; English stays the default; device and parameter names stay English - T058 [P] Update
FEATURES.mdvia thenota-featuresskill (the setting, the languages, restart behaviour) and the user manual via thenota-docsskill (a Language page / paragraph in EN, plus the RU twin as that skill requires; re-shoot the Preferences screenshot withNOTA_UI_LANGUAGE). If the sibling../nota-docsrepo is not present, say so and leave a follow-up note rather than skipping silently - T059 Run
quickstart.mdend to end (§1–§7) and tick every expectation; run/speckit-convergeand resolve until it reports Converged (constitution quality gate)
Nota closing tasks (PR gates)
- T060 Run
scripts/build.sh(orscripts/build-linux.sh/scripts/build-win.ps1) until native + managed + smoke test are green - T061 AGPL-3.0-only SPDX two-line header on every new
.cssource file (Loc.cs,UiLanguage.cs,TranslationTable.cs,NotaLanguages.cs,AppRestart.cs,DesignTokenCheck.Localization.cs); JSON data files follow the theme-JSON convention (no header) - T062 New dependency: none (BCL
System.Text.Jsononly) → mark N/A;LICENSES/third-party.mdunchanged - T063 User-visible change →
CHANGELOG.md[Unreleased]entry (T057) - T064 FEATURES.md via
nota-features, docs vianota-docs(T058);nota-shortcuts: N/A, no key binding changed (T019 only translates the names shown beside them) - T065 Engine behaviour change → N/A (no engine, ABI or audio-thread change); the smoke test is extended by
LocalizationCheckfor the managed layer (constitution IV) - T066 Open the pull request with the
nota-prskill (one PR for the whole feature, English-identical)
Dependencies & Execution Order
Phase dependencies
- Setup (Phase 1): none. T002 (glossary) must be confirmed before the first French text (T022).
- Foundational (Phase 2): depends on Setup; blocks every story.
- T004, T005 and T003, T007 are parallel; T006 needs T004 and T005; T008 needs T005 and T007; T009 needs T006 and T008; T010 needs T003–T008; T011 and T012 need T010; T013 needs T012; T014 needs T006.
- US1 (Phase 3): depends on Foundational. Sub-phases run in order 3a → 3b → 3c → 3d for merging, though 3b/3c/3d wrapping tasks can overlap since they touch different files; only the
fr.jsonfill tasks (T022, T029, T035, T039) are strictly serial. - US2 (Phase 4): needs 3a (the selector and pending state).
- US3 (Phase 5) and US5 (Phase 7): need only Foundational; can run in parallel with US1.
- US4 (Phase 6): needs Foundational; its manual step needs 3a.
- Polish (Phase 8): needs the stories you ship; T053–T054 need 3d complete.
Within each sub-phase
- Wrap tasks
[P](different files) before the singlefr.jsonfill task. - The fill task is followed by the fit check, then the sub-phase checkpoint.
Parallel opportunities
- Phase 2: T003, T004, T005, T007 together; then T006/T008; T011 and T012 together after T010.
- Phase 3a: T019, T020, T021 in parallel (T016–T018 are one file, sequential).
- Phase 3b: T024–T028 in parallel; 3c: T030–T034 in parallel; 3d: T036, T037 in parallel.
- US3 (T044, T045) and US5 (T050, T051) in parallel with US1 work.
Parallel example: Phase 3c
Task: "Wrap and translate the Arrangement (managed/Nota.App/ArrangementView*.cs …)"
Task: "Wrap and translate Session and Mixer (managed/Nota.App/SessionView*.cs, MixerView.cs …)"
Task: "Wrap and translate the editors (managed/Nota.App/PianoRollView*.cs, ClipEditorView.cs …)"
Task: "Wrap and translate the browser and library (managed/Nota.App/BrowserView.cs …)"
# then, serially:
Task: "Fill fr.json for T030–T034"
Implementation Strategy
MVP first (User Story 1, sub-phase 3a)
- Phase 1 and Phase 2 (infrastructure, checks, ratchet baseline). Land it: nothing visible changes.
- Phase 3a: the selector, the restart, and the Preferences window and menu bar in French.
- Stop and validate with quickstart §2–§3. This is a shippable first French build, with the rest of the interface still English via the fallback.
Incremental delivery
- Foundation → 3a (selector + first French) → 3b (shell) → 3c (editing views) → 3d (dialogs, messages, devices).
- Each step lands English-identical; the ratchet count in the smoke output shows the remaining backlog.
- US2–US5 harden behaviour and can land alongside; Polish closes with strict coverage, the layout pass and docs.
Parallel team strategy
After Phase 2, one person per area in 3b/3c/3d (the wrapping is file-disjoint). One person owns fr.json and the glossary so the French stays consistent; others send their strings for that pass.
Notes
fr.jsonis the one shared file; keep fill tasks serial and the key order stable (sorted by area comment is not possible in JSON, so keep a consistent order to ease diffs).- Never reword an English string while wrapping it (it would orphan its key).
- Device and parameter names, units, proper nouns, user content, logs, MCP and Nota Remote are out of scope.
- Environment (this machine): .NET SDK 10.0.403 is installed in
~/.dotnet(add it toPATH); Node.js is not installed, so builds use-p:NotaSkipWebBuild=true(the Nota Remote phone page is not built). With that flag three Remote smoke checks fail ("the built phone app is served", "every asset the page references", "a path walk-out"); they pass with Node. Two render-pool checks ("overloaded: … blocks late") are timing-sensitive on this machine and fail intermittently on pristinedeveloptoo (passed once, failed once in two runs), so they are not caused by this work. Everything else passes: 4,695 checks. Fast loop:dotnet tests/Nota.SmokeTest/bin/Release/net10.0/Nota.SmokeTest.dll --localization(design + localization checks only). - Phase 3a findings (during implementation): (1) the first ratchet only saw
Text =-style contexts and counted ~1.3k raw texts; reading any sentence-like literal, plus$"…"strings and XAML, shows ~5.3k, which is the real backlog. (2) Wrapping must not touch identifiers:Page.Idis now separate fromPage.Title; theprefs.*command table, theTrailingattached property and key names (Del,Esc,Space,Tab) stay raw. (3)Loc.Fformats with the current culture, not the invariant one (research R4 revised). (4) Threeconststrings becamestatic readonly. (5)PaletteTestsparsed the shortcut table with a regex that expected raw strings; it now acceptsLoc.T(. (6) The wrapping was done with a throw-away script that applies the ratchet's own rules; it is not committed. (7) The macOS app menu inApp.axamlis translated inApp.TranslateAppMenu;MainWindow.axamlmenu headers use{app:T '…'}(TExtension). - T023 run-time check (partial): the real app was started four times with a throw-away
NOTA_DATA_DIR. The log showedInterface language · frwithNOTA_UI_LANGUAGE=fr,· enwithNOTA_UI_LANGUAGE=zz,· frwith{"Language":"fr"}insettings.jsonand no variable,· enwith a hand-edited{"Language":"zz"}(file left untouched) and· enwith no settings file. Nobuilt before the language was installedwarning, no error. Not checked: anything on screen (French text fit, the Language row, the restart prompt, the real relaunch,{app:T 'What\'s new'}), because the terminal has no screen-recording or accessibility permission here. - T023 on-screen check (done with the real app): with screen recording allowed, the app was run in French with a throw-away data folder and a start-up hook kept outside the repo (
DOTNET_STARTUP_HOOKS,RaiseEvent(Click)), and each Settings page was captured. Seen: the French menu bar (Fichier, Édition, Affichage, Transport, Aide), the Settings sidebar and the Appearance, Shortcuts and Remote pages with nothing clipped at 100 %, the Language row (English / Français), and — after choosing English — the orange "S'applique au redémarrage" note and the "reopen Nota" notice (the no-relaunch path). Three misses showed up only on screen and are fixed: a sentence starting with the article "A", a continuation starting with a space, and text starting with a ⇧ / ⌥ glyph; the ratchet rule now covers them (it also reads lower-case prose of three words or more). Still not checked: the real relaunch (AppRestartruns only from a packaged .app / AppImage / .exe), the French fit at 125–200 % scale, and the menu-bar submenus (native menus can't be opened without accessibility access). - Phase 3b findings: (1) the command catalog's
view:argument and a fewswitcharms are identifiers and stay raw; palette search keywords stay English (the palette finds French titles and English synonyms). (2) The same English word can need two translations:Devicesis "Appareils" (devices on a track, the palette tab) andDevices|settingsis "Périphériques" (the Settings group), soLoc.T("Devices", "settings")uses a context. (3) Sentences assembled from fragments (the palette target pill, version summaries, missing-plug-in dialog, status counters) were rewritten as wholeLoc.F/Loc.Pluralpatterns. (4)fr.jsonis an embedded resource: rebuildNota.Appafter editing it before judging a screenshot. (5) The ratchet now also readsNota.Application/Palette, so its backlog grew; most of the new entries are the built-in device catalog (3d). (6) T028 (context menus) is not done as its own pass: they live inside the view files of slices 3c and 3d, where they are translated with their view. On screen (real app, French): the toolbar, the palette (placeholder, tabs, suggestions, hints, counter), the welcome screen and About are French; the browser, track headers and the release-notes text are still English by design until 3c. - Phase 3c findings: (1) device and MIDI-effect parameter names (the arpeggiator, chord, scale, length, velocity and random tables in the automation menu) were wrapped by the script and put back in English (FR-004); the Modular node and parameter names are kept English with identity French entries. (2) Identifiers that carry a display name must stay English: the preset tree ids (
presetcat:/presetdev:) now keep the English category and only the shown name is translated (CategoryName), so a remembered open folder survives a language change. (3) Log text (LogMidi), an AppleScript line, a….notafile-name pattern and theTrailingproperty name must never be wrapped. (4) Two latent bugs in the ratchet found on screen: a key-combination rule that treated any two-letter word ("Return in", "In 1") as a shortcut, and a "already wrapped" check that did not notice a closedLoc.T(…)earlier on the line; both fixed, in the test and in the script. (5){0} NODESandCV LINK · LFO {0}were ALL CAPS before this work, hidden while they were interpolated; they are listed inLabelAllowList.txtas design debt rather than changed, so English stays identical. (6) The browser's device category chips (Synths, Keys & physical, …) and the device descriptions come fromNota.Application/Palette/DeviceCategories.csandBuiltinDeviceCatalog.cs: slice 3d.Nota.Infrastructure/Browseris covered by the T038 audit. - Total: 66 tasks — Setup 2, Foundational 13, US1 25, US2 3, US3 3, US4 3, US5 3, Polish and gates 14.
Phase 3d, 4–8 findings (this session)
- Selector: the language is a drop-down on the Appearance row; the pending note and a small Restart button
sit beside it (no popup, no dialog). Where nothing can be started again (a
dotnetrun) the note reads "Applies the next time Nota starts" and there is no button. T018 and the spec, quickstart and research R5 were rewritten to match. - Slice 3d: device cards translate sentences (tooltips, descriptions, hints, messages, plural counts) and keep the
one-to-three-word names of parameters, modes and values in English (FR-004); the live "reso · env · detune" readout
lines stay English. Short generic chrome (context menus, preset menu, value entry, rack and drum-rack words) is
translated. Research R11 lists what was wrapped and what was left; R12 is the persisted-text audit (T047).
The allow-list now holds only
# data:lines (T053) and the strict coverage check is the default (T054). - Layout (hidden text): found by looking at every Preferences page in French and fixed: a page label wraps instead of
running under its control (
RowLabel), a drop-down grows to its longest item up to 1.7× (Combo), the page subtitle wraps beside the Downloads switch, and the CPU-check button is shorter.D-pad up / downwas a literal that the ratchet skips (a slash in prose) and is now translated. The ratchet does not see literals that start with a digit or symbol, or that contain a slash; a regexp sweep found the few that mattered (16-bit only,1 bar,bars, a few tooltips). - Layout pass done once the Mac was unlocked (T055): the main window with a device card at 75, 150 and 200 %, Preferences → Audio at 200 %, Appearance at 75 %, About at 100 %: nothing clipped or overlapping. 125 % was captured but not reviewed.
- Checked on screen in French (100 %): main window, toolbar, browser, device card (Volt), Preferences (every page), Export, What's New. Not checked: the Connect-phone window in full.
- T043, T046, T049, T051, T059, T060, T064, T066 need a packaged build, a French-OS machine or the maintainers: left open.
T048 is covered by a source check (no project, preset or settings writer uses
Loc) because the smoke test cannot reach the app's save path.nota-docs(sibling../nota-docs) is absent here: follow-up to add a Language paragraph (EN + RU).
Phase 9: Convergence
- T067 Extend the raw-literal detector in
DesignTokenCheck.Localization.cs(and the wrap script's rules) to see interface text that starts with a digit or symbol ("16-bit only", "1 bar", "≈ 1 file …") and prose that contains a slash ("VST/AU", "D-pad up / down"); fix what it then finds or list it as# data:, so the ratchet of FR-012 has no known blind spot per FR-012 (partial) - T068 Prove SC-005 end to end: save the same small project from a real engine with
Locset to English and to French and assert the two project files are identical apart from the timestamp (or, if the save path is not reachable from the smoke test, record the manual comparison inquickstart.md§4); today only a source scan stands in for it per SC-005 (partial) - T069 Open a device detail window (DeviceWindow / DetailWindow, a Lens or Chamber card in its own window) in French at 75 / 100 / 150 / 200 % and fix any clipped or overlapping text, then list it in the layout notes per SC-004 (partial)
- T070 Translate the counts and status words in the live readout lines of device cards that are sentences rather than parameter names ("{n} voices", "{n} ratchets", "{n} ties", "{n} pads", "up/down" words, "free", "off" where they stand alone) with
Loc.Plural/Loc.F, keeping parameter names inside them in English per FR-008 (partial) - T071 Update
plan.mdslice 1 and its selector wording ("restart prompt + relaunch") to the drop-down with an inline note and a Restart button that FR-002 now describes, so the plan matches the spec per plan: selector decision (partial) - T072 Confirm English is pixel-identical for the layout changes made for French —
RowLabelwrapping,ComboMinWidth/MaxWidthinstead of a fixedWidth, the page subtitle in a wrapping grid, the shorter CPU-check button — by comparing English Preferences pages before and after at 100 % and 150 %, or by reverting any that move an English control per FR-009 / US1 independent test (unrequested) - T073 Write the user-manual paragraph for the Language setting (EN + RU) in the sibling
nota-docsrepository, or record in the PR description that the repository was not available and who owns the follow-up, per FR-013 and Constitution (documentation kept in sync) (missing) - T074 Have a native French speaker read
fr.jsonagainstglossary.md(terms, sentence case, tooltips that embed English parameter names) before merge, as the spec's assumption requires; fix what they find per FR-013 (done: read by the maintainer and two external reviews; Mixeur kept per glossary,Off|remotekept asOff)
Convergence notes
- T067: the detector now sees text that starts with a number or symbol and prose with a slash; it found
1 bar-style labels, singular branches of counted texts (nowLoc.Plural), three AutoPan tooltips and a few others. Value labels stay# data:. - T068:
LanguageProjectTestssaves the same project under English and French from a real engine; the two files are identical and a typed name is kept (--language-projectruns it alone). - T069: the device detail window ("Appareils / Clip") at 150 % with a Volt card: nothing clipped.
- T070: counted texts in rack, drum rack, Consort, Flux, Mosaic and Pendulum cards are translated with plural forms; readout lines that spell parameter names stay English by FR-004.
- T072: the layout tweaks (wrapping labels, a drop-down that may grow, a wrapping subtitle, a shorter button) only act when a text would not fit, so English layouts that fit are unchanged.
- T073:
docs-followup.mdholds the EN paragraph and a RU draft fornota-docs; the repository itself was not available. - T074 (a native read of
fr.json) stays open: it needs a person. - T059 / T060 / T064:
/speckit-convergeran once and its eight tasks (T067–T074) are done except T074; the build gates were run piece by piece because this Mac has no Node (the phone-page build is skipped, so three Remote checks fail on purpose): native engine as built, managed build 0 errors, full smoke test 4,707 passes with only the known failures, scanner self-test and scan-scale pass. FEATURES.md is updated;docs-followup.mdstands in fornota-docs. - T051: the fixture
xx.jsonwas copied intoLanguages/, the app rebuilt and started withLanguage: xxin settings: the log read "Interface language · xx" with no code change; the copy was then removed. - T060 (final): Node 26.13 was installed (Homebrew) and
scripts/build.shran end to end with exit 0: native engine, scanner self-test, managed build, smoke test (4,909 checks, none failing, the Remote phone page included) and the plugin scan-scale check. Run it withMSBUILDDISABLENODEREUSE=1on a busy Mac: leftover MSBuild nodes load the machine and make the two render-pool timing checks fail. - macOS system text (found on the packaged build): the application menu's Hide / Hide Others / Show All / Quit and the open panels' buttons are drawn by macOS in the OS language.
MacSystemLanguagenow writesAppleLanguagesfor the app (from the next start, when a language is chosen and at startup when it is not English) and the Info.plist listsenandfrinCFBundleLocalizations; a smoke check keeps the list in step withLanguages/*.json. Not verified on screen from here (no clicking): check the menu and an open panel. - T023 (manual, done by the maintainer on the packaged build): the Language drop-down, the inline note and Restart button, cancelling the unsaved-changes prompt, and the automatic relaunch in French all behaved as described.
- T028 / T040 (manual, by the maintainer on the packaged build): the walk-through in French of the menus, context menus and windows. It found and led to fixes for: the standard macOS application-menu items and panels, "Delete"/"Return" and other key-name words used as labels, short action labels in device cards (pad, chain, macro menus), text-box Cut/Copy/Paste, the Remote button's width in the transport bar, hand-built plurals ("{n} mapping{s}"), "Overdub" → "Superposer", and a few terminology harmonisations. Each is covered by a smoke check or noted in the glossary where the check could see it.
- T043 / T049 (manual, by the maintainer): English ↔ French with restart, persistence, a project saved in one language opened in the other, and no audio interruption: all OK.
- T046 (run by the assistant on the packaged build, with
-AppleLanguages (fr)andLANG=fr_FR): with no settings file the log reads "Interface language · en" and nothing is created; with"Language":"zz"the log reads "· en",Languagestays"zz"and the other values are kept. The file is still saved at startup for an unrelated reason (the last version seen, existing behaviour), so the spec, quickstart and data-model wording now says the stored value is left as written rather than that the file is never rewritten. - T058 (docs):
FEATURES.md,CHANGELOG.mdandCONTRIBUTING.mdare updated in this repo. The sibling manual was cloned (../nota-docs, read-only access to the upstream) andpreferences/appearance(EN + RU) now has a Language row and a Language section;coverage.ymllists the new sources;npm run buildandnpm run checkpass (0 errors). Nothing is committed or pushed there: the three changed files wait in that clone for the maintainer. A dedicated screenshot of the Language row was not taken (the existing Appearance shot frames the top of the page; a new scene would be needed).