Localise the app chrome, with Russian beside English

[alpha5611331]

Closes #135.

What

The app chrome is translatable, and Russian ships beside English. The chrome language is its own setting, asked rather than inferred - the first step of the first-run wizard, and the first row on the configuration page.

CLAUDE.md recorded the opposite rule, and half of its reasoning still holds:

an English button on a Spanish interview is an inconvenience, an English transcript of Spanish speech is a wrong answer read out loud

That is why nothing here derives one language from the other. A Russian speaker interviewing in English wants an English transcript and a Russian app, and guessing in either direction gets that user wrong. The other half only argued for not guessing, and this does not guess.

Why a typed dictionary and not i18next

locales/en.ts is the source of truth and exports Translation = typeof en. Every other locale is an object literal assigned to that type, so a key Russian is missing, or spells differently, fails the build. i18next's documented behaviour for a missing key is to render the key itself - home.greeting on screen, in production, for the one user who would notice least. For two locales with no lazy loading and no namespacing, that runtime is the only thing being bought.

Strings that take a value are functions, not templates with placeholders. That is what makes Russian expressible at all:

// en
charactersLeft: (n: number) => `${n.toLocaleString()} characters left`,
// ru - 1 символ, 2 символа, 5 символов, and 11 символов again despite ending in 1
charactersLeft: (n) => `Осталось ${n.toLocaleString('ru-RU')} ${plural(n, 'символ', 'символа', 'символов')}`,

The compiler covers the other direction: noUnusedParameters is already on, so a locale that declares (email: string) and then writes a sentence without it does not compile. That replaced an earlier ${}-slot parity check in the test, which forbade exactly the legitimate case above.

No new dependency.

Where the setting lives

• Wizard step 1, ahead of even the profile. Every other step asks about an interview; this one asks whether the user can read the questions. Picking re-renders that step in the chosen language on the spot, so one English screen is the whole cost of discovery - and only endonyms are listed, since the reader may not speak the language the app is currently in.
• Configuration page, first row, separated by a rule from the interview settings - it is the only control there that is not about how an interview runs.
• uiLanguage is resolved on the way out of getConfig(), the same as the interview language and for a sharper reason: an unresolved code reaches a lookup in the locale table and comes back undefined, which is an app with no text in it.

useT() reads the config store directly, so there is no provider. The code is also cached in localStorage and read synchronously at module load, because the store is loaded from an effect in MainFrame - without it a Russian install opens in English for the first frames of every launch.

Main process

src/main/utils/ui-strings.ts, a table keyed by language - same shape as export-labels.ts and deliberately not that table. The report follows the interview language because it is handed to someone who was not there; this follows the chrome language because it is read by the person using the app. It covers the placeholder panel copy main seeds and the push notifications it raises as toasts from paths the renderer cannot see: a global hotkey pressed while the window is hidden, a session that expires, stealth refused at the IPC boundary.

appStateService.refreshPlaceholderLanguage() closes the gap that opens: the placeholder is written on launch and after a Clear, so a language changed between those two would leave English sample copy in the panels of a Russian app. A no-op once a real interview has written to the history - a re-seed there would throw the interview away.

Out of scope, deliberately

• The exported report keeps following the interview language through export-labels.ts.
• Model-written content - suggestions, mock questions, scoring - follows the interview language by design.
• Backend error text is passed through untranslated. The client cannot translate a string it did not write, and swapping a specific server message for a generic local one loses the only useful half of it. The locale's errors blocks are fallbacks, for a failure that arrived without a message.
• Two internal faults stay in English: 'Electron API not available' (a state a working build cannot reach) and 'Some services did not stop cleanly' (written to a store field no component reads - the toast beside it is translated).

Tests

test/ui-language.test.mjs, 29 checks, registered in test/run.mjs. It covers what the types cannot:

• an unknown stored code resolves to English rather than reaching the lookup;
• the two UiLanguage mirrors staying in step, the way language.test.mjs pins Language;
• a Russian string that is still its English original - which type-checks perfectly, ships, and is otherwise only caught by a Russian speaker reading the screen. The rule is Latin letters with no Cyrillic in the same string, skipping quoted property names ('mock-done' must not be translated) and stripping ${...}. The allowlist is a list rather than a rule, and each entry is a written-out claim: Markdown, Word, Pro, Junior, ru-RU, a domain;
• the same check over main's table, plus uiStrings() following the stored language and the placeholder re-seed in both directions.

test/mock-transcript-turns.test.mjs anchored on the literal 'No answer' in the panel source; it now anchors on t.panels.noAnswer. That the panel reaches for a label at all is the invariant worth pinning.

Verified

pnpm test:main (all checks pass), tsc -b, tsc -p tsconfig.electron.json, eslint . - all clean, which is the whole of what CI runs.

Two things worth a reviewer's opinion

1. Dashes. The Russian copy uses hyphens where Russian typography wants —, because this repository's writing rules forbid generating em-dashes and the English source uses hyphens in the same positions. It reads slightly flat to a native eye. Say the word and I will switch the Russian strings to — and note the exception in the writing rules.
2. Seniority and plan names stay Latin. Junior / Middle / Senior / Staff+ and Starter / Pro / Enterprise are untranslated on purpose - the first set is what Russian-language job ads use essentially without exception, the second are purchasable SKUs. Both are in the test's allowlist with that reasoning attached.

Review notes for the translation itself: the copy was written rather than machine-translated, matching the English register (direct, second-person formal, no more words than the English uses). Russian runs roughly 15% longer than English and these strings sit in a window whose minimum width is 840px, so the long ones were kept tight - the control-bar tooltips and the fixed-height mock status row are where that matters most.

---

Review loop

Four passes after the implementation. What they turned up, because most of it is the kind of thing a line-by-line check against the English does not see:

A gendered form. mock.session.ready said Я готов - the masculine participle, on the button a candidate presses to start answering. A woman using the app was being misgendered by the interface at the one moment it asks her to speak. Russian has no short genderless participle here, so the label now says what the button does rather than who is pressing it: Можно начинать.

Terminology drift across surfaces. One suggestion mode, five places that name it, and Russian had named it four different ways - Только подсказки on the configuration card, Краткие подсказки in the control-bar tooltip, Кратко on the status badge, Кратко / полными фразами in the hotkey sheet. English is Hint-only in all five. They agree now, with Кратко kept only for the status pill and a comment saying why. The rename also resolved a collision: languageGroup.suggestionsOnly means "only the suggestions switched" and was rendering as the mode's own name.

A whole untranslated component. TrialUserNotice is on screen for every trial user on /main and was still entirely in English after six passes, because its sentence is split across lines by two <span>s and a <br /> - no single line held anything that looked like a string. test/ui-text-routing.test.mjs is the guard: it matches text between two tags, which in a .tsx file is a JSX child or nothing, and it fails on exactly that shape. Verified by putting the English back and watching it fail.

Three native save dialogs. showSaveDialog's title is the OS window title and the filter name is the file-type dropdown, and all three were English literals. Same distinction as export-labels.ts one layer up: the document inside follows the interview language, the window asking where to put it follows the chrome language.

One real overflow. ОСТАНОВКА is nine characters of uppercase bold Cyrillic and does not fit RunningIndicator's 96px badge. It wrapped rather than clipped, which makes the badge taller - and in stealth mode that badge is the only thing on screen. Widened to w-28, and test/ui-language.test.mjs now pins the two genuinely fixed-width slots with the budget written down and the measurement printed ("Остановка", 9/10).

Grammar and government, about a dozen: отвечает для этой роли and пишутся вашим опытом are the wrong case for their verb, нет кнопки, по которой можно нажать wants на которую, ответы за ним renders "the answers behind it" spatially in six save-history entries, тренировка против ИИ-интервьюера reads adversarial for what is practice with an interviewer, and two app-name sentences were missing в. charactersLeft said Осталось N символов, which is right for every N except 1 - Russian wants Остался 1 символ, and the verb agrees with the numeral too, which a plural helper picking only the noun cannot reach. Rephrased to Ещё N символов, which has no verb to agree.

Two code-quality fixes while in there. save-history-dialog read the partial mock copy table by casting reason into a narrower key union - asserting something false and then relying on the ?? to catch it; it reads through a Partial<Record<...>> view now. And useUiLanguageCode keyed on the stored value being truthy, which read a config carrying an unknown language as "not loaded yet" and sat on the localStorage cache instead of resolving to English.

Not verified

The Russian UI has not been looked at running. Everything above is static: types, lint, the 818-check suite, the production bundle, and reading the copy as a Russian speaker. Width and wrapping were reasoned about and the two unforgiving slots are now pinned by test, but a pass with the app open against a backend is the one check I could not do here - say the word and I will run it.

The NSIS installer is still installerLanguages: ['en_US']. Out of scope on purpose: it is not app chrome, and adding ru_RU wants a real installer run to verify.

Sign-out keeps the chrome language, deliberately: it lives in the config store rather than on the account, like the interview language, because it is a property of the person at the keyboard. The next account to sign in gets the wizard, whose first step asks again.

Pass 5: what /code-review high found

It cleared the plumbing - the resolver, the migration, the paint-time cache, the t-in-deps decisions and the placeholder re-seed guard all held up under it. What it found was five more English strings, and the common cause is worth stating because it was a reasoning error rather than an oversight:

The pass drew the line at "backend error text is passed through untranslated", which is right, and then applied it to strings main itself wrote - which is the opposite of right, and is what ui-strings.ts exists for.

• auth.service.ts was the worst of it. useAuth was translated as result?.error || t.auth.errors.*, but on these paths result.error is always set, so the new fallbacks were unreachable and "Invalid email or password" - the most frequently read error in the app - stayed English. Same shape in account.service.ts, which surfaces on the Account page and in the wizard.
• suggestion-error.ts writes onto suggestion.error, rendered verbatim on the card the candidate is reading: a rate-limited or stalled suggestion put an English sentence mid-interview into a Russian UI.
• mock-interview.service.ts writes onto the session's error, which /mock-interview deliberately surfaces - including the "check the microphone" explanation a candidate is owed for a session that skipped its way through questions they were already billed for. One of its lines was the same sentence as t.assistant.mockRunning, so one route into that refusal was Russian and the other English.
• proceedLabel="Continue" on /main's startup permission gate: translated title, rows and Cancel beside an English primary button.
• A screen-capture timeout thrown into startAssistant, rendered in English by the same toast whose generic fallback was already translated.

test/ui-text-routing.test.mjs grew the check that would have caught the fourth: copy-bearing attributes must be expressions, not string literals - a rule about the shape rather than the words, so a one-word literal too short for any prose heuristic still fails. Its \b was also written inside a template literal, where it is a backspace character rather than a word boundary, so the attribute check passed vacuously until that was fixed. Verified by putting proceedLabel="Continue" back.

The two decorative logos lost their alt="Logo" on the way past - they sit beside the app's name in text, so an empty alt is correct, and it was the last English word in the accessibility tree.

Final state: 821 passing checks, both typecheck configs, eslint, and the production bundle.

Passes 6-7: the rest of main, and running the locales

Pass 6 found 22 more strings of the same class the code review named, because the previous sweep had only re-scanned the renderer. All of them are strings main itself wrote reaching the screen through a { success: false, error } return or a suggestion's error field:

• payment.service.ts had the whole set - twelve sites across six methods, every one the message usePayment's result?.error || t.payment.errors.* can never fall back past.
• account.service.ts had four more at the || sites, beside the catch blocks already fixed.
• The three suggestion services each wrote 'The model returned an empty response.' onto a card rendered verbatim mid-interview, and suggestion-action wrote its own 'The response timed out...' beside the identical string already sitting unused in the table.
• api/client.ts was the one with reach. On a timeout it sets response.error.message to its own 'The request timed out' - so that English string won over every translated fallback behind it, in auth, account and payment alike, for the most common failure the app has.

A message thrown by the runtime (fetch failed) is still passed through: we did not write it, which is the line already drawn for backend text. src/main now scans clean - no client-authored user-facing English outside export-labels.ts, which follows the interview language by design, and diagnostics that cannot reach a screen ('Electron API not available', the websocket generation-guard throws, 'Synthesis returned no audio' - each verified as caught locally or unreachable).

Pass 7 closed the one axis with no coverage at all: until now, no test had ever executed a locale. plural, three toLocaleString calls and the two duration builders all run real logic, reached only by the bundler. Translation = typeof en describes the shape, which leaves two things that type-check perfectly and still break on screen: a leaf that is undefined at runtime, and a parameterised string that throws when called - which takes the screen down rather than showing the wrong words.

test/locale-runtime.test.mjs transpiles both locales with ts.transpileModule (one call, no bundler, typescript is already a devDependency - both files are self-contained once types are stripped) and walks every leaf. Each function is called twice, with 1 and with 0, because the duration builders branch on each part being truthy and 0 is the path a drained balance hits. plural is pinned directly on the numbers that separate its three forms, including 11, which takes the third despite ending in 1 and is exactly what a naive n % 10 === 1 rule gets wrong.

Verified by breaking it both ways - a leaf written as undefined as unknown as string and a function made to throw, each reported by key.

Final: 840 passing checks, both typecheck configs, eslint, production bundle.

🤖 Generated with Claude Code

[gitar-bot]

Gitar is working

_Gitar