What the agent does
The agent reads what the extension says and where it says it. In a project shaped like chibat/chrome-extension-typescript-starter, public/manifest.json is Manifest V3 with a literal name and description, an options_ui page, an action popup, a content script on <all_urls>, a background service worker and the storage permission, and no default_locale. src/popup.tsx renders "Current URL", "Current Time", "count up" and "change background" as string literals in React 18; src/options.tsx renders "Favorite color", four colour option labels, "I like colors.", "Save" and the "Options saved." status. webpack/webpack.common.js builds four entries with ts-loader and copies public/ into dist/, so a _locales directory under public/ ships with the build.
The checks are small and the agent keeps them passing. npm run build runs the production webpack config, npm test runs Jest with ts-jest over src/, where src/__tests__/sum.ts is the only test, and .github/workflows/build.yml runs npm ci, npm run build and npm test on Node 20 and 22 for every pull request. @types/chrome is pinned at 0.0.158, which already types chrome.i18n.getMessage and chrome.i18n.getUILanguage.
The agent creates public/_locales/en/messages.json with one entry per string, named for where it appears (popupCurrentUrl, optionsSave, extName), plus a messages.json for each locale the issue names, and sets default_locale to en in the manifest while replacing name and description with __MSG_extName__ and __MSG_extDescription__. A src/i18n.ts exports a t() helper over chrome.i18n.getMessage whose key parameter is a union type derived from the English file with a resolveJsonModule import, so a key that does not exist is a compile error rather than an empty string at runtime. popup.tsx and options.tsx call t() for every literal, and the time in the popup is formatted with toLocaleTimeString(chrome.i18n.getUILanguage()) so it follows the browser's locale too.
Two tests go beside sum.ts: one that loads every _locales/*/messages.json and asserts each has exactly the keys of en, so a translation cannot fall behind silently, and one that stubs chrome.i18n.getMessage and checks t() passes the key and substitutions through. The agent runs npm run build and npm test, then starts a Chromium in the sandbox with --load-extension=dist and --lang set to the second locale, opens the popup and options pages by the extension's id, and checks the rendered text before it opens the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labelled agent asks for internationalisation of the extension: every user-facing string in the popup, the options page and the manifest comes from _locales message files, English is the default, and the locales named in the issue are added. Read public/manifest.json, public/popup.html, public/options.html, src/popup.tsx, src/options.tsx, src/content_script.tsx, src/background.ts, webpack/webpack.common.js, package.json, jest.config.js and .github/workflows/build.yml first. Create public/_locales/en/messages.json with a named entry per string and a file per extra locale, set default_locale and use __MSG_ keys for the manifest name and description, add src/i18n.ts with a t() helper over chrome.i18n.getMessage whose keys are typed from the English file, replace every literal in popup.tsx and options.tsx, and format the popup time with the UI language. Add a Jest test that every locale has the same keys as en and one for the helper. Run npm run build and npm test, load dist as an unpacked extension in a Chromium started with the second locale, open the popup and options pages and check the strings, and open a pull request that links the issue and lists the message keys.",
"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 on its own branch. It adds public/_locales/<locale>/messages.json for English and each locale from the issue, src/i18n.ts, and two tests under src/__tests__; it changes public/manifest.json (default_locale, __MSG_extName__, __MSG_extDescription__), src/popup.tsx and src/options.tsx, and tsconfig.json if resolveJsonModule was not already on. src/background.ts, src/content_script.tsx and the webpack config are untouched. The description lists every message key with its English text and quotes the issue.
The checks are the proof. The repository's build workflow runs npm ci, npm run build and npm test on Node 20 and 22 for the pull request, so a missing key in one locale fails the new test there. The trajectory at GET /o/{org}/sessions/{id}/messages keeps the build output, the Jest run and the popup and options pages as rendered under the second locale, so a reviewer reads what the extension showed rather than trusting a description.
Before merging, a reviewer reads the translations themselves, since the agent's wording in a language the team does not speak is a draft, and decides whether the Web Store listing should use the same name and description. The extension is not published anywhere by the run.
Run it on every Linear issue labelled agent
Sign in to Linear once from Settings → Connections, then add an automation to the Project that holds the extension 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 that adds one more locale fits the same automation: the agent reads _locales/en/messages.json, adds the new file, and the key-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 an extension is a long mechanical pass over every literal, and the only way to know it worked is to build, load the unpacked extension in a browser running under another locale and look at the popup and the options page. On a laptop that means a second Chrome profile and a reload after every change. In a Rush sandbox the agent builds, starts its own Chromium with --load-extension and --lang, opens the pages, reads them and fixes what is wrong before anyone else looks.
The pull request carries its proof: the repository's own workflow builds and tests it on two Node versions, and the transcript keeps the rendered pages beside the commands. Each locale the team adds later is one more issue, one more sandbox and one more pull request, and the key-parity test keeps every file complete.
Frequently asked questions
Does it add an i18n library?
No. Chrome extensions have chrome.i18n built in, and _locales/<locale>/messages.json is the format the browser reads for the manifest and for getMessage. The one new file in src/ is a small typed helper so a misspelled key fails tsc in the webpack build instead of rendering an empty string.
Which locale does the browser use?
The browser's own UI language, matched against the folders under _locales, falling back to default_locale. That is why the agent sets default_locale to en and starts a Chromium with --lang set to the second locale to check the other path. A user cannot pick a language inside the extension unless you ask for a selector in the options page, which is a follow-up issue.
What about the content script and the background worker?
In this starter they contain no user-facing text, so they are left alone; chrome.i18n.getMessage works in both if a later change needs it. The agent lists which files it changed and which it read and left as they were.
How do I know a translation file is complete?
A new Jest test loads every _locales/*/messages.json and asserts the key set equals the English one, so an entry added to en without a translation fails npm test locally and in the build workflow. The typed t() helper covers the other direction: a key used in code that is not in en fails the build.
More Chrome extension jobs
The same job on other stacks
- Add i18n to a CodeIgniter 4 App (CodeIgniter)
- Add i18n to a Docusaurus Site (Docusaurus)
- Add i18n to an Electron App from a Linear Issue (Electron)