# Add i18n to a Chrome Extension from a Linear Issue

Yes. An agent moves every string into _locales message files, wires chrome.i18n through a typed helper, localises the manifest, builds and tests it, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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

- [Add Keyboard Shortcuts to a Chrome Extension](https://getrush.ai/run/add-keyboard-shortcuts/chrome-extension/)
- [Add Desktop Notifications to a Chrome Extension](https://getrush.ai/run/add-notifications/chrome-extension/)
- [Add a Release Workflow for a Chrome Extension](https://getrush.ai/run/add-release-workflow/chrome-extension/)

## The same job on other stacks

- [Add i18n to a CodeIgniter 4 App](https://getrush.ai/run/add-i18n/codeigniter/)
- [Add i18n to a Docusaurus Site](https://getrush.ai/run/add-i18n/docusaurus/)
- [Add i18n to an Electron App from a Linear Issue](https://getrush.ai/run/add-i18n/electron/)

## 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/)
