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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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.