Add a language setting, applied at the next launch

[zaerl]

Why

Second part of #559, on the dialog of #638. The app is translatable (#540) and picks its language from the operating system's; a contributor on a machine set to a language they do not read, or at a shared laptop, had no way to choose. This adds the language to the settings.

What changes

Language, on the General tab. Your system's language, which is the default, or English, or any language the build ships a catalog for, each named in its own language ("Deutsch", "Português (Brasil)") so that someone looking for theirs finds it whatever the app is showing. The list is what src/languages/ holds, so it grows as releases ship catalogs; today that is English.

Where it is read. Main puts the chosen language in front of the OS's languages and loads the first one with a catalog, as it walked the OS's before. In front, not in their place: a chosen language whose catalog a later release dropped falls back to the OS's language, not to English. The --lang switch still replaces the whole list; it is how the journeys pick a locale, and a flag typed at launch is a decision.

A change applies after a relaunch, since main applies the catalog as it starts, for its own strings and the window's. The dialog says so once what is set is no longer what the window started in, and offers Relaunch now: a quit and a start, so the quit sweep ends every child the app started, as it does on any quit. The new instance gets this one's arguments less a wpct:// address a cold start was given, which is not a second request for its ticket, and a --lang, which would outrank the language just chosen; on Linux it is started from the AppImage, since the mounted copy is gone once this one quits.

The first read of the store is now before the window exists. One that cannot be read is logged and counts as no choice, so the window still opens; every later read then fails as it did before.

Beside it: the catalogs' README and CONTRIBUTING.md say where the language comes from now; a journey can launch without --lang, as the app launches for a contributor.

Not in this pull request:

• Switching the language without a relaunch. Main applies the catalog once, at startup, for its own strings; the window would need a second path, and the menu and the native dialogs a third.
• The slugs no operating system reports (pirate, art-xemoji), which are not offered, as they could not be picked from the OS list either.
• The rest of Settings dialog with what exists and all new settings #559: the PHP version and the debug flags, what starts when a site opens and what happens on quit, the theme (Add dark mode #560).

How to test this

Platforms: any. The journeys drive this on macOS and Windows. From the repository root, after npm ci and npm run build:once:

npx playwright test --project=journeys settings.spec i18n.spec

• settings.spec.js, the language journey: the pseudo-locale set in the store, with no --lang, is the language the app starts in; the control shows it though the build has no catalog for it; English chosen is kept at once and the dialog offers the relaunch, which asks main; the system's language chosen is kept as none and the offer stays; the pseudo-locale chosen again is refused, since the build has no catalog for it; started again with English kept, the app is in English and the control says so with no offer.
• i18n.spec.js: the dialog with the control, in the pseudo-locale.

I broke two of the journey's claims one at a time (main not reading the chosen language; the relaunch button asking nothing of main) and each turned it red. tests/unit/i18n.test.cjs holds the list, settings.test.cjs what is accepted, settings-view.test.cjs the control's entries and when the relaunch is offered, and ipc-wiring.test.cjs the order the languages are tried in, the store that cannot be read, and what the relaunch is given.

Worth a look by hand (any platform, the current head): Settings → General → Language: with no catalog shipped the list is your system's language and English. Choose English, press Relaunch now: the app quits and comes back, the control says English and offers nothing. Choose your system's language, press the cog's relaunch again: as before. With npm run i18n:download -- --locales=de run first (it needs the network), "Deutsch" is in the list, and chosen and relaunched, the app is in German where it is translated.

What must not have happened: a running server or build left behind by the relaunch (the quit sweep ends them, as on any quit); a wpct:// ticket opened again after a relaunch of an app that was started from a link (Windows and Linux); the app failing to open a window when settings.json is not JSON.

What I could not test: Linux, where the relaunch is started from the AppImage; the unit test pins what Electron is told, not that the image starts. And a real catalog in the dialog: the repository ships none, and I did not run the download.

Risks and limitations

• Review: 2 passes, 4 findings fixed here, 1 follow-up taken here. Details below.
• The language names are not translated, by design: each is in its own language.
• A store that cannot be read lets the window open but every later read fails as it did before this change; the app does not say which file is at fault.
• The relaunch is a quit: nothing asks first, as nothing asks on ⌘Q.

Related

Part of #559, which is part of #542. Follows #638. Translations: #540.

---

Design decisions and alternatives considered

• A relaunch, not a live switch. Main applies the locale once, at startup, for the menu, the native dialogs and the sentences it sends, and the window reads its catalog before its first render; three paths to re-run for a setting changed a few times in the app's life. The dialog says what the relaunch costs.
• The chosen language in front of the OS's, not in their place. A release drops a catalog that fell under the cut-off; the contributor who chose it should get their OS's language, as they did before choosing.
• The control's entries with their tags as values, drawn by the dialog, and the list also handed over for the names. Handed the list alone, the design system's select takes each entry as its own value and tells them apart by identity, which a value kept in the store cannot match.
• Entries made from the language the window started in, not the one set, so that a choice does not change them: an entry taken away under the control while it is choosing is reported as a second choice, of none. A language the window started in that the build has no catalog for is listed, so the control shows what is set, and refused if chosen again.
• The quit sweep over app.exit. The relaunch goes through app.quit() so every child the app started is ended first.

Review outcome (required — see AGENTS.md)

Pass 1: 3 [fix here] · 0 [follow-up] · 4 style notes. Pass 2 (on the fix-up): 1 [fix here] · 1 [follow-up] · 1 style note. All 4 fixed, the follow-up taken here, every style note applied.

• Review: completed — a separate agent context, read-only; head 82aac18 / base fe02e6b; the store read traced from whenReady, the relaunch against Electron's quit events and the single-instance lock, the language names checked on ICU for lowercase tags and Valencian, the select's value handling read in the design system's source, the journey read against the standard; ESLint, the unit files and the pot extraction run; 3 [fix here].
  • Fixed: a store that could not be read would have stopped the window opening, since the locale is resolved before it; a chosen language replaced the OS list, so one whose catalog was dropped gave English rather than the OS's language; the relaunch reused the launch's arguments, a wpct:// address and a --lang included.
  • Style notes, applied: a stale comment in the store module; a silent catch on the relaunch; the system entry's mapping as a tested function; the catalogs' README counting entries not offered; a journey comment.
• Review: completed — a second separate agent context, read-only; head 7eab0b6 / base fe02e6b; the fallback order followed through resolveCatalog for each case, the relaunch arguments against Electron's documented default and a dev launch, the three changed wiring tests confirmed red on the first commit; ESLint and the unit files run; 1 [fix here], 1 [follow-up].
  • Fixed: the README still described the chosen language as used instead of the OS's rather than before them.
  • Follow-up, taken here: on Linux the relaunch would start from the AppImage's mount, which is gone once the app quits; the new instance is started from the image.
  • Style note, applied: one comment line left unwrapped.
• Since review: 7eab0b6 → b68f7c2 is that finding, the follow-up and the rewrap, not reviewed again. On the head: npm run lint, npm test, npm run test:electron, the settings, i18n and create-site journeys and the packaged smoke pass; all 118 journeys passed on 82aac18.

Implementation notes

• src/i18n.cjs: languageChoices(names). src/settings.cjs: locale. src/main.js: localeReply reads the store, languages(), i18n:languages, app:relaunch, relaunchArgs. src/preload.js: listLanguages, relaunch.
• src/renderer/settings-view.cjs: languageItems, languageValue, languageChanged, SYSTEM_LANGUAGE. src/renderer/components/settings-dialog.jsx: LanguageControl. src/renderer/hooks/use-settings.jsx: loaded.
• tests/e2e/helpers/app.cjs: lang: false drops the --lang switch.

Screenshots or recording

Not attached: I have no way to upload images from the command line. The language journey drives everything that changed.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: WordPress/contributor-toolkit/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: a256f064-9147-4ddb-8fc8-e976ffb2dea4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}