# Add i18n to an Electron App from a Linear Issue

Yes. An agent adds i18next to the renderer and the main process of your Electron app, moves menu and UI strings into locale files, tests key parity, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/electron/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads where the strings live before it picks a library. In an app shaped like electron-react-boilerplate, `package.json` builds with `electron-vite` 5 on Electron 44, React 19 and `react-router-dom` 7, tests with Jest 30 in a `jsdom` environment through `jest.config.js`, and has no i18n dependency. The renderer's text is all in `src/renderer/App.tsx`: the heading, the two button labels and the `aria-label` values on the emoji spans. The main process has its own text in `src/main/menu.ts`, where `MenuBuilder` writes `Learn More`, `Documentation`, `Community Discussions` and `Search Issues` into the Help submenu and `&File` and `&View` into the default template, while the `appMenu`, `editMenu` and `windowMenu` roles are translated by Electron itself and need nothing. `src/main/preload.ts` exposes `ipcRenderer` through `contextBridge` with a `Channels` type that allows only `ipc-example`, and `src/renderer/index.html` hardcodes `lang` as English.

It adds `i18next` and `react-i18next` to `package.json` and a `src/locales/` directory with one `translation.json` per locale, English first plus the locales the Linear issue names. The renderer gets `src/renderer/i18n.ts`, which initialises i18next with the JSON files, which `electron-vite` bundles as modules, and is imported once from `src/renderer/index.tsx`; `App.tsx` reads its strings with `useTranslation()`, including the two `aria-label` values, so a screen reader hears the same language as the screen. The main process cannot use React hooks, so `src/main/i18n.ts` creates a separate i18next instance from the same JSON files, and `MenuBuilder` takes a `t` function and uses it for every literal label in `buildDarwinTemplate` and `buildDefaultTemplate`, keeping the `&` accelerator marks in the English and German values.

The locale comes from Electron, not from the browser. After `app.whenReady()` in `src/main/main.ts`, the agent reads `app.getLocale()`, initialises the main instance with it and builds the menu, and adds a `get-locale` channel to the `Channels` union in `preload.ts` with an `ipcMain.handle` in `main.ts`, so the renderer asks for the locale before it renders and falls back to English for a language with no file. It sets `document.documentElement.lang` from the same value so `index.html` no longer claims English for a German window. Unknown locales fall back through i18next's `fallbackLng`.

Tests stay in Jest. `src/__tests__/App.test.tsx`, which finds the heading by its English name and the two links by their text, keeps passing because the test setup initialises i18next with `lng: 'en'` in a new `src/__tests__/setup-i18n.ts` added to `setupFiles` in `jest.config.js`, beside the existing `check-build-exists.ts`. A new `src/__tests__/locales.test.ts` loads every `translation.json` and asserts each has exactly the keys of the English file, so a forgotten string fails the suite rather than showing an English fallback. The agent then runs what `.github/workflows/test.yml` runs: `npm run package`, `npm run lint`, `npm exec tsc -- --noEmit`, `npm test`, and the smoke test under `xvfb-run` on Linux, and starts the packaged app with `LANG` set to a second locale to see the translated menu in its own display.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add internationalisation to this Electron app with i18next and open a pull request. Read package.json, electron.vite.config.ts, jest.config.js, src/main/main.ts, src/main/menu.ts, src/main/preload.ts, src/renderer/index.tsx, src/renderer/index.html, src/renderer/App.tsx, src/__tests__/App.test.tsx and .github/workflows/test.yml first. Add i18next and react-i18next. Create src/locales/<locale>/translation.json for English and for each locale the issue names, and move every literal string in App.tsx, including the aria-label values, and every literal menu label in menu.ts into those files; leave role-based menu items alone because Electron translates them. Add src/renderer/i18n.ts imported once from index.tsx and used through useTranslation() in App.tsx, and a separate src/main/i18n.ts instance for the main process; make MenuBuilder take a t function. Read the locale with app.getLocale() after whenReady, build the menu with it, add a get-locale channel to the Channels type in preload.ts with an ipcMain.handle in main.ts, and set document.documentElement.lang in the renderer. Fall back to English for any other locale. Add a setup file to jest.config.js that initialises i18next with lng en so App.test.tsx keeps passing, and add src/__tests__/locales.test.ts asserting every locale file has exactly the keys of the English one. Run npm run package, npm run lint, npm exec tsc -- --noEmit, npm test and the smoke test, start the packaged app with a second locale and check the menu, and paste the output in the pull request. Do not change the auto-updater, the window setup or any dependency version.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with `i18next` and `react-i18next` in `package.json` and `package-lock.json`, the `src/locales/` directory with one `translation.json` per locale, `src/renderer/i18n.ts` and `src/main/i18n.ts`, a `t`-driven `src/main/menu.ts`, the `get-locale` channel in `src/main/preload.ts` and `src/main/main.ts`, `App.tsx` using `useTranslation()`, the Jest setup file and the new key-parity test. The description shows a screenshot of the translated Help menu from the sandbox and the output of the package, lint, type-check, test and smoke commands.

The `Test` workflow runs those same steps on macOS, Windows and Ubuntu on the pull request, so the packaged build, ESLint, `tsc` and Jest have all passed on three platforms before a reviewer opens it. The agent pushes one commit for the dependency and locale files, one for the renderer, and one for the main process and tests.

A reviewer checks that no literal string is left in `App.tsx` or in the non-role items of `menu.ts`, that the `&` accelerators survive in each translated label, that `aria-label` values are translated, that the `Channels` type still rejects an unknown channel, and that a locale without a file falls back to English rather than showing keys. Then they merge and add locales by adding one JSON file, which the parity test keeps complete.

## Run it on every Linear issue labelled agent

Connect Linear once under Settings → Connections, then add an automation to the Project that holds the app with this prompt and a `linear` trigger on `linear.issue.labeled`, naming the label in `config.labels`. The trigger appends the labelled issue after the prompt and fills in no placeholder, so the agent reads the locales to add from the issue text. Each labelled issue starts its own run in its own sandbox and ends in its own pull request, up to the automation's `max_runs_per_hour`.

A later issue asking for one more language fits the same automation: the agent reads `src/locales/en/translation.json`, adds the new file and the parity test keeps it complete. From your own server, a handler that receives Linear's webhook sends `POST /o/{org}/sessions` with the repository and the issue URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered webhook returns the run it already started.

## Why run it on Rush?

Internationalising a desktop app is a long mechanical pass over two processes with different rules, and the only real check is to package the app, start it under another locale and look at the window and the native menu. On a laptop that means a second system language and a rebuild per change. In a Rush sandbox the agent packages, launches the app in its own display with a second locale, screenshots the menu and keeps the picture beside the test output in the transcript.

The result passes the repository's own three-platform workflow before a reviewer opens it, and the parity test turns every future locale into a one-file change. The same request works unchanged for any Electron app whose strings live in a React renderer and a `Menu.buildFromTemplate` call.

## Frequently asked questions

### Why two i18next instances?

The renderer and the main process are separate JavaScript contexts with no shared memory. `react-i18next` belongs in the renderer where React runs; the menu is built in the main process from `menu.ts` before any window content exists. Both instances load the same JSON files, so there is one source of strings.

### Why not translate the Edit and Window menus?

Those are built with `role: 'editMenu'`, `role: 'windowMenu'` and `role: 'appMenu'`, which Electron labels in the system language itself. Translating them by hand would duplicate work and drift from the OS. Only the literal labels in `menu.ts` move into the locale files.

### Will App.test.tsx still pass?

Yes. It finds the heading and links by their English text, and the new Jest setup file initialises i18next synchronously with `lng: 'en'` and the bundled resources before each test file runs, so the rendered output is the same English the test expects.

### How does the renderer learn the locale?

The main process reads `app.getLocale()` and answers a `get-locale` request over IPC through the preload bridge; the renderer awaits that before its first render and passes it to `i18next.changeLanguage`. Reading `navigator.language` in the renderer would work too, but it reflects Chromium's language rather than the one Electron reports.

## More Electron jobs

- [Add Keyboard Shortcuts to an Electron App from a Linear Issue](https://getrush.ai/run/add-keyboard-shortcuts/electron/)
- [Add a Local SQLite Database to an Electron App](https://getrush.ai/run/add-local-database/electron/)
- [Add Desktop Notifications to an Electron App](https://getrush.ai/run/add-notifications/electron/)

## The same job on other stacks

- [Add i18n to an Eleventy Blog](https://getrush.ai/run/add-i18n/eleventy/)
- [Add i18n to an Expo App](https://getrush.ai/run/add-i18n/expo/)
- [Add Internationalisation to a Filament Admin Panel from a Linear Issue](https://getrush.ai/run/add-i18n/filament/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
